Field Reference

Complete reference for every field in agent.yaml

Identity

`name` (required)

Type: string
Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
Max length: 128

Machine-readable slug for the agent. Lowercase alphanumeric characters and hyphens only. Must start and end with an alphanumeric character.

name: code-reviewer

`version`

Type: string
Default: 0.1.0

Semver version of this agent definition. Useful for tracking changes over time and for publishing to the Automagent Hub.

version: 1.2.0

`description` (required)

Type: string
Min length: 1

Human-readable description of what the agent does.

description: Reviews pull requests for code quality and security issues

`apiVersion`

Type: string
Default: v1

Schema version identifier. Used for forward compatibility as the spec evolves.

apiVersion: v1

`kind`

Type: string
Enum: agent, team
Default: agent

Definition type. Use agent for a single agent, team for a multi-agent composition.

kind: agent

Model

`model` (required)

Type: string or ModelConfig object

The model this agent uses. Can be a simple string identifier or a full configuration object.

Simple form:

model: claude-sonnet-4-20250514

Object form:

model:
  id: claude-sonnet-4-20250514
  provider: anthropic
  settings:
    temperature: 0.3
    max_tokens: 4096
  fallback:
    id: gpt-4o
    provider: openai
  compatible:
    - id: gpt-4o
      score: 0.9
    - id: claude-haiku-4-5-20251001
      score: 0.7

ModelConfig fields

Field	Type	Description
`id` (required)	`string`	Model identifier, e.g. `claude-sonnet-4-20250514`
`provider`	`string`	Provider name: `anthropic`, `openai`, etc.
`settings`	`object`	Model parameters
`settings.temperature`	`number`	Sampling temperature
`settings.max_tokens`	`integer`	Maximum output tokens
`fallback`	`object`	Fallback model if primary is unavailable
`fallback.id`	`string`	Fallback model identifier
`fallback.provider`	`string`	Fallback provider
`compatible`	`array`	List of compatible models with compatibility scores
`compatible[].id`	`string`	Compatible model identifier
`compatible[].score`	`number`	Compatibility score (0-1)

Instructions

`instructions`

Type: string or InstructionsConfig object

The system prompt and persona configuration for the agent.

Simple form:

instructions: |
  You are a helpful customer support agent.
  Always be polite and concise.

Object form:

instructions:
  system: |
    You are a senior code reviewer. Focus on security
    and performance issues.
  persona:
    role: Senior Engineer
    tone: constructive and direct
    expertise:
      - TypeScript
      - security
      - performance optimization

The system field can also reference an external file:

instructions:
  system:
    file: ./prompts/system-prompt.md

InstructionsConfig fields

Field	Type	Description
`system`	`string` or `{ file: string }`	System prompt, inline or from a file
`persona`	`object`	Agent persona configuration
`persona.role`	`string`	The role the agent plays
`persona.tone`	`string`	Communication tone
`persona.expertise`	`string[]`	Areas of expertise

Tools

`tools`

Type: array of ToolDefinition

Inline tool definitions following the MCP Tool interface. MCP server references go in the separate mcp field.

tools:
  - name: search-docs
    description: Search the documentation for relevant articles
    inputSchema:
      type: object
      properties:
        query:
          type: string
          description: Search query
        limit:
          type: integer
          description: Maximum number of results
          default: 5
      required:
        - query
    annotations:
      readOnlyHint: true

ToolDefinition fields

Field	Type	Description
`name` (required)	`string`	Tool name
`description`	`string`	Human-readable description
`inputSchema`	`object`	JSON Schema for tool parameters
`annotations`	`object`	MCP tool annotations
`annotations.readOnlyHint`	`boolean`	Whether the tool only reads data
`annotations.idempotentHint`	`boolean`	Whether repeated calls have the same effect
`annotations.destructiveHint`	`boolean`	Whether the tool makes destructive changes
`annotations.openWorldHint`	`boolean`	Whether the tool interacts with external systems

MCP

`mcp`

Type: array of McpServerConfig

