# Agent YAML

Agent YAML selects the model, instructions, and capabilities for one runnable role.

## Example

```yaml
name: reviewer
description: Reviews evidence and recommends whether to release.
ai:
  model: openai/gpt-5.4
  thinking_level: medium
session:
  tool_execution: parallel
  retry:
    enabled: true
    max_retries: 2
tools: [read]
skills: [release-policy]
system_instructions:
  mode: append
  content: |
    Return a recommendation, supporting evidence, and unresolved risks.
```

## Fields

Ten fields are the whole vocabulary—anything else fails the file at launch:

| Field | What it decides |
| --- | --- |
| `name` | The stable role. `name` is the agent's identity everywhere; the filename means nothing. |
| `description` | When the role should be used. |
| `from` | Another agent definition used as the base for a variant. |
| `ai` | The model, reasoning, portable request options, and provider payload policy that are part of this agent version. |
| `session` | Portable Pi policy for queues, tool execution, retry, compaction, and images. |
| `system_instructions` | How this role specializes the recipe's shared instructions. |
| `tools` | An allowlist of built-in and extension-provided tools; nothing else reaches the model. Never list `agent`—it is generated from `subagents`. |
| `skills` | The skills selected for this role, by skill name (frontmatter `name`, defaulting to the skill's directory name), not path. |
| `mcp` | Which part of the package's declared MCP capability this role uses. |
| `subagents` | Which other recipe agents this role may delegate to. |

One compatibility carve-out: a legacy top-level `model` block is still
accepted in place of `ai`, and a file declaring both fails. New recipes should
always use `ai`.

## AI configuration

`ai.model` is required once inheritance is resolved. `ai.thinking_level`,
`ai.options`, and `ai.providers` are optional. `ai.options` is a transparent,
forward-compatible map of portable Pi request options authored in snake_case;
Recipes converts only option names to Pi camelCase. OpenRouter routing,
Anthropic context management, and Vercel AI Gateway routing are explicit
provider payloads whose nested contents remain transparent.

The checker validates the safe outer AI envelope and rejects host-owned
credentials, clients, headers, hooks, networking, telemetry, and session
identity. It validates supported provider payload shapes, but it does not
predict whether the selected model or a live provider endpoint accepts an
opaque nested value.

`ai.model` and `ai.thinking_level` are the agent's defaults, not a ceiling: a
task may override either for its own run. See
[selecting a model for one task](/platform/tasks-and-runs#selecting-a-model-for-one-task).
Subagents are unaffected, so a delegated role keeps whatever model this file
gives it.

## Session policy

Unlike those transparent AI payloads, `session` is closed and fully checked:

```yaml
session:
  steering_mode: one-at-a-time   # all | one-at-a-time
  follow_up_mode: one-at-a-time
  tool_execution: parallel       # parallel | sequential
  retry:
    enabled: true
    max_retries: 2
    base_delay_ms: 1000
    provider:
      timeout_ms: 60000
      max_retries: 2
      max_retry_delay_ms: 8000
  compaction:
    enabled: true
    reserve_tokens: 8192
    keep_recent_tokens: 12000
  images:
    auto_resize: true
    block_images: false
```

Every nested `session` key, type, enum, and numeric range is validated.
Interactive tree navigation and branch summaries are not portable managed
runtime policy.

## Inheritance

Omitted settings are inherited through `from:`, and each rule keeps permission
changes visible in review:

- Arrays never merge item by item—a declared `tools`, `skills`, or `subagents`
  list replaces the inherited one entirely, and `[]` clears it.
- `ai` merges by key, unless the child declares `ai.model`, which starts a
  fresh AI configuration and drops inherited request and provider policy.
- `session` merges by key, including recursive merges of nested settings.
- A declared `mcp` block replaces the whole inherited policy.
- `system_instructions.mode: append` composes after the inherited
  instructions; `replace` discards both the inherited instructions and Pi's
  base prompt—use it only when the role intentionally starts from nothing.

## Related

See [Agent definitions](/recipes/agents) for the mental model and the
[agent composition standard](https://pi.recipes/docs/agents)
for complete field and inheritance rules.

Agent YAML

Agent YAML selects the model, instructions, and capabilities for one runnable role.

Example


name: reviewer
description: Reviews evidence and recommends whether to release.
ai:
  model: openai/gpt-5.4
  thinking_level: medium
session:
  tool_execution: parallel
  retry:
    enabled: true
    max_retries: 2
tools: [read]
skills: [release-policy]
system_instructions:
  mode: append
  content: |
    Return a recommendation, supporting evidence, and unresolved risks.

Fields

Ten fields are the whole vocabulary—anything else fails the file at launch:

Field	What it decides
`name`	The stable role. `name` is the agent’s identity everywhere; the filename means nothing.
`description`	When the role should be used.
`from`	Another agent definition used as the base for a variant.
`ai`	The model, reasoning, portable request options, and provider payload policy that are part of this agent version.
`session`	Portable Pi policy for queues, tool execution, retry, compaction, and images.
`system_instructions`	How this role specializes the recipe’s shared instructions.
`tools`	An allowlist of built-in and extension-provided tools; nothing else reaches the model. Never list `agent`—it is generated from `subagents`.
`skills`	The skills selected for this role, by skill name (frontmatter `name`, defaulting to the skill’s directory name), not path.
`mcp`	Which part of the package’s declared MCP capability this role uses.
`subagents`	Which other recipe agents this role may delegate to.

One compatibility carve-out: a legacy top-level model block is still accepted in place of ai, and a file declaring both fails. New recipes should always use ai.

AI configuration

ai.model is required once inheritance is resolved. ai.thinking_level, ai.options, and ai.providers are optional. ai.options is a transparent, forward-compatible map of portable Pi request options authored in snake_case; Recipes converts only option names to Pi camelCase. OpenRouter routing, Anthropic context management, and Vercel AI Gateway routing are explicit provider payloads whose nested contents remain transparent.

The checker validates the safe outer AI envelope and rejects host-owned credentials, clients, headers, hooks, networking, telemetry, and session identity. It validates supported provider payload shapes, but it does not predict whether the selected model or a live provider endpoint accepts an opaque nested value.

ai.model and ai.thinking_level are the agent’s defaults, not a ceiling: a task may override either for its own run. See selecting a model for one task. Subagents are unaffected, so a delegated role keeps whatever model this file gives it.

Session policy

Unlike those transparent AI payloads, session is closed and fully checked:


session:
  steering_mode: one-at-a-time   # all | one-at-a-time
  follow_up_mode: one-at-a-time
  tool_execution: parallel       # parallel | sequential
  retry:
    enabled: true
    max_retries: 2
    base_delay_ms: 1000
    provider:
      timeout_ms: 60000
      max_retries: 2
      max_retry_delay_ms: 8000
  compaction:
    enabled: true
    reserve_tokens: 8192
    keep_recent_tokens: 12000
  images:
    auto_resize: true
    block_images: false

Every nested session key, type, enum, and numeric range is validated. Interactive tree navigation and branch summaries are not portable managed runtime policy.

Inheritance

Omitted settings are inherited through from:, and each rule keeps permission changes visible in review:

Arrays never merge item by item—a declared tools, skills, or subagents list replaces the inherited one entirely, and [] clears it.
ai merges by key, unless the child declares ai.model, which starts a fresh AI configuration and drops inherited request and provider policy.
session merges by key, including recursive merges of nested settings.
A declared mcp block replaces the whole inherited policy.
system_instructions.mode: append composes after the inherited instructions; replace discards both the inherited instructions and Pi’s base prompt—use it only when the role intentionally starts from nothing.

See Agent definitions for the mental model and the agent composition standard for complete field and inheritance rules.