Before you begin
- A chat in the Reliant app, or the
reliantCLI v1.21 or later, signed in (Sign in and tokens), with a connected machine (Run a machine from the terminal). - A task that splits into independent pieces: one per file, service, question or approach.
- For pieces that edit code at the same time, a workspace each. That is Run parallel coding agents in separate git worktrees.
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.
spawnreturns at once, so starting every sub-agent together costs no more than starting one.
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:The caps are ceilings: past about six at once, the model provider starts throttling every agent.
caps.json
terminal
4
Watch the sub-agents
In the app, each sub-agent has a thread tab beside All and Main (Threads). From a terminal, Each
reliant workflow status prints the run’s tree. The run’s id is the chat id:terminal
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 hasspawn_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
Spawn refused, and nothing was started
Spawn refused, and nothing was started
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.
Spawning is not available to this sub-agent: spawn nests at most 2 levels deep
Spawning is not available to this sub-agent: spawn nests at most 2 levels deep
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.
Spawning is not available to this agent: spawn is offered only by a workflow node that declares spawn presets
Spawning is not available to this agent: spawn is offered only by a workflow node that declares spawn presets
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.