A subagent is an agent invoked by another agent or orchestrator. It receives a bounded task and returns a result to its parent.
The parent should delegate an outcome, not its entire uncertainty.
- Supervisor
Split work that can run independently and assign bounded authority.
- Research tray
Use a small evidence context and read-only sources. Return cited findings.
- Code and operations trays
A code worker returns a scoped patch and tests; an operations worker returns observations from scoped diagnostics.
- Merge
Combine structured results while preserving sources and unresolved disagreements.
The merge keeps evidence and disagreements, rather than multiplying conversation.
How to read this model
A supervisor sorter with three isolated work trays. The object is a teaching analogy. Inspecting a part highlights its role; it does not execute or simulate the software. Cabinet trays are records, workpieces are data, and latches are checks. Unless an explanation states a quantity, compartments and sample workpieces do not denote data counts. Part dimensions are not a quantitative scale.
Pass the minimum complete context
A useful subagent request contains:
- The task and success condition
- Relevant evidence and identifiers
- Allowed tools and sources
- Output contract
- Deadline and budget
- Known constraints
Do not pass the full conversation by default. It wastes tokens, leaks unrelated information, and lets earlier untrusted content influence another role.
A tool is often enough
Use a tool when the task has one stable operation. Use a subagent when the task needs its own observe-decide-act loop.
lookupCustomer(customerId) is a tool. “Investigate why this customer's last three orders failed, using order and payment read tools, then return cited findings” can justify a subagent.
Handoff transfers responsibility
Delegation normally returns control to the parent after a bounded result. A handoff transfers the ongoing interaction to another agent. The receiving agent needs enough context to continue, and the system needs a record of which agent currently owns the task.
Use handoffs for clear routing, such as language or product specialization. Avoid chains in which agents hand the user back and forth without progress.
Limit recursive delegation
Set maximum depth, total child count, and per-child budgets. Propagate cancellation. Prevent a child from invoking a peer that later invokes the parent again unless the graph explicitly allows that cycle.
Recursion can be useful for hierarchical task decomposition, but it needs the same termination rules as any other loop.
Aggregate structured results
For parallel research, combine claims by stable topic or question. Deduplicate repeated evidence. Preserve provenance. Mark conflicts.
The aggregator should not turn three weak, copied claims into one high-confidence claim merely because several agents repeated the same source.
Handle timeout as a partial result
When one child times out, cancel its remaining work and decide whether the parent can continue with partial evidence. Record which branch is missing. Do not silently replace “worker did not finish” with “no issue found.”
Evaluate delegation
Measure whether the parent delegated the right task, supplied enough context, selected an appropriate worker, stayed within budget, and used the returned evidence correctly. Evaluating only the final answer misses poor coordination.