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 the SDK’s 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.

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.

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.

The agent vocabulary is deliberately small, and anything outside it fails the file at launch—a typo cannot quietly do nothing. The Agent YAML reference documents every field.

Variants and subagents

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

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 — but that one line changes more than the model. Declaring ai.model starts a fresh AI configuration, so agent-mini loses the base agent’s thinking_level: medium along with any inherited request options and provider policy. Everything it does not declare — the tools, the review subagent, the appended instructions — carries over unchanged. And deriving from agent does not make agent-mini reachable as a delegate: only naming it in some agent’s subagents list would. The full inheritance rules — which fields merge by key, which lists replace wholesale, and what [] clears — live in the Agent YAML reference.

review is a subagent with its own read-only tools and an empty subagents list. It cannot delegate further — but that is structural, not a consequence of the empty list: delegation is one level deep, and a child session never gets the agent tool regardless of what its file declares. The empty list simply makes the boundary explicit in the file. 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 complete agent composition rules  in the Recipes documentation.