Docs Features Agent Hub GitHub Get Started

Schema Overview

Understanding agent.yaml — the standard definition format for AI agents

Why YAML

YAML was chosen for several reasons:

  • Human-readable — Easy to write and review without tooling.
  • Git-friendly — Clean diffs, straightforward merge conflict resolution.
  • Editor support — The file includes a YAML language server directive that enables autocomplete, inline validation, and hover docs in VS Code and other editors.
  • Ecosystem — Widely used for configuration in DevOps, Kubernetes, CI/CD, and infrastructure tooling. Developers already know it.

Minimal example

An agent.yaml only requires three fields:

name: support-agent
description: Answers customer questions about our product
model: claude-sonnet-4-20250514

That’s a valid agent definition. The CLI can validate it, and automagent run can start a chat session with it.

Full example

Here is a more complete definition showing the major sections:

# yaml-language-server: $schema=https://automagent.dev/schema/v1.json
apiVersion: v1
kind: agent

name: code-reviewer
version: 1.0.0
description: Reviews pull requests for code quality, security, and best practices

model:
  id: claude-sonnet-4-20250514
  provider: anthropic
  settings:
    temperature: 0.2
    max_tokens: 4096
  fallback:
    id: gpt-4o
    provider: openai

instructions:
  system: |
    You are a senior code reviewer. Review pull requests for:
    - Code correctness and logic errors
    - Security vulnerabilities
    - Performance implications
    - Adherence to project conventions

    Be specific in your feedback. Reference line numbers. Suggest fixes, not just problems.
  persona:
    role: Senior Software Engineer
    tone: constructive and direct
    expertise:
      - TypeScript
      - Python
      - security best practices

tools:
  - name: read-file
    description: Read a file from the repository
    inputSchema:
      type: object
      properties:
        path:
          type: string
      required:
        - path
  - name: search-code
    description: Search for patterns across the codebase
    inputSchema:
      type: object
      properties:
        query:
          type: string

mcp:
  - name: github
    transport: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-github"

context:
  - file: ./CONVENTIONS.md
  - file: ./docs/security-guidelines.md

guardrails:
  behavioral:
    - Never approve code that contains hardcoded credentials
    - Always flag SQL queries that use string concatenation
  prohibited_actions:
    - Merging pull requests
    - Modifying repository settings

governance:
  data_classification: internal
  pii_handling: none

dependencies:
  agents:
    - ref: "@acme/security-scanner:^2.0.0"
      role: security-analysis
      required: false
      interaction: on_demand

metadata:
  owner: platform-team
  tags:
    - code-review
    - security
    - quality
  categories:
    domain: engineering
    function: review
    maturity: production
  license: MIT
  author:
    name: Acme Corp
    email: platform@acme.com

The JSON Schema

The agent.yaml format is backed by a formal JSON Schema. This enables:

  • Programmatic validation via automagent validate
  • Editor autocomplete when you include the language server directive
  • Integration with any tool that supports JSON Schema validation

The schema is published at:

https://automagent.dev/schema/v1.json

Add this line to the top of your agent.yaml to enable editor support:

# yaml-language-server: $schema=https://automagent.dev/schema/v1.json

Next steps