# Sub-agent

> VI: https://5ac.vn/wiki/sub-agent/ · EN: https://5ac.vn/en/wiki/sub-agent/ · lang: en · spec_as_of 2026-10-18 (spec no formal spec) · cluster C4

A specialized worker an orchestrating lead agent spawns for one bounded task: it runs in its own context window with its own prompt, tools and permissions, and returns a compressed result.

---
## Definition

A sub-agent is a specialized worker that an orchestrating lead agent spawns for one bounded piece of work: it runs in its own context window with its own prompt, tools and permissions, works independently, and returns a compressed result — keeping the parent conversation clean.

## Mechanism

The reference architecture is the orchestrator-worker pattern Anthropic describes for its Research system (post of 2025-06-13): a lead agent analyzes the query, forms a strategy and spawns subagents running in parallel; each subagent searches its own branch of the assignment and returns curated findings for the lead to synthesize; thin evidence triggers another loop or a strategy fix; before the answer lands, a separate CitationAgent attributes every claim. The architecture wins on compression — "the essence of search is compression": each subagent distills a corpus down to the tokens that matter inside its own context window.

The post's own numbers: a multi-agent setup with Claude Opus 4 as lead and Claude Sonnet 4 subagents beat single-agent Opus 4 by 90.2% on an internal research eval; three variables explain 95% of variance on BrowseComp, token usage alone explains 80%. The price: agents spend roughly 4× the tokens of chat and multi-agent systems roughly 15× — worth it when the task is valuable enough and parallelizes; tasks that force every agent to share one context or carry dense cross-dependencies (most coding) are the named anti-fit.

Claude Code defines the sub-agent close to the machinery: a markdown file with YAML frontmatter (`name`, `description`, `tools`, `model`) that runs in its own context window with its own system prompt, restricted tool access and independent permissions; Claude delegates when a task matches the subagent's `description`. Built-ins: Explore (read-only codebase survey), Plan (research during plan mode) and General-purpose (multi-step explore-and-modify). Scope follows file location in descending priority: managed settings → CLI flag → `.claude/agents/` (project) → `~/.claude/agents/` (user) → plugin directories.

| Component | Anthropic Research | Claude Code |
| --- | --- | --- |
| Who spawns | the lead decomposes the query into subtasks at runtime | Claude delegates when a task matches `description` |
| Effort control | scaling rules baked into prompts: 1 agent with 3–10 tool calls for simple facts, 2–4 subagents × 10–15 calls for comparisons, 10+ for complex research | per-subagent tool and model limits; startup warning once combined descriptions exceed 15,000 tokens |

Anthropic's early failure modes are the sizing lesson: spawning 50 subagents for a trivial query, and duplicated work because task descriptions were vague; fixed by teaching the orchestrator explicit delegation (objective, output format, sources and tools, task boundaries). Another pattern worth copying: let subagents write results to a filesystem and pass a lightweight reference back, instead of shuttling everything through the lead — it avoids the game of telephone and the token cost of copying.

Flow: User → lead agent sets strategy → spawn sub-agents in parallel → synthesize and loop if evidence thin → CitationAgent attributes → final answer

## Spec anchor

No neutral spec defines sub-agents; the working standards are the two vendors' own documentation, so this anchor pins retrieval dates. Claude Code marks several behaviors by product version (v2.1.198 changed the Explore subagent's model inheritance and removed the interactive `/agents` wizard); the canonical URL of the Anthropic post is `/engineering/multi-agent-research-system`.

Sources fetched for this entry:

- <https://www.anthropic.com/engineering/multi-agent-research-system> — "How we built our multi-agent research system", published 2025-06-13 — accessed 2026-10-18
- <https://docs.claude.com/en/docs/claude-code/sub-agents> — "Create custom subagents" (canonical: code.claude.com/docs/en/sub-agents) — accessed 2026-10-18
- <https://arxiv.org/abs/2402.01680> — multi-agent survey abstract page (v2) — accessed 2026-10-18
- <https://export.arxiv.org/api/query?id_list=2402.01680> — arXiv API: verified ID, authors, abstract — accessed 2026-10-18

## Academic anchors

The ID sits in the frontmatter, verified through the arXiv API on 2026-10-18. *Large Language Model based Multi-Agents: A Survey of Progress and Challenges* (arXiv:2402.01680 — Taicheng Guo, Xiuying Chen, Yaqi Wang, Ruidi Chang et al.; submitted 2024-01-21, v2 updated 2024-04-19) frames the underlying questions for every sub-agent design: how agents are profiled, how they communicate, and which mechanisms grow a multi-agent system's capabilities. A sub-agent is the special case of that space: a delegated hierarchy from one orchestrator, rather than peers negotiating.

## FAQ

**How does a sub-agent differ from a single tool call?** A tool call is one step: the model emits arguments, the system executes, a result comes back. A sub-agent is a whole agent loop: reasoning, calling many tools, deciding when it is done, running in its own context window and returning only a compressed result to the orchestrator.

**How does a sub-agent differ from a multi-agent system?** Multi-agent system is the broad domain: any society of agents, including peers debating a problem. Sub-agent names one structural relation: a lead agent spawns and delegates bounded work to workers — the orchestrator-worker pattern.

**Why give every sub-agent its own context window?** Two reasons Anthropic states directly: compression, so the system spends more parallel reasoning tokens than one window could hold, and separation of concerns, which keeps the search branches genuinely independent.

**When should you not use sub-agents?** When the task can't parallelize, when every agent needs the same shared context, or when output value won't cover token spend — multi-agent systems burn roughly 15× the tokens of chat on Anthropic's data. Coding with dense cross-step dependencies is the classic anti-fit.

**How do you declare one in Claude Code?** Write a markdown file with YAML frontmatter (`name`, `description`, `tools`, `model`) into `.claude/agents/` (project scope) or `~/.claude/agents/` (user scope); the `description` field is what Claude matches tasks against when deciding to delegate.

## Related

- [What is a Multi-Agent OS?](/en/blog/what-is-multi-agent-os/)
- [YC open-sources QM — a multi-agent harness](/en/blog/yc-qm-open-source-multi-agent-harness/)
- [What is agent memory?](/en/wiki/agent-memory/)
- [What is agentic RAG?](/en/wiki/agentic-rag/)