Architecture

my-agent/
├── agent.yaml          # Model, tools, runtime config
├── SOUL.md             # Agent identity & personality
├── RULES.md            # Behavioral rules & constraints
├── DUTIES.md           # Role-specific responsibilities
├── memory/
│   └── MEMORY.md       # Git-committed agent memory
├── tools/
│   └── *.yaml          # Declarative tool definitions
├── skills/
│   └── <name>/
│       ├── SKILL.md    # Skill instructions (YAML frontmatter)
│       └── scripts/    # Skill scripts
├── workflows/
│   └── *.yaml|*.md     # Multi-step workflow definitions
├── agents/
│   └── <name>/         # Sub-agent definitions
├── plugins/
│   └── <name>/         # Local plugins (plugin.yaml + tools/hooks/skills)
├── hooks/
│   └── hooks.yaml      # Lifecycle hook scripts
├── knowledge/
│   └── index.yaml      # Knowledge base entries
├── config/
│   ├── default.yaml    # Default environment config
│   └── <env>.yaml      # Environment overrides
├── examples/
│   └── *.md            # Few-shot examples
└── compliance/
    └── *.yaml          # Compliance & audit config

# agent.yaml
spec_version: "0.4.0"
name: my-agent
version: 1.0.0
description: An agent that does things

model:
  preferred: "anthropic:claude-sonnet-4-6"
  fallback: ["openai:gpt-4o"]
  constraints:
    temperature: 0.7
    max_tokens: 4096

tools: [cli, read, write, memory]

runtime:
  max_turns: 50
  timeout: 120

# agent.yaml
spec_version: "0.4.0"
name: my-agent
version: 1.0.0
description: A description of what this agent does

model:
  preferred: "anthropic:claude-sonnet-4-6"
  fallback:
    - "openai:gpt-4o"
    - "google:gemini-2.0-flash-001"
  constraints:
    temperature: 0.7
    max_tokens: 4096

tools:
  - cli
  - read
  - write
  - memory
  - capture_photo
  - task_tracker
  - skill_learner

skills:
  - code-review
  - deployment

runtime:
  max_turns: 50
  timeout: 300

extends: https://github.com/user/parent-agent.git

dependencies:
  - name: shared-skills
    source: https://github.com/team/shared-skills
    version: main
    mount: deps/shared

agents:
  researcher:
    model: "anthropic:claude-haiku-4-5-20251001"
    tools: [read, cli]

delegation:
  mode: auto

plugins:
  my-plugin:
    enabled: true
    config:
      api_key: "${MY_PLUGIN_KEY}"

compliance:
  risk_level: high
  human_in_the_loop: true
  data_classification: "confidential"
  regulatory_frameworks: [SOX, GLBA]
  recordkeeping:
    audit_logging: true
    retention_days: 2555
  review:
    required_approvers: 2
    auto_review: false

serve:
  port: 8080
  allowed_tools: [lookup_account, get_policy]
  constraints:
    temperature: 0
    max_tokens: 4000