How it works
A subagent is a scoped delegation. The parent agent decides that some slice of work is separable, then spawns a worker to handle it. The mechanism is a short control loop:
- Spawn — the parent creates a subagent with its own prompt, context, and tool surface.
- Scope — the parent hands it exactly one task and the inputs that task needs, not the whole conversation.
- Isolate — the subagent runs in a fresh context. It cannot see the parent's full history, and it cannot address other subagents.
- Return — the subagent produces one result and terminates. That result is the only thing that flows back.
The defining constraint is the missing edge: subagents do not talk to each other. Communication is a star, not a mesh. Every message goes child-to-parent or parent-to-child. That single restriction is what separates a subagent from a peer in a free-form multi-agent system, and it is the reason subagents are easier to reason about. You always know where a result came from and who is responsible for merging it.
Why it matters in an agent harness
Subagents are a containment tool before they are a throughput tool. Three properties matter in production.
Context isolation. A subagent starts clean. You can send it noisy inputs — a long file, raw search output, an untrusted excerpt — and its confusion, token bloat, or prompt injection stays inside its context. The parent only ever sees the returned result, so a poisoned subagent contaminates one branch instead of the whole run.
Blast-radius control. Because you provision each subagent's tool surface at spawn time, you can hand a research subagent read-only search and hand nothing else write access. The permissions travel with the delegation. A subagent that only summarizes cannot delete anything, no matter what its input tells it to do.
Observability at the boundary. The parent/child interface is a natural logging seam. You capture the task in, the result out, and the tools used — one legible record per delegation. That is far easier to audit than a mesh of agents negotiating among themselves.
Parallelism is real but secondary: independent subagents can run concurrently, which shortens wall-clock time on fan-out work like checking many sources. The point is that the isolation makes the parallelism safe.
Subagent vs peer agent in a multi-agent system
The distinction changes your topology, so it is worth being precise.
| Property | Subagent | Peer agent (mesh) |
|---|---|---|
| Communication | Only to and from its parent | To any other agent |
| Lifecycle | Spawned for one task, then ends | Often long-lived |
| Context | Fresh, scoped by the parent | Shared or negotiated |
| Responsibility | Parent owns the merge | Diffuse across the group |
| Failure containment | Bounded to one branch | Can cascade across peers |
If you allow peer-to-peer messaging, you gain flexibility and lose legibility: emergent loops, ambiguous ownership, and cascading confusion become possible. The subagent pattern trades that flexibility for a supervisor you can point at.
The Rifty take
We treat the subagent as the default unit of delegation and the mesh as the exception you justify. We optimize for a legible chain of responsibility: one parent that scopes work, hands out minimal context and minimal tools, and owns the merge. We accept the coordination cost of routing everything through that parent because it buys us containment and a clean audit trail. A subagent should be able to fail, hallucinate, or be injected without the operator losing control of the run.
Common failure modes
- Over-scoping the handoff. Passing the parent's entire context defeats isolation and reintroduces the noise you spawned the subagent to escape. Send only the task and its inputs.
- Unbounded fan-out. Spawning subagents per item with no cap burns tokens and time. Put an iteration or concurrency budget on the parent.
- Trusting the return blindly. A subagent result is untrusted output, not verified truth. Validate it against a schema or a check before merging.
- Leaking write access. Granting a read-only subagent write tools re-couples the blast radius. Provision the narrowest tool surface the task needs.
- Silent swallowing. If the parent ignores a subagent's error and proceeds, you lose the containment benefit. Surface failures at the boundary.
- Hidden peer channels. Letting subagents share state through a common store recreates the mesh you avoided. Keep coordination explicit and parent-mediated.
Frequently asked questions
How is a subagent different from a tool call?
A tool call runs fixed code and returns a deterministic result. A subagent is itself an agent: it reasons, plans, and may call tools of its own before returning. Use a tool when the step is mechanical, and a subagent when the step needs judgment inside an isolated context.
When should I spawn a subagent instead of doing the work inline?
Spawn one when the work is separable and either noisy or risky: large inputs that would bloat your context, untrusted excerpts, or steps needing tighter permissions. Keep work inline when it is small, tightly coupled to the main thread, or cheaper to run directly than to scope and merge.
Can subagents talk to each other?
No, not directly, and that is the point. A subagent communicates only with the parent that spawned it. All coordination routes through that parent, which keeps the topology a star. If your agents message peers freely, you have a multi-agent mesh, not a subagent pattern.
Do subagents make an agent system more reliable?
They can, by containing failure to one branch and isolating noisy or untrusted context. But reliability depends on the parent validating returned results and provisioning minimal tools. Unbounded fan-out and blindly trusted returns turn subagents into a new source of cost and error rather than a safeguard.
How do I control a subagent's blast radius?
Provision its tool surface at spawn time and grant the least privilege the task needs. A summarizing subagent gets read-only access and no write tools. Because permissions travel with the delegation, the subagent cannot exceed them regardless of what its inputs instruct it to do.