MCP (Model Context Protocol) server references for tool discovery. These connect your agent to external tool servers.

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

  - name: database
    transport: streamable-http
    url: https://mcp.internal.example.com/db
    auth:
      type: bearer
      scope: read

McpServerConfig fields

Field	Type	Description
`name` (required)	`string`	Server name
`transport` (required)	`string`	`stdio` or `streamable-http`
`url`	`string`	URL for `streamable-http` transport
`command`	`string`	Command for `stdio` transport
`args`	`string[]`	Arguments for `stdio` transport
`auth`	`object`	Authentication configuration
`auth.type`	`string`	Auth type (e.g., `bearer`)
`auth.scope`	`string`	Auth scope

Context

`context`

Type: array of ContextSource

Static knowledge sources the agent should have access to. These are loaded and provided to the agent as additional context.

context:
  - file: ./docs/product-guide.md
  - file: ./data/*.csv
  - url: https://api.example.com/knowledge-base
  - agent: "@acme/fact-checker"

ContextSource fields

Field	Type	Description
`file`	`string`	Path to a local file or glob pattern
`url`	`string`	URL to fetch content from
`agent`	`string`	Agent reference for dynamic context

Inputs and Outputs

`inputs`

Type: object

JSON Schema defining the structured input format for the agent. Useful when the agent is called programmatically rather than through free-form chat.

inputs:
  schema:
    type: object
    properties:
      pull_request_url:
        type: string
        description: URL of the PR to review
      focus_areas:
        type: array
        items:
          type: string
    required:
      - pull_request_url

`outputs`

Type: object

JSON Schema defining the structured output format.

outputs:
  schema:
    type: object
    properties:
      summary:
        type: string
      issues:
        type: array
        items:
          type: object
          properties:
            severity:
              type: string
              enum: [critical, warning, info]
            description:
              type: string
            line:
              type: integer

Guardrails

`guardrails`

Type: Guardrails object

Rules and constraints that govern the agent’s behavior, inputs, and outputs.

guardrails:
  input:
    - name: content-filter
      description: Block requests containing harmful content
      action: block

  output:
    - name: pii-redaction
      description: Redact PII from responses
      action: transform

  behavioral:
    - Never share internal system details with users
    - Always cite sources when making factual claims

  prohibited_actions:
    - Executing arbitrary code
    - Accessing production databases directly

  require_approval:
    - pattern: "delete-*"
      approvers:
        - platform-team
        - security-team

Guardrails fields

Field	Type	Description
`input`	`GuardrailRule[]`	Rules applied before processing input
`output`	`GuardrailRule[]`	Rules applied after generating output
`behavioral`	`string[]`	Natural language behavioral rules
`prohibited_actions`	`string[]`	Actions the agent must never take
`require_approval`	`object[]`	Actions requiring human approval
`require_approval[].pattern`	`string`	Pattern matching actions that need approval
`require_approval[].approvers`	`string[]`	Teams or individuals who can approve

GuardrailRule fields

Field	Type	Description
`name`	`string`	Rule name
`description`	`string`	Human-readable description
`action`	`string`	`block`, `warn`, `transform`, or `log`

Governance

`governance`

Type: Governance object

Data handling policies, compliance requirements, and authorized use constraints.

governance:
  data_classification: confidential
  pii_handling: processes
  pii_types:
    - email
    - phone
    - address
  data_residency:
    - us-east-1
    - eu-west-1
  compliance_frameworks:
    - SOC2
    - GDPR
  risk_level: medium
  authorized_use:
    departments:
      - customer-support
      - sales
    environments:
      - staging
      - production

Governance fields

Field	Type	Description
`data_classification`	`string`	Classification level (e.g., `public`, `internal`, `confidential`)
`pii_handling`	`string`	How PII is handled: `processes`, `none`, etc.
`pii_types`	`string[]`	Types of PII the agent processes
`data_residency`	`string[]`	Allowed data residency regions
`compliance_frameworks`	`string[]`	Compliance frameworks (e.g., `SOC2`, `GDPR`, `HIPAA`)
`risk_level`	`string`	Risk level assessment
`authorized_use`	`object`	Usage constraints
`authorized_use.departments`	`string[]`	Departments authorized to use this agent
`authorized_use.environments`	`string[]`	Environments where the agent can run

Evaluation

`evaluation`

Type: object

Test datasets, minimum scores, and behavioral assertions for evaluating agent quality.

evaluation:
  dataset: ./evals/test-cases.jsonl
  minimum_score: 0.85
  assertions:
    - input: "What is your return policy?"
      expected: "30-day return policy"
    - input: "Can I speak to a manager?"
      expected: "escalation to human agent"

Evaluation fields

Field	Type	Description
`dataset`	`string`	Path to evaluation dataset file
`minimum_score`	`number`	Minimum passing score
`assertions`	`object[]`	Input/expected output pairs
`assertions[].input`	`string`	Test input
`assertions[].expected`	`string`	Expected output or pattern

Triggers

`triggers`

Type: array of Trigger

Events and schedules that activate the agent.

triggers:
  - event: pull_request.opened
    description: Run on new pull requests
    filter:
      base_branch: main
  - schedule: "0 9 * * 1"
    description: Weekly Monday morning report

Trigger fields

Field	Type	Description
`event`	`string`	Event name that triggers the agent
`schedule`	`string`	Cron expression for scheduled execution
`description`	`string`	Human-readable description
`filter`	`object`	Event filter conditions

Environments

`environments`

Type: object

Per-environment overrides. Any agent field can be overridden for a specific environment.

environments:
  staging:
    model: claude-haiku-4-5-20251001
    guardrails:
      behavioral:
        - Log all interactions for review
  production:
    model:
      id: claude-sonnet-4-20250514
      settings:
        temperature: 0.1

Each key is an environment name, and the value is a partial agent definition whose fields override the defaults.

Dependencies

`dependencies`

Type: object

Declares agents and tools this agent depends on.

dependencies:
  agents:
    - ref: "@acme/fact-checker:^1.2.0"
      role: fact-verification
      required: true
      interaction: on_demand
    - ref: "@acme/translator:^3.0.0"
      role: translation
      required: false
      interaction: on_demand

AgentDependency fields

Field	Type	Description
`ref` (required)	`string`	Agent reference (e.g., `@acme/fact-checker:^1.2.0`)
`role`	`string`	Role this dependency plays
`required`	`boolean`	Whether this dependency is required (default: `true`)
`interaction`	`string`	Interaction mode: `on_demand`, `always`, etc.

Extensions

`extensions`

Type: object

Framework-specific configuration under namespaced keys. This is where non-standard fields live, keeping the core schema clean while preserving framework-specific data.

extensions:
  crewai:
    verbose: true
    allow_delegation: true
  langgraph:
    graph_type: sequential

Extensions are freeform — any key/value structure is allowed under each namespace.

Metadata

`metadata`

Type: Metadata object

Organizational metadata for discovery, categorization, and ownership.

metadata:
  owner: platform-team
  tags:
    - code-review
    - security
    - automation
  categories:
    domain: engineering
    function: review
    maturity: production
  license: MIT
  author:
    name: Jane Smith
    email: jane@example.com
  repository: https://github.com/acme/code-reviewer
  changelog: |
    ## 1.0.0
    - Initial release
    - Added security scanning rules

Metadata fields

Field	Type	Description
`owner`	`string`	Team or individual who owns this agent
`tags`	`string[]`	Tags for discovery and categorization
`categories`	`object`	Structured categories
`categories.domain`	`string`	Domain (e.g., `engineering`, `support`)
`categories.function`	`string`	Function (e.g., `review`, `analysis`)
`categories.maturity`	`string`	Maturity level (e.g., `experimental`, `production`)
`license`	`string`	License identifier (e.g., `MIT`, `PROPRIETARY`)
`author`	`object`	Author information
`author.name`	`string`	Author name
`author.email`	`string`	Author email
`repository`	`string`	Source repository URL
`changelog`	`string`	Inline changelog