docs

agentfile.yaml

agentfile.yaml is the single source of truth for your agent — its identity, model, tools, memory, triggers, and governance rules. Think of it as a Dockerfile for AI agents.

Full example

agentfile.yaml
# Global defaults (can be overridden per agent)
governance:
  max_budget_per_run: 0.50        # USD
  human_approval:
    enabled: true
    actions: [file_write, send_email]

triggers:
  - type: webhook
    endpoint: /run
  - type: schedule
    cron: "0 9 * * MON-FRI"
    message: "Generate daily status report"

agents:
  orchestrator:
    metadata:
      role: Task coordinator
      goal: Break down complex tasks and delegate to specialists
      instructions: |
        You are a coordinator. Analyze the request, create a plan,
        and delegate subtasks to the researcher or writer agent.
      constraints:
        - Never delete files without explicit confirmation
        - Always summarize what was accomplished at the end

    runtime:
      provider: anthropic
      model: claude-sonnet-4-6
      temperature: 0.3

    collaborators: [researcher, writer]

    execution:
      mode: planned          # generate a plan first, then execute
      verify_steps: true
      max_steps: 15

  researcher:
    metadata:
      role: Web researcher
      goal: Find accurate, up-to-date information from the web

    runtime:
      provider: anthropic
      model: claude-haiku-4-5-20251001
      temperature: 0.1

    tools:
      - name: web_search
        source: mcp://brave-search
      - name: github
        source: mcp://github

  writer:
    metadata:
      role: Content writer
      goal: Write clear, well-structured documents

    runtime:
      provider: openai          # mix providers freely
      model: gpt-4o
      temperature: 0.2

    tools:
      - name: filesystem
        source: mcp://filesystem

Structure

The file has two levels: global (top-level keys) and per-agent (under agents:). Per-agent settings override globals.

KeyLevelRequiredDescription
agentsglobalyesMap of agent definitions. First key is the entry agent.
governanceglobal / agentnoBudget limits and approval gates
triggersglobal / agentnoWebhook and schedule triggers

agents block

KeyRequiredDescription
metadata.roleyesOne-line role description injected into the system prompt
metadata.goalyesWhat the agent is trying to accomplish
metadata.instructionsnoMulti-line behavior instructions
metadata.constraintsnoList of hard rules (e.g. "never delete files")
runtime.provideryesanthropic | openai | google | deepseek | mistral | groq | together_ai | openrouter | cerebras | fireworks_ai | bedrock | azure | minimax
runtime.modelyesModel ID string (e.g. claude-sonnet-4-6, gpt-4o)
runtime.temperaturenoFloat 0.0–2.0, default 0.2
toolsnoList of tool definitions (see MCP Tools)
packagesnoSystem packages installed via apt-get install -y at build time
collaboratorsnoList of agent keys this agent can hand off to
executionnoExecution mode and verification settings
governancenoAgent-level override of global governance
triggersnoAgent-level triggers

Runtime overrides

These environment variables always override the baked-in agentfile.yaml values — no rebuild required:

Bash
AGENTFILE_PROVIDER=openai
AGENTFILE_MODEL=gpt-4o
AGENTFILE_TEMPERATURE=0.5

Variable interpolation

${VAR} syntax in agentfile.yaml is resolved at runtime from the container environment — not at build time. This keeps secrets out of your Docker images:

YAML
governance:
  human_approval:
    notify_url: "${APPROVAL_WEBHOOK_URL}"    # resolved when container starts
On this page