Skip to main content
By the end of this guide one agent has split a task, started a sub-agent per piece in parallel, and combined their reports, and you know how to watch, steer and stop them. Each sub-agent reads in a thread of its own and returns a summary, so the parent’s context holds the summary, not the reading (how this works).

Before you begin

1

Check that the agent can spawn

An agent can start sub-agents only when its spawn_presets list is not empty. The built-in agent allows general, researcher and code_reviewer by default, and most built-in presets set their own list. To see a preset’s list, open Settings → Presets and choose View (Configuring sub-agents).Nesting stops at two levels. Your chat’s agent can spawn, and so can its sub-agents. Their sub-agents cannot.
2

Write a prompt that delegates

Say how to split the work, ask for a plan and a briefing file, and ask for every spawn in the same turn:
Chat message
  • A plan. Sub-agents read their nearest ancestor’s plan, so it becomes the board they report on. Only its creator can change its shape.
  • A briefing file. A sub-agent starts with only its prompt. A file it is pointed to holds what the parent already learned.
  • One turn. spawn returns at once, so starting every sub-agent together costs no more than starting one.
In a real run the agent called create_plan, wrote notes/brief.md, then made both spawn calls in one turn:
spawn call
3

Set the concurrency caps (optional)

By default one agent runs at most 8 sub-agents at once, and a run at most 16. To set other caps for a run you start from the CLI, put them in a JSON file as numbers:
caps.json
terminal
The caps are ceilings: past about six at once, the model provider starts throttling every agent.
4

Watch the sub-agents

In the app, each sub-agent has a thread tab beside All and Main (Threads). From a terminal, reliant workflow status prints the run’s tree. The run’s id is the chat id:
terminal
Each builtin://agent row is a sub-agent. Sub-agents also mark their tasks on the plan with update_task:
5

Steer or stop a sub-agent

To redirect one, send a message in its thread in the app, or ask the main agent to use spawn_send. To stop one, ask the main agent to call spawn_stop.Both take effect at the sub-agent’s next step boundary, after its current tool call returns, so spawn_send reports the message as queued, not read. spawn_status with wait: true shows when an agent has finished or stopped. A wait ends early when any message arrives:
6

Verify the result

When every sub-agent has reported, the main agent answers. The run’s tree shows each sub-agent finished:
The answer combined both reports and noted where they disagreed:
Read each sub-agent’s own thread when you want its evidence, not just the summary.

What you see from inside a sub-agent

A sub-agent two levels below the main agent shows this. Its tool list has spawn_send, to report to its parent, and no spawn, spawn_status or spawn_stop, because it is at the depth limit. Its list_tasks returns the main agent’s plan, past the orchestrator in between, which made none:

What this does not do

  • Sub-agents do not see your conversation. They get the prompt, the preset and the project’s memory.
  • It does not isolate files. Without a workspace, every sub-agent works in the parent’s checkout. Parallel edits need a workspace each.
  • There is no queue. A spawn past a cap starts nothing; the agent spawns again when a sub-agent finishes.
  • Siblings cannot message each other. Messages go between a parent and its direct sub-agents.
  • Nesting depth is fixed at 2. Only the caps are configurable.

Troubleshooting

The agent hit a concurrency cap; the message names it and the input that sets it. The agent waits for a sub-agent to finish and spawns again. To change the caps, see step 3.
A sub-agent of a sub-agent asked to spawn. It does the work itself or tells its parent which parts to fan out. Give depth-2 helpers leaf work.
The agent’s spawn_presets list is empty. Choose a preset that lists some, or set spawn_presets on the workflow node (Configuring sub-agents).

Next steps

Run parallel coding agents in separate git worktrees

Give each agent its own workspace and branch, then join the results.

How sub-agents and threads isolate context

Mailboxes, the plan’s single writer, nesting and the caps.

Best of Three

Three candidates in separate workspaces and a reviewer.

Sub-agents reference

The spawn tool’s parameters, presets, errors and resuming.