CONCEPT Cited by 1 source

Sub-agent¶

Definition¶

A sub-agent is an LLM agent spawned by another agent, with its own separate context array and typically its own tool allowlist, invoked to do a bounded task on behalf of a parent agent. The parent sees the sub-agent as a single call that returns a summary (or a structured result); the sub-agent's full transcript never enters the parent's context window.

Fly.io's framing demystifies the primitive:

"People make a huge deal out of Claude Code's sub-agents, but you can see now how trivial they are to implement: just a new context array, another call to the model. Give each call different tools. Make sub-agents talk to each other, summarize each other, collate and aggregate. Build tree structures out of them. Feed them back through the LLM to summarize them as a form of on-the-fly compression, whatever you like." (Source: sources/2025-11-06-flyio-you-should-write-an-agent.)

Once you accept that a "conversation" is a Python list of strings (concepts/agent-loop-stateless-llm), a sub-agent is a second list with a second LLM call against it — nothing more.

What sub-agents buy you¶

Context-window isolation. The sub-agent's exploration — tool calls, dead-ends, large intermediate outputs — does not consume the parent's token budget. Only the return value does.
Tool-surface narrowing. Each sub-agent can be given only the tools it needs for its task. The parent's "describe-everything tool inventory" is replaced by "call-a-specialist tool inventory", reducing per-turn schema overhead (patterns/tool-surface-minimization).
Parallelism / composition. Multiple sub-agents can run in parallel over disjoint inputs; their outputs can be collated, aggregated, or fed to a judge/coordinator sub-agent. Trees of sub-agents are straightforward — they're just trees of lists of strings.
Security segregation. Hostile tool output goes into the sub-agent's context, not the parent's — a direct shape supporting the prompt-injection defence pattern patterns/untrusted-input-via-file-not-prompt and the general principle of keeping hostile data off the main planner.

Prior wiki instances¶

This wiki has multiple sub-agent instances that predate the Fly.io canonicalisation:

Cloudflare AI Code Review (2026-04-20) — the coordinator agent spawns a specialised-reviewer sub-agent per review category (security / perf / correctness / style), each with its own narrow tool allowlist and prompt. See patterns/coordinator-sub-reviewer-orchestration + patterns/specialized-reviewer-agents.
Claude Code / Goose sub-agents — the IDE-side productised form Fly.io points at.
Specialised-agent-decomposition pattern (patterns/specialized-agent-decomposition) captures the general shape: one planner, N narrow executors, each with a context and tool set tuned to its concern.

Design heuristics (Fly.io)¶

"Your wackiest idea will probably (1) work and (2) take 30 minutes to code." Sub-agent experimentation is cheap enough that the correct move is to try it, not to architect it.
The right intermediate format between parent and child (JSON, SQL, markdown summary) is still an open question — concepts/context-engineering treats it as a real programming problem.
How to stop a sub-agent from early-exiting its loop by lying to itself about success ("How best to connect agents to ground truth so they can't lie to themselves about having solved a problem too early to exit their loops") is also open — the usual answer is wiring the sub-agent's exit condition to an external executable verifier (tests green, compiler clean), cf. concepts/agentic-development-loop.

Seen in¶

Fly.io, You Should Write An Agent (2025-11-06) — canonical demystification of sub-agents as "just a new context array, another call to the model". (Source: sources/2025-11-06-flyio-you-should-write-an-agent.)
Cloudflare AI Code Review (2026-04-20) — coordinator + specialised-reviewer sub-agents.
Fly.io Phoenix.new (2025-06-20) — implicit sub-agent model where the agent shelling out to gh or running tests in the VM uses local-call/local-agent-like shapes.