Agent definitions

A recipe can contain one agent or a small team of them. Each agent is a YAML file whose name is its identity everywhere—in --agent, in agentName, in another agent’s subagents list, and in traces. The conventional entry point is agents/agent.yaml, and the default agent is the one named agent.

How an agent comes together

An agent’s effective behavior is composed from a few clear layers:

1. SYSTEM.md establishes the mission, terminology, policies, and workflow shared by the recipe.
2. The agent YAML selects its model and capabilities and adds instructions for this particular role.
3. Selected skills provide detailed procedures only when the agent needs them.
4. Extensions and MCP declarations determine which actions the role can take.

Keep shared rules in SYSTEM.md and role-specific duties in the agent file. Model choice belongs in the agent definition because it is part of the versioned behavior you test and deploy.

Ten fields are the whole agent vocabulary: name, from, description, ai, session, tools, skills, subagents, mcp, and system_instructions. Anything else fails the file at launch—a typo cannot quietly do nothing.

Variants and subagents

Create more YAML files to define subagents and variants. In this example, the base agent exposes a reviewer for delegated work. A model variant derives from that base, while the reviewer remains an independent agent definition.

name: agent
description: Main coding agent for repository tasks.
ai:
  model: openai/gpt-5.5
  thinking_level: medium
tools:
  - read
  - write
  - bash
  - update_plan
subagents:
  - review
system_instructions:
  mode: append
  content: |
    Make focused changes, verify the result, and use the reviewer after
    non-trivial work.

name: agent-mini
from: agent
ai:
  model: openai/gpt-5.4-mini

name: review
description: Independently reviews a proposed code change.
ai:
  model: openai/gpt-5.5
  thinking_level: medium
tools:
  - read
  - bash
skills: []
subagents: []
system_instructions:
  mode: append
  content: |
    Inspect the proposed change and report concrete findings. Do not edit the
    workspace.

agent-mini derives from agent and restates only the model. Along a from: chain, ai merges by key—unless the child declares ai.model, which starts a fresh AI configuration. Restating the model therefore drops inherited thinking, request options, and provider policy. session merges separately by key, including recursive merges of nested retry, compaction, and image settings.

Use ai.options for portable Pi request options and explicit provider blocks for OpenRouter, Anthropic, or Vercel AI Gateway payload policy. Use session for model-independent queues, tool execution, retry, compaction, and image handling. The Agent YAML reference documents which parts are transparent and which are fully validated.

Arrays never merge item by item: a derived agent declaring tools: [read] receives only read, whatever its base listed, and [] clears an inherited list entirely. That keeps permission changes visible in review. Inheritance and delegation are separate: from: inherits a definition; only naming an agent in subagents makes it reachable.

review is a subagent with its own read-only tools and an empty subagents list, so it cannot delegate further. Use this pattern when the delegated work needs an independent context, capability boundary, and clear output.

Delegation is asynchronous

There is no separate kind of agent for delegated work: every agent in a package can be invoked directly, and the same file becomes a tool the moment a lead agent names it in subagents. Recipes registers a single agent tool that accepts only those names—never list agent in tools yourself; the subagents list is what enables it.

Starting a run returns a run id immediately instead of blocking, which lets a lead agent keep working while the agents it started run alongside it:

A child runs from the same resolved snapshot as the root with its own model, tools, skills, and instructions, and no agent tool of its own—delegation is one level deep, so a run cannot fan out without bound. Selection is not isolation: every agent in a recipe runs in the same workspace with the same authority.

See the Recipes standard for the complete agent composition rules .