AEGIS Examples

Example agents and workflows for AEGIS.

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.