Skip to content

Latest commit

 

History

History
391 lines (285 loc) · 11.6 KB

README.md

File metadata and controls

391 lines (285 loc) · 11.6 KB

AEGIS Examples

Example agents and workflows for AEGIS.

License

Initialize AEGIS locally

Initialize your local AEGIS stack with aegis init, then use this repository for deployable examples.

git clone https://github.com/100monkeys-ai/aegis-examples.git

# Install AEGIS
curl -fsSL https://raw.githubusercontent.com/100monkeys-ai/aegis-examples/main/install.sh | bash

# Initialize local stack and config
aegis init

# Clone examples and deploy one
cd aegis-examples

# Deploy and run the hello-world example
aegis agent deploy ./agents/hello-world/agent.yaml
aegis task execute hello-world \
  --input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}' \
  --follow

See the Getting Started guide for a step-by-step walkthrough.

Overview

This repository contains ready-to-run example agents that showcase:

  • MCP tool integration
  • Security policy configuration
  • Memory system (Cortex) usage
  • Best practices for agent development

Examples

0. Hello World

Location: agents/hello-world/

The introductory agent. Writes a Python function, tests it, and iteratively refines it until all tests pass. Used in the Getting Started guide.

Features:

  • Iterative refinement loop (100monkeys algorithm)
  • fs.write and cmd.run tool usage
  • Gradient validation (0.0–1.0 quality score)

Run:

aegis agent deploy ./agents/hello-world/agent.yaml
aegis task execute hello-world \
  --input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}' \
  --follow

1. Email Summarizer

Location: agents/email-summarizer/

Connects to Gmail and generates AI-powered email summaries.

Features:

  • Gmail MCP integration
  • OpenAI GPT-4 summarization
  • Persistent memory for learning user preferences

Run:

aegis run agents/email-summarizer/agent.yaml

2. Web Researcher

Location: agents/web-researcher/

Performs deep research on any topic by searching, reading, and synthesizing information.

Features:

  • Web search via MCP
  • Multi-source article reading
  • Comprehensive report generation

Run:

aegis run agents/web-researcher/agent.yaml

3. Code Reviewer

Location: agents/code-reviewer/

Reviews pull requests for security issues, code quality, and best practices.

Features:

  • GitHub MCP integration
  • Security vulnerability detection
  • Best practice recommendations

Run:

aegis run agents/code-reviewer/agent.yaml

Workflow Examples

Multi-agent pipelines are defined in agents/workflows/. Each file is a complete, deployable Workflow Manifest.

File Pattern Description
100monkeys-classic.yaml Iterative refinement Generate → execute → judge-validate → refine loop using the Blackboard for iteration state.
the-forge.yaml Constitutional pipeline Full RequirementsAI → ArchitectAI → TesterAI → CoderAI → parallel audit → human gate → deploy lifecycle.
stateful-pipeline.yaml Blackboard accumulation Three-state example showing all three Blackboard population methods: spec.context seeding, automatic state-output writes, and explicit update_blackboard System states. Start here if you're learning the Blackboard.
echo-workflow.yaml Minimal Two-state echo workflow demonstrating {{workflow.context.KEY}} access.
agent-workflow.yaml Minimal Two-state workflow with a System state reading an Agent output.
human-approval.yaml Human-in-the-loop Three-state workflow with a Human gate and signal resumption.
multi-judge.yaml Parallel validation ParallelAgents state with weighted-average consensus.
multi-judge-majority.yaml Parallel validation ParallelAgents with majority-vote consensus strategy.
multi-judge-unanimous.yaml Parallel validation ParallelAgents with unanimous-approval gate.
multi-judge-best-of-n.yaml Parallel validation ParallelAgents with best-of-N consensus — for grading and ranking tasks.

Deploy and run a workflow:

# Deploy
aegis workflow deploy ./agents/workflows/stateful-pipeline.yaml

# Start with input
aegis workflow start stateful-pipeline --input '{"task": "quantum entanglement", "max_words": 150}'

# Monitor
aegis workflow status <execution-id> --follow

See the Workflow Manifest Reference and the Building Workflows guide for full documentation.

Getting Started

Prerequisites

  • Docker 24.0+ and Docker Compose v2.20+ — required by aegis init
  • AEGIS CLI — install with: curl -fsSL https://raw.githubusercontent.com/100monkeys-ai/aegis-examples/main/install.sh | bash
  • Python 3.11+ — for Python-based agents
  • API keys for the services you want to use (OpenAI, GitHub, etc.)

Running an Example

  1. Install AEGIS and initialize your local stack:

    curl -fsSL https://raw.githubusercontent.com/100monkeys-ai/aegis-examples/main/install.sh | bash
aegis init

  2. Clone this examples repository:

    git clone https://github.com/100monkeys-ai/aegis-examples
cd aegis-examples

  3. Deploy and run an agent:

    # Start with the hello-world example — no API keys required with local Ollama
aegis agent deploy ./agents/hello-world/agent.yaml
aegis task execute hello-world \
  --input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}' \
  --follow

Creating Your Own Agent

AEGIS agents are manifest-only — there is no agent-side Python script. The orchestrator drives the LLM using the task.instruction you provide, and the LLM accomplishes the task through tool calls (fs.write, cmd.run, mcp:*, etc.). You declare what the agent can do; the runtime figures out how.

  1. Create a directory:

    mkdir my-agent
cd my-agent

  2. Create agent.yaml:

    apiVersion: 100monkeys.ai/v1
kind: Agent

metadata:
  name: "my-agent"
  version: "1.0.0"
  description: "Brief description of what this agent does"

spec:
  runtime:
    language: "python"
    version: "3.11"
    isolation: "inherit"

  task:
    instruction: |
      Describe the agent\'s behaviour here as a clear, natural-language
      instruction. The orchestrator uses this as the system prompt for the
      iterative LLM loop. Be specific about inputs, outputs, and quality
      criteria.

  execution:
    mode: "iterative"
    max_iterations: 5
    memory: false

    validation:
      semantic:
        enabled: true
        threshold: 0.85
        prompt: |
          Assess whether the agent successfully completed the task.

  security:
    network:
      mode: "allow"
      allowlist: []  # Add external domains only if your tools need them
    filesystem:
      read: ["/workspace"]
      write: ["/workspace"]
    resources:
      cpu: 500
      memory: "512Mi"
      timeout: "120s"

  tools:
    - "fs.write"
    - "fs.read"
    - "cmd.run"

  3. Deploy and run:

    aegis agent deploy ./my-agent/agent.yaml
aegis task execute my-agent --input '{"task": "Your task here"}' --follow

Agent Manifest Reference

AEGIS manifests follow a Kubernetes-style apiVersion/kind/metadata/spec schema. There is no agent-side script — the orchestrator drives the LLM using spec.task.instruction.

Metadata

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: "agent-name"     # Unique identifier, used as value
  version: "1.0.0"
  description: "What this agent does"
  labels:
    role: "worker"       # worker | judge | critic | router
    category: "demo"

Runtime

spec:
  runtime:
    language: "python"   # Execution environment
    version: "3.11"
    isolation: "inherit" # inherit (Docker) | microvm (Firecracker)

Task

  task:
    instruction: |
      Natural-language description of the agent's goal.
      The orchestrator uses this as the system prompt for the LLM.
      Be specific: describe inputs, expected outputs, and quality bar.
    prompt_template: |
      {{instruction}}
      User: {{input}}

Execution

  execution:
    mode: "iterative"    # iterative = 100monkeys refinement loop
    max_iterations: 5
    memory: false        # true = enable Cortex persistent memory

    validation:
      semantic:
        enabled: true
        threshold: 0.85  # 0.0–1.0; score below this triggers refinement
        prompt: |
          Assess whether the agent successfully completed the task.

Security

  security:
    network:
      mode: "allow"
      allowlist:
        # List only domains your MCP tool servers need to reach.
        # Do NOT add api.openai.com or any LLM endpoint here —
        # the orchestrator handles all LLM routing.
        - "api.github.com"
    filesystem:
      read: ["/workspace"]
      write: ["/workspace"]
    resources:
      cpu: 500           # millicores (500 = 0.5 core)
      memory: "512Mi"
      timeout: "120s"

Tools

  tools:
    - "fs.write"         # Write files in the agent container
    - "fs.read"          # Read files in the agent container
    - "cmd.run"          # Execute shell commands in the container
    - "mcp:gmail"        # Gmail integration (tool server on orchestrator host)
    - "mcp:github"       # GitHub API
    - "mcp:browser"      # Web browsing
    - "mcp:search"       # Web search

Secrets (for MCP tool servers)

  # Secrets listed here are resolved from OpenBao by the orchestrator and
  # injected into MCP tool server processes on the orchestrator host.
  # They are NOT exposed inside the agent container.
  env:
    GITHUB_TOKEN: "secret:github-token"
    GMAIL_CREDENTIALS: "secret:gmail-oauth"

Security Best Practices

  1. Minimal Permissions: Only request necessary network/filesystem access
  2. Use Secrets: Never hardcode API keys; use secret: references
  3. Resource Limits: Set appropriate CPU and memory limits
  4. Tool Scoping: Only include required MCP tools

Schema Validation

All manifests are validated against schemas/agent-manifest.schema.json.

Contributing

We welcome new examples! Please:

  1. Follow the existing structure
  2. Include a README in your example directory
  3. Test locally before submitting
  4. Add appropriate comments

License

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details.

Learn by example. Build with confidence.