Configuration

name: my-agent                    # Required — unique agent identifier
description: ""                   # Optional — human-readable description
tags: []                          # Optional — categorization tags
author: ""                        # Optional — author name
version: ""                       # Optional — semantic version
dependencies: []                  # Optional — pip dependencies
spec_version: 3                   # Flat schema version

prompt: |                         # Required — system prompt
  You are a helpful assistant.

model:                            # Optional — auto-detects when omitted
  provider: openai                # or shorthand: openai:gpt-5-mini
  name: gpt-5-mini                # Model identifier
  temperature: 0.1                # Sampling temperature (0.0-2.0)
  max_tokens: 4096                # Max tokens per response
  base_url: null                  # Custom endpoint URL
  api_key_env: null               # Env var for API key
  fallback: []                    # Provider:model fallback chain (v2026.4.17)

output: {}                        # Structured output (text or json_schema)
tools: []                         # Tool configurations
guardrails: {}                    # Resource limits
execution: {}                     # Retry, end-strategy, concurrency (v2026.4.17)
deps_schema: null                 # Template variables for {{var}} (v2026.4.17)
autonomy: {}                      # Autonomous plan-execute-adapt loop
observability: {}                 # OpenTelemetry tracing (opt-in)
ingest: null                      # Document ingestion / RAG
memory: null                      # Memory system
triggers: []                      # Trigger configurations
sinks: []                         # Output sink configurations
security: {}                      # Security policy
skills: []                        # Skill references
resources: {}                     # Memory and CPU limits
tool_search: {}                   # Tool search meta-tool config

output:
  type: json_schema
  schema:
    type: object
    properties:
      summary:
        type: string
      confidence:
        type: number
    required: [summary, confidence]

execution:
  retries: 3
  output_retries: 2
  end_strategy: graceful
  tool_timeout_seconds: 15.0
  max_concurrency:
    max_running: 4
    max_queued: 8

prompt: "You are greeting {{name}} from {{city}}."
deps_schema:
  type: object
  properties:
    name: {type: string}
    city: {type: string}
  required: [name, city]

initrunner run greeter/role.yaml -p "be polite" --var name=Alice --var city=Berlin

name: support-agent
description: Answers questions from the support knowledge base
tags:
  - support
  - rag
model:
  provider: openai
  name: gpt-5-mini
  temperature: 0.1
  max_tokens: 4096
prompt: |
  You are a support agent. Use search_documents to find relevant
  articles before answering. Always cite your sources.
ingest:
  sources:
    - "./knowledge-base/**/*.md"
    - "./docs/**/*.pdf"
  chunking:
    strategy: fixed
    chunk_size: 512
    chunk_overlap: 50
tools:
  - filesystem:
      root_path: ./src
      read_only: true
  - mcp:
      transport: stdio
      command: npx
      args: ["-y", "@anthropic/mcp-server-filesystem"]
triggers:
  - type: file_watch
    paths: ["./knowledge-base"]
    extensions: [".html", ".md"]
    prompt_template: "Knowledge base updated: {path}. Re-index."
  - type: cron
    schedule: "0 9 * * 1"
    prompt: "Generate weekly support coverage report."
guardrails:
  max_tokens_per_run: 50000
  max_tool_calls: 20
  timeout_seconds: 300