Define agents
An agent is a YAML file in agents/ that turns the recipe’s shared
instructions into one runnable role. Add a second agent when a task needs its
own model, tools, or context.
You need: a recipe (Create a recipe).
name: agent
description: Reviews refund requests and drafts the next response.
ai:
model: anthropic/<model>
thinking_level: medium
tools: [read, bash]
skills: [refund-policy]
subagents: [reviewer]
system_instructions:
mode: append
content: |
Ground every decision in the refund policy. Draft responses; never issue a refund.name is the agent’s identity; the filename means nothing. The default agent
is named agent. system_instructions adds to the shared SYSTEM.md
(append) or replaces it (replace).
Fields
Only name (lowercase kebab-case) and ai.model are required (legacy
model.name is still accepted in place of ai). Any other key fails the file.
| Field | What it decides |
|---|---|
description | When this role should be used. |
from | The agent this one derives from. |
ai | model (<provider>/<model_id>), thinking_level, options (pi-ai request options in snake_case, such as cache_retention), providers (provider settings and routing). Credentials, headers, and networking are rejected. See Tune requests and caching. |
session | Pi session policy: steering_mode, follow_up_mode, tool_execution, retry, compaction, images. Every key is validated; values are Pi settings . |
tools | Strict allowlist of built-in tools and your tools. Omitted means none. |
skills | Skills by name. Omitted means none. |
mcp | This agent’s share of the recipe’s MCP grant. |
subagents | Agents this one may delegate to. |
1. Add a subagent
name: reviewer
description: Independently checks a drafted refund decision.
ai:
model: anthropic/<model>
tools: [read]2. Let the lead agent delegate
List it in subagents. The delegation tool, agent, is added for you; do not
put it in tools.
subagents: [reviewer]The agent tool takes start (returns a run id at once), status, wait,
message, interrupt, or close. A child has its own model, tools, and
instructions, but shares the task’s sandbox, /workspace, credentials, and
memory.
3. Make a variant
A variant derives from another agent and changes a few fields:
name: agent-fast
from: agent
ai:
model: anthropic/<smaller-model>Pick it per task instead of editing the recipe:
introspection tasks create -r support-agent -e staging --agent agent-fast --prompt "Review order 1842."The SDKs take the same choice as agent_name. A variant is not a delegate
unless some agent lists it in subagents.
| Inherited field | Rule |
|---|---|
tools, skills, subagents | A declared list replaces the inherited one; [] clears it. |
ai | Merges by key, but declaring ai.model starts a fresh ai block. |
session | Merges by key. |
mcp | A declared block replaces the inherited one whole. |
system_instructions | append adds after the inherited text; replace discards it. |
Verify
introspection check
introspection local -p "Draft a decision for order 1842 and have it reviewed."
introspection local --agent agent-fast -p "Review order 1842."Expect an agent tool call that starts reviewer in the first run.
Limits
| Not supported | Do this instead |
|---|---|
| Isolating a subagent’s files or credentials | Selection is not isolation. Run separate tasks or separate runtimes. |
| Unbounded fan-out | Concurrency and depth are capped (Limits). |
Or ask your agent: “Add a read-only reviewer subagent that checks each refund draft, and test it locally.”