11 min read

Sub-Agent Orchestration

When and how to spawn isolated sub-agents: fan-out versus one loop, task contracts, partitioning, supervision, and the token economics of parallelism.

TL;DR

A sub-agent is a child agent loop with its own context window, toolset, and budget. The parent sends a task prompt and receives a result message—process isolation with message passing, not shared-memory threads.
There are two distinct reasons to spawn: parallelism, and context isolation. Isolation pays even with a single child—a token-heavy exploration runs in quarantine and returns only its conclusion.
Fan out only across independent branches. Steps that depend on each other's observations belong in one loop; splitting them just adds serialization through a narrow result channel.
The task prompt is an API contract. A sub-agent starts cold, sees none of the parent's context, and does exactly what the prompt scopes—under-specified tasks come back overlapping, duplicated, or wrong.
Never point parallel writers at shared state. Partition work like you would shard data: disjoint files, resources, and responsibilities per worker, with one synthesizer merging results.
Fan-out buys latency and context capacity, not efficiency—multi-agent runs burn an order of magnitude more tokens than a single loop, so the task's value must cover the multiplier.
Operate the fleet like a worker pool: per-worker budgets and timeouts, a policy for partial failure, results with provenance, and traces that cover the whole tree.

Quick view

Best for

Wide, read-heavy, parallelizable tasks

Core primitive

Prompt in, result message out

Do first

Quarantine one token-heavy subtask

Primary risk

Token multiplication without payoff

What & why

Sub-agent orchestration is the pattern of one agent spawning others: a parent loop delegates a scoped task to a child that runs its own complete agent loop—own context window, own tool calls, own turns—and reports back a single result. The parent never sees the child's intermediate work, only what the child chooses to return [1] [2].

The first payoff is parallelism. A research question with five independent angles, a codebase audit across five modules, a migration touching five services: independent branches can run concurrently, collapsing wall-clock time the way a worker pool collapses a job queue.

The second payoff is subtler and often more valuable: context isolation. An agent that greps through forty files to answer one question has spent thousands of tokens of its working context on exhaust. Run that search in a sub-agent and the parent pays only for the conclusion—the exploration happened in someone else's address space [3].

The cost is real. Every child starts cold, re-derives context the parent already had, and burns its own tokens; Anthropic reported its multi-agent research system using roughly fifteen times the tokens of a chat interaction [2]. Orchestration is the expensive path—the engineering below is about spending it only where it pays.

Mental model

A sub-agent is a spawned process, not a thread. It gets a fresh address space (its own context window), no shared memory with its parent, and communicates through explicit messages: the task prompt going in, the result message coming out. Everything you know about process isolation transfers—including the discipline it forces.

That interface is the whole relationship. The parent cannot peek at the child's reasoning mid-flight, and the child cannot consult the parent's conversation history. Both facts are features: the child's mess never pollutes the parent, and the child is forced to work from an explicit, reviewable task statement rather than ambient context.

The classic shapes apply directly. Fan-out/fan-in is fork–join: split, run, synthesize. An orchestrator handing typed tasks to specialized workers is a job queue. A parent restarting failed children under a budget is a supervisor tree. You are not learning a new architecture; you are re-applying one to a runtime where each worker is a model in a loop [1] [5].

The one place the analogy needs care: workers here are probabilistic. Two children given overlapping scopes will not idle—both will do the work, differently. Partitioning and task contracts do the job that locks and schedulers do in conventional pools.

Fan out or stay in one loop

01
Stay in one loop when steps are dependent
If each action depends on the previous observation—debugging, iterative code changes, negotiation-shaped tasks—a single loop with full context is strictly better. Splitting a sequential task forces every insight through a narrow result-message channel and adds cold starts for nothing.
02
Fan out when branches are independent and read-heavy
Parallel research, multi-module audits, evaluating alternatives, gathering evidence across sources: branches that neither write shared state nor need each other's findings until synthesis are the ideal case [2].
Independence is a claim worth checking: if the branches would benefit from talking to each other mid-run, they were not independent.
03
Spawn a single child for context hygiene
Even with no parallelism, quarantine work that is token-heavy but conclusion-light: broad searches, log spelunking, reading large documents for one fact. The parent's working context stays reserved for decisions [3].
This is the cheapest orchestration pattern and the right first use of sub-agents in most systems.
04
Spawn to narrow permissions or change the environment
A child can run with a smaller toolset, read-only credentials, a different model, or an isolated workspace such as a separate branch or container. Delegation becomes a security and blast-radius boundary, not just a concurrency trick [4].
05
Do not fan out writers on shared state
Two agents editing the same files, records, or configuration is shared mutable state without locks—you will get conflicts, lost updates, or silent overwrites. Partition writes into disjoint territories, or funnel all writes through one agent while others only read.

Build the orchestration layer

01
Write the task prompt as an API contract
The child sees nothing but this prompt plus its tools. Include the goal, the relevant context the parent already established, explicit scope boundaries—which files, which sources, which questions belong to this worker and which do not—and the effort expected.
Anthropic found orchestration quality tracks task-description quality directly: vague delegation produces duplicated work, gaps between workers, and confident answers to the wrong question [2].
02
Define the result contract
Specify what the final message must contain: findings with file paths or citations, confidence and open questions, changed artifacts by identifier. The parent synthesizes from result messages alone, so anything the child omits is lost with its context.
Ask for evidence and provenance, not just conclusions—synthesis needs to weigh sources and detect conflicts between workers.
03
Right-size the model and budget per worker
Narrow, well-specified tasks run fine on smaller, cheaper models; reserve the strongest model for orchestration and synthesis, where judgment concentrates. Give each child its own turn, token, and cost ceilings so one runaway worker cannot consume the run's budget.
04
Partition work like sharding
Divide by module, directory, source, or time range so no two workers claim the same territory. Overlap does not merely waste tokens—two probabilistic workers will resolve the same subtask differently, and the synthesizer inherits the contradiction.
05
Supervise like a worker pool
Set timeouts, retry failed children with amended prompts rather than verbatim reruns, and decide the partial-failure policy up front: does the run need all workers, a quorum, or best-effort synthesis over whoever returned?
Cap the topology while you are at it—workers spawning their own workers multiplies cost geometrically, and one level of delegation covers almost every real task.
06
Synthesize with provenance, then verify
The synthesizer should see which worker produced each claim and where workers disagree—surfacing conflicts beats averaging them into mush. Spot-check load-bearing claims against the underlying evidence before acting on the merged result.
07
Trace the tree, not just the run
Observability must cover the whole hierarchy: which parent spawned which child with what prompt, each child's turns and cost, and how results flowed into synthesis. A wrong final answer is undebuggable if the failing worker's trace is invisible [6].

Topology cheat sheet

Single loop: the default. No coordination cost, full context continuity; right for anything sequential.
Quarantine: one child for token-heavy exploration; parent keeps a clean working context. Cheapest win.
Orchestrator–workers: parent decomposes, N children run independent branches in parallel, parent synthesizes. Fork–join for open-ended work [1] [2].
Pipeline / handoff: sequential stages with different tools or permissions per stage; a relay, not a pool [5].
Evaluator pair: one agent produces, another critiques against explicit criteria; bounded revision loop.
Hierarchical (workers spawn workers): rarely worth it—cost compounds per level and debugging becomes archaeology. Reach for it only when a branch is itself a full decomposable project.

Common failure modes

Splitting a sequential task and forcing every insight through result-message bottlenecks.
Task prompts that assume the parent's context, so cold-started children guess at scope.
Two workers with overlapping territory resolving the same subtask two different ways.
Parallel writers on the same files or records, producing conflicts and lost updates.
Result messages without evidence or provenance, leaving the synthesizer to trust blindly.
No per-child budgets, so one runaway worker consumes the run's token ceiling.
Retrying failed children with the identical prompt and expecting a different outcome.
Unbounded hierarchy depth—delegation as a habit instead of a costed decision.
Traces that stop at the parent, making child failures invisible.
Fanning out by default when a single loop was cheaper, faster, and easier to debug.

Final checklist

The branches are genuinely independent, or the spawn is for isolation or permissions rather than parallelism.

The expected latency or context savings justify the token multiplier.

Each task prompt is self-contained, with explicit scope boundaries and expected effort.

The result contract names what every child must return, including evidence and provenance.

Work is partitioned so no two workers share writable territory.

Each child has its own model choice, turn, token, and cost budget.

Timeouts, retry-with-amendment, and a partial-failure policy are defined.

Hierarchy depth is capped, and children need approval to spawn further children.

Synthesis sees per-worker provenance and surfaces conflicts instead of averaging them.

Load-bearing claims in the merged result are spot-checked against evidence.

Traces cover the full spawn tree: prompts, turns, costs, and result flow.

Cost per task and conflict rate are compared against the single-loop baseline.

References

[1] Building effective agents — The orchestrator–workers and evaluator–optimizer patterns, with guidance to start from a single loop.
[2] How we built our multi-agent research system — Production lessons on task decomposition, delegation prompts, token economics, and synthesis.
[3] Effective context engineering for AI agents — Sub-agent isolation as a context strategy: exploration in a child, conclusions in the parent.
[4] Claude Code: Subagents — A production implementation: scoped tools, separate context windows, and per-agent configuration.
[5] OpenAI Agents SDK: Handoffs — Sequential delegation between specialized agents as a first-class runtime primitive.
[6] OpenAI Agents SDK: Tracing — Trace structure spanning nested agent runs, tool calls, and handoffs in one view.

More recipes

Subscribe to all Software Cookbook updates

If this recipe was useful, subscribe for the next ones. New pages arrive with the same concise, technical format.