Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 35 of 37

Subagents

0 of 37 complete

Why it matters

Search, exploration and file reading produce far more text than the parent needs. Putting it all in the parent's context dilutes attention and raises cost. A subagent absorbs that volume, does the reading and returns a summary with references. The engineering problem is the return contract: what must survive compression, and how the parent asks for more without repeating the search.

Mental model

A subagent is a research assistant who reads the archive and hands back a brief with citations. The metaphor breaks because an assistant can be asked follow-up questions from memory, while a subagent's context is gone once it returns, so a follow-up starts a new run.

How it works

Spawn under four guards, return under an evidence contractInteractive

Keyed transitions

  1. Spawn? → Parent: read inline
  2. Spawn? → Child run: depth < 2 ∧ children < 4
  3. Spawn? → Over-scoped: scope ⊄ parent
transitionfailurerepeat

Event · step 1 of 10

Parent · step 6

Entry: the parent's context is 8.1k tokens and the next task needs a read across 40 files. Children: 0, depth 0. The child exists to keep that read out of this context.

In state

  • Parent

Next: Spawn decision

Children
0
Parent tokens
8.1k
Depth
0
Step 1/10 · Parent · step 6

Figure. Nine states. Spawn is guarded by volume, depth, fan-out and scope; Return is guarded by evidence per finding, and Merge is the only edge that grows the parent's context. The three red states are the page's failures: a result without provenance, a recursive spawn, and a child with broader scope than its parent.

What to notice. The 20k-token trigger, the depth-2 and four-child caps, the 380-token brief and the 8.1k parent context are illustrative. Parallel children are drawn as one sequential trace and share Spawn's guards. The return contract is what the parent can verify later, so Merge is a checkpoint rather than a copy of the child's transcript.

Text version

A state machine with nine states. Parent is the start, a pill. Parent goes to Spawn, a hexagonal decision, on volume, and to Done, a terminal pill, on answered. Spawn has a keyed repeat edge back to Parent, guard read inline, goes to Child run on spawn, to Recursive, a red failure box, when depth equals 2, and to Over-scoped, a red failure box, when scope is not inside the parent. Child run goes to Return on result. Return goes to Merge, a checkpoint, when every finding has evidence, and to No evidence, a red failure box, when evidence is missing. Merge has a repeat edge back to Parent labelled brief. The trace walks Parent, Spawn, Child run, Return, Merge, Parent, Done, then No evidence, then Recursive, then Over-scoped. Counters show children at 1 after the spawn, parent tokens moving only at Merge, and depth holding at 1 while the depth-2 spawn is refused.

  1. Define the child's task as a question with a required output shape, not a vague area to explore.
  2. Give it only the tools it needs and the same or narrower permissions than the parent.
  3. Require references such as paths, ids and URLs beside the summary so claims can be checked.
  4. Return a structured result with findings, evidence, confidence and open questions.
  5. Keep the child's transcript available to the operator even though the parent never sees it.
  6. Cap child count, depth and total tokens, and make recursion impossible past a fixed depth.

Trade-offs

ChoiceGood forCostFails when
Subagent per explorationParent context stays smallLatency and token cost per childThe task needs one quick lookup
Summary-only returnCheapest for the parentDetail is unrecoverableThe parent must justify a specific claim
Full transcript returnNothing is lostDefeats the purpose of isolationThe transcript is large
Parallel subagentsWall-clock savings on independent workCost spike and coordinationSubtasks depend on each other
Trade-off mapInteractive

Good for

Parent context stays small

Cost

Latency and token cost per child

Fails when

The task needs one quick lookup

  1. The task needs one quick lookup
  2. The parent must justify a specific claim
  3. The transcript is large
  4. Subtasks depend on each other

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Subagent per exploration is good for Parent context stays small, costs Latency and token cost per child, and fails when The task needs one quick lookup. Summary-only return is good for Cheapest for the parent, costs Detail is unrecoverable, and fails when The parent must justify a specific claim. Full transcript return is good for Nothing is lost, costs Defeats the purpose of isolation, and fails when The transcript is large. Parallel subagents is good for Wall-clock savings on independent work, costs Cost spike and coordination, and fails when Subtasks depend on each other

Failure modes

  • Lost provenance. The parent cites a claim the child cannot substantiate. Debug: require an evidence field per finding and reject results without one.
  • Permission escalation. A child is granted broader tools than its parent and acts beyond the task. Debug: diff effective tool scopes between parent and child at spawn time.
  • Recursive spawn. A subagent creates subagents until the budget is gone. Debug: record depth on every run and assert a hard maximum.

In production

Monitor tokens per child, children per task and the share of child results the parent uses. Cap depth and fan-out, and keep child transcripts for the retention window so a result can be audited.

Common misconceptions

People think: Subagents let the parent think about more.

Actually: The parent sees less by design; the benefit is focus and the risk is losing detail it needed.

People think: Subagents are just parallel tool calls.

Actually: A tool call returns data to the same context; a subagent runs a separate context and returns a compressed artefact.

Interview angle

Strong answers describe the return contract and the permission inheritance, then explain what the parent can still verify afterwards. Weak answers describe spawning helpers as a way to parallelise, with no mention of what is lost.

Sources