Split work across several agents

A helper agent is another YAML file in the same recipe, with its own model, tools, and connector access. Use one when part of the work needs a cheaper model, fewer permissions, or a fresh context.

You need: a recipe you can change (Define agents).

1. Add the helpers

Only agents listed in subagents can be started by that agent.

name: agent
ai: { model: anthropic/<large-model> }
tools: [read, write, edit, bash]
subagents: [worker, explorer, verifier]

name: explorer
description: Answers one narrow question with sources. Never writes.
ai: { model: anthropic/<mid-model> }
tools: [read, bash]

A verifier is the same shape on another provider (openai/<model>), and a worker adds write tools. With byok, bind a key per provider (Choose models). Never give an explorer or verifier write, edit, or send tools.

2. Narrow each agent’s connector tools

pi.mcp in package.json is the most any agent may use. Each agent selects its own subset in mcp:; nothing is inherited, and an agent without mcp: gets no MCP tools.

mcp:
  mode: cli
  servers:
    <app>: { include: [<app>-search, <app>-get] }

3. Tell the main agent when to delegate

Delegation goes through the built-in agent tool (start, status, wait, message, interrupt, close). start returns at once; the parent keeps working and later calls wait.

system_instructions:
  mode: append
  content: |
    Hand a long task to worker with everything it needs in the prompt; it cannot
    see this conversation. Start one explorer per independent question.
    Each helper writes only under scratchpad/<its label>/.

Helpers share /workspace, credentials, and memory with the parent, so give each its own folder. A helper keeps running after the main agent’s reply ends the turn; its result arrives as a new turn. At most 64 helpers run at once (a further start fails until one finishes), nested at most 2 deep (Limits).

The task’s stream shows only the main agent’s tool calls. If your app acts on a tool call such as save_draft, the main agent must make it.

4. Start a helper directly

Any agent can be a task’s main agent, for example a nightly maintainer:

introspection tasks create -r support-agent --agent maintainer --prompt "Tidy memory for today."

The SDKs take agent_name. To run it nightly, put that prompt in a platform automation or your own scheduler.

Verify

introspection check
introspection local -p "Research Acme and Globex pricing in parallel, then summarize."

Expect agent tool calls that start two explorer runs.

Or ask your agent: “Add a read-only explorer agent to support-agent and test delegation locally.”

Limits