Writing Your First Agent

In AEGIS, agents are created declaratively with a kind: Agent manifest. You define behavior, security, tools, and validation in YAML, then deploy it with the CLI.

This guide walks through the default and recommended path:

Write agent.yaml
Deploy the manifest
Execute a task
Tune validation and permissions

No custom bootstrap.py is required for this flow.

Prerequisites

AEGIS daemon running locally (see Getting Started)
A working aegis CLI installation

Step 1: Create the Project Structure

my-agent/
├── agent.yaml

Step 2: Write the Agent Manifest

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: python-coder
  version: "1.0.0"
  description: "Writes Python solutions to programming tasks."
  labels:
    role: worker
    team: platform
  tags:
    - code-generation
    - python
    - task-solving
spec:
  runtime:
    language: python
    version: "3.11"
    isolation: inherit

  task:
    instruction: |
      Review the provided pull request diff and return structured feedback.
      Include findings for security, performance, and maintainability.
      Return JSON with keys: summary, risks, recommendations.
    prompt_template: |
      {{instruction}}

      Pull request context:
      {{input}}

      Assistant:

  security:
    network:
      mode: allow
      allowlist:
        - api.github.com
    filesystem:
      read:
        - /workspace
      write:
        - /workspace/output
    resources:
      cpu: 1000
      memory: "1Gi"
      timeout: "300s"

  volumes:
    - name: workspace
      storage_class: ephemeral
      mount_path: /workspace
      access_mode: read-write
      ttl_hours: 1
      size_limit: "5Gi"

  execution:
    mode: iterative
    max_iterations: 5
    validation:
      system:
        must_succeed: true
      output:
        format: json
        schema:
          type: object
          required: ["summary", "risks", "recommendations"]
          properties:
            summary:
              type: string
            risks:
              type: array
              items:
                type: string
            recommendations:
              type: string

  tools:
    - name: filesystem
      server: "mcp:filesystem"
      config:
        allowed_paths: ["/workspace"]
        access_mode: read-write

The metadata.description field is a human-readable summary of what the agent does. It is used by the discovery service to build the semantic embedding for this agent, so write it to reflect capability and intent — not implementation details.

metadata:
  name: my-agent
  version: "1.0.0"
  description: "Audits Python code for security vulnerabilities and OWASP compliance."
  labels:
    role: worker
    category: security

Declaring structured inputs with `input_schema`

If your agent accepts structured inputs — named fields beyond a free-form string — declare them in spec.input_schema. This tells callers exactly what to pass and lets the orchestrator validate the input before the agent runs.

spec:
  input_schema:
    type: object
    properties:
      repo_url:
        type: string
        description: GitHub repository URL to analyze
      dry_run:
        type: boolean
    required:
      - repo_url

Callers then pass --input '{"repo_url": "https://github.com/org/repo", "dry_run": false}' instead of a plain string. See the Agent Manifest Reference for the full field specification.

Step 3: Deploy the Agent

aegis agent deploy ./my-agent/agent.yaml

Confirm registration:

aegis agent show python-coder

Step 4: Execute a Task

Run an execution and stream iterations:

aegis task execute \
  python-coder \
  --input 'Write a Python function that returns the Fibonacci sequence up to n.' \
  --follow

If validation fails, AEGIS automatically refines and retries up to max_iterations.

Step 5: Tighten Security and Validation

After your first successful run:

Restrict spec.security.network.allowlist to only required domains.
Restrict spec.security.filesystem.read/write to minimal paths.
Add or tighten spec.execution.validation.output.schema rules.
Lower max_iterations when your agent behavior is stable.

Common Issues

Symptom	Cause	Fix
Tool call rejected	Tool not declared in `spec.tools`	Add the MCP tool entry under `spec.tools`
Validation fails repeatedly	Output schema too strict or mismatched	Align the schema with expected output shape
Execution times out	Resource timeout too low	Increase `spec.security.resources.timeout` and/or validation timeouts
Network denied	Domain missing from allowlist	Add required host to `spec.security.network.allowlist`