On this page
TLDR
Subagents are specialized, isolated agents spawned by a coordinator to handle domain-specific tasks while preserving conversation isolation. A standard subagent does not see the coordinator's conversation history, so the task message must carry what it needs. Hub-and-spoke prevents context creep from parallel work.
What you are deciding
A subagent is a separate worker with its own context window, started from a task message the coordinator writes. Delegate when the side work is verbose or self-contained, pass only what the worker needs, and take back a short structured result.
What should I delegate, what context crosses the boundary, and what comes back?
What it is
A subagent is a specialized assistant the coordinator spawns to handle a focused task in isolation. It receives an explicit task string, runs in its own fresh context window, and returns only a structured summary. The intermediate work (file reads, searches, tool calls) stays out of the coordinator's context. From the coordinator's perspective the subagent is a black box: task in, summary out.
The mental model is hub-and-spoke. The coordinator (hub) owns task decomposition and result aggregation. Subagents (spokes) are workers that start with a fresh context: a standard subagent does not see the coordinator's conversation history (a fork is the exception), so the facts it needs must be embedded in its task message. In Claude Code a subagent also starts with the CLAUDE.md files, unless it is built-in Explore or Plan or sets omitClaudeMd. Subagents report back to the coordinator rather than talking to each other. This isolation is what lets subagents run in parallel without the context explosion that would kill a single mega-loop.
Subagents are scoped by three mechanisms: system prompt (the role description), allowed-tools (the SDK-enforced tool list), and output format (the shape of the summary). A code-review subagent gets [Read, Grep, Bash] but not Edit. A retriever gets [Read, Glob, WebSearch] but no destructive capability. The contract is tool-based, not language-based: the SDK enforces the allowed-tools list, you don't have to hope the subagent respects a prompt suggestion.
Production subagent failures cluster around three gaps: missing task context (the coordinator assumes the subagent knows facts it doesn't), vague output formats (the subagent doesn't know when to stop), and overscoped tools (Edit access on a reviewer that should only read). Each is a coordination bug, not a model limitation. The exam tests whether you recognize the right delegation signals: verbose work, parallel tasks, and read-only analysis are the canonical triggers for subagents over inline loops.
How each certification frames it
CCD-F: How CCD-F tests subagents and context isolation
CCDVF-D1-O1Agent Architecture: principles, patterns, and tradeoffs of agent and workflow architecture, including the decision criteria for using a workflow versus an agent, the structure of manager/supervisor hierarchies, and the role of subagents in improving task executionCCDVF-D1-O3Agent Patterns and Frameworks: common agent design patterns (tool-use loops, sub-agents, memory, context-window management) and agentic abstraction frameworks (e.g., Strands, LangGraph, PydanticAI) for building agents and workflows for multi-step tasksCCDVF-D6-O1Context Engineering: context and memory management techniques for Claude applications, including context window management, prevention of context drift and bloat (tool output pruning, compaction), and context isolation through subagents or multi-step agentic workflows
The Developer guide covers the role of subagents in improving task execution and sub-agents as an agent pattern (PDF page 5, Domain 1), and context isolation through subagents (PDF page 7, Domain 6). Claude Code's documentation says a standard subagent does not see the parent conversation history and works from the delegation message, with its own system prompt, tools and permissions.
That documentation also lists what a subagent does start with, such as CLAUDE.md files and a git status snapshot, and notes that a fork inherits the whole conversation. A subagent returns its final result and keeps intermediate tool calls out of the main context.
CCA-P: How CCA-P tests coordinator topology and failure ownership
CCARP-D1-O4Design multi-agent systems and orchestration strategies
The Professional guide lists designing multi-agent systems and orchestration strategies (PDF page 4, Domain 1). Anthropic describes orchestrator-workers as a central model that breaks a task down, delegates to workers and synthesizes their results, unlike parallelization where the subtasks are fixed in advance.
Treat each delegation as a contract: the inputs the worker receives, the tools it may use, the shape of what it returns and what counts as done. The coordinator owns decomposition and synthesis, and each worker owns the quality of its own subtask result.
How it works
The coordinator invokes a subagent by passing three inputs: name (the subagent's identifier), task (a self-contained text description), and optional context metadata. The SDK spawns a fresh agent context, loads the subagent's system prompt and tool definitions from configuration, and starts an independent agentic loop inside the subagent. The subagent reads the task, plans, executes tools, and loops on stop_reason exactly as a standalone loop would.
The message list inside the subagent is isolated from the coordinator. Every file read, every tool call, every intermediate result stays in that nested context window. This is the efficiency win: if a code-review subagent reads 20 files to find one bug, the coordinator pays no token cost for those 20 reads. Only the final structured report ("vulnerability in auth.ts line 47, severity high") returns.
When the subagent reaches stop_reason: "end_turn", it emits a final message. The SDK extracts the text and returns it to the coordinator as a tool_result block. Each new invocation of a standard subagent starts with a fresh context, so the coordinator gets back only the final result, not the intermediate work. Per Anthropic's Claude Code sub-agents documentation, a resumed subagent retains its full conversation history, including earlier tool calls and results, and a fork is the exception that inherits the parent conversation instead of starting fresh. Plan on a new invocation with a self-contained task unless you deliberately resume or fork.
Parallel execution is free. If a coordinator needs four subagents to analyze four repos, the SDK spawns all four simultaneously, awaits all four results, and aggregates them. Each subagent runs in its own context window with no contention; the cost is four separate completions but the speedup and context cleanliness justify it for any decomposable task. The pattern collapses cleanly to one subagent when work isn't parallelizable.
Worked example: a research coordinator with two specialists
Authored teaching example, not a bank question.
A coordinator must produce a briefing on a new product category using a market specialist and a regulatory specialist.
| Worker | Receives | Returns | Tools |
|---|---|---|---|
| Market specialist | Category, questions, allowed source types | Findings with sources, confidence and gaps | Search and read only |
| Regulatory specialist | Region, questions, allowed source types | Findings with sources, confidence and gaps | Search and read only |
The coordinator's context holds findings, not search noise. Check afterwards that each specialist task message was self-contained and that the final briefing lists any recorded gaps.
How this decision goes wrong
Missing task context
Looks right: The subagent can see what the coordinator saw, so a short instruction is enough.
Why it fails: A standard subagent does not inherit the conversation. A thin task message leaves it guessing or working on the wrong thing.
Instead: Write a self-contained task message with the goal, the facts it needs and the return format.
Unnecessary delegation
Looks right: Splitting every task across subagents is always more scalable.
Why it fails: A subagent starts fresh, which costs latency, and tasks that need frequent back-and-forth or share heavy context fit the main conversation better.
Instead: Delegate verbose, self-contained work. Keep tightly coupled or quick work in the main conversation.
Returning every intermediate result
Looks right: Passing the full transcript back keeps nothing hidden.
Why it fails: The coordinator's context fills with worker detail, which defeats the isolation that justified delegating.
Instead: Return a condensed, structured result and keep the raw detail in the worker.
Where you'll see it
Parallel multi-repo code analysis
The coordinator gets a task: "find all references to the deprecated client across our 12 repos." Instead of visiting each repo in a massive inline loop (token explosion), it spawns four subagents in parallel, each scoped to three repos. Each subagent reads files, greps imports, returns a structured report. The coordinator merges the four reports and deduplicates. Without parallelization the same task consumes roughly 5x more tokens because every read accumulates in the main context.
Code-review subagent in CI/CD
On every PR, a CI pipeline invokes a code-review subagent with the PR diff. The subagent is restricted to [Read, Grep, Bash], no Edit. It examines security, performance, and maintainability, and returns a JSON report. The pipeline decides whether to approve, request changes, or escalate. Without isolation the 50+ file reads pollute the main context; with the subagent, the main thread sees only the structured verdict.
Show 2 more examples
Knowledge-base retriever subagent
A user asks a general question: "What's our refund policy for SaaS subscriptions?" A retriever subagent is spawned with [Read, Glob, WebSearch]. It searches internal docs and web, summarizes findings, returns a single answer. The coordinator never sees the eight intermediate searches or the three docs that were skipped. The output is clean, directly usable, and audit-ready.
Structured extraction with a dedicated extractor
An invoice-processing pipeline receives a scanned PDF. Rather than have the main agent loop through 40 pages of OCR, a dedicated extraction subagent is spawned with a precise output format {vendor, amount, date, items[]}. It runs, returns the structured data, and exits. The main pipeline continues without ever seeing the intermediate OCR noise or abandoned extraction attempts.
Code examples
# Coordinator delegates to subagents in parallel.
# Each subagent runs in isolation; only the summary returns.
import asyncio
from anthropic import Anthropic
client = Anthropic()
async def review_repo(name: str, files: list[str]) -> dict:
"""Spawn a code-review subagent for one repo."""
task = f"""Review the codebase in {name}.
Files to check: {", ".join(files)}
Return JSON:
{{
"verdict": "approved" | "needs_rework" | "hold",
"critical_issues": [{{"file": "...", "line": N, "issue": "..."}}],
"minor_issues": [...]
}}"""
# In Claude Code SDK this is invoke_subagent("code-reviewer", task)
resp = await asyncio.to_thread(
client.messages.create,
model="claude-opus-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": task}],
)
return {"repo": name, "review": resp.content[0].text}
async def coordinate(repos: dict[str, list[str]]) -> dict:
"""Spawn one subagent per repo in parallel and aggregate."""
results = await asyncio.gather(*[
review_repo(name, files) for name, files in repos.items()
])
return {
"total": len(results),
"reviews": results,
"verdict": "approved" if all(
r["review"].get("verdict") == "approved" for r in results
) else "needs_review",
}
asyncio.run(coordinate({
"auth-service": ["auth.py", "oauth.py"],
"payment-service": ["payments.py", "webhooks.py"],
}))Looks right, isn't
Each row pairs a plausible-looking pattern with the failure it actually creates. These are the shapes exam distractors are built from.
Pass the entire coordinator conversation history to the subagent so it has full context.
A standard subagent does not see the coordinator's history, and passing all prior messages wastes its context.
Embed the facts it needs in the task string, make it self-contained.
Two subagents can coordinate with each other to share results.
In the standard coordinator pattern a subagent reports its result back to the coordinator.
If A's output feeds B's input, the coordinator orchestrates: run A, collect its summary, pass that into B's task string. (Claude Code also documents agent teams and a SendMessage tool as a separate mechanism; check the sub-agents documentation before relying on direct messaging.)
Give every subagent full tool access (Edit, Bash, all of them) so it can handle any task.
Tool scope must match the role.
A reviewer should not have Edit. A retriever should not have Bash. Overscoping causes accidental side effects (file edits, deployments) and obscures intent. Restrict to the minimum needed.
A vague output format is fine, the subagent will figure out when it's done.
Without a defined output format, subagents wander and run too long.
Structured formats (JSON, fixed sections) create natural stopping points. A good subagent config includes an explicit output shape exactly because it doubles as a termination cue.
Subagent failure should trigger a retry with the same task.
Retries succeed only if the failure was transient.
If the task is ambiguous or the tool set is wrong, retrying burns tokens without fixing the root cause. Debug the task string, the tool restrictions, and the output format first; retry second.
Side-by-side
| Aspect | Subagent (isolated) | Inline agentic loop | Parallel subagents | Sequential coordinator |
|---|---|---|---|---|
| Context window | Isolated; discarded after | Grows monotonically | N fresh windows | Main stays clean |
| Parallel execution | Yes, N concurrent | Single-threaded | Natural; N tasks async | Never parallel |
| Tool access | Scoped per role | Full set | Scoped per subagent | Full set |
| Output shape | Structured summary only | Full message history | N summaries merged | Single result |
| Visibility | Black box, no intermediate work shown | Every tool call visible | Summary only per subagent | Every step logged |
| Best for | Verbose or read-only tasks | 3 to 15 turn loops | 4+ parallel tasks | Fixed sequential pipelines |
Decision tree
Will the work produce verbose intermediate output (file reads, searches, false starts)?
Are the tasks independent and parallelizable (4 repos, each analyzed separately)?
Should this agent be unable to modify files (read-only analysis)?
allowed-tools to [Read, Grep, Glob, WebSearch]. Omit Edit, Bash, Write.Can the task be expressed as a self-contained string without prior context?
Does the output need a strict format (JSON, structured sections, checklist)?
The exam trap
Many assume subagents inherit the coordinator's conversation history. A standard subagent does not: it starts with a fresh context window (a fork is the exception, it inherits the parent conversation). What it needs from the conversation must be passed explicitly in the task message, making context-passing strategy critical for refinement loops.
Question patterns
CCD-F practice questions
2 approved CCD-F questions for this topic. Tap an answer to check it, then read the rationale for every option.
A media-research coordinator must assess one unfamiliar patent dispute while preserving its context for the broader market report. The assessment requires several searches and a focused legal-technical synthesis. Which design best uses a subagent?
CCA-F practice questions
2 approved CCA-F questions for this topic. Tap an answer to check it, then read the rationale for every option.
A subagent returns wrong facts about a customer the coordinator clearly mentioned earlier in its own conversation. Why?
CCA-P practice questions
2 approved CCA-P questions for this topic. Tap an answer to check it, then read the rationale for every option.
A multi-agent system has a lead agent spawn five subagents to each independently propose a fix for the same bug in a shared codebase, then apply whichever fix returns first. In production this caused two subagents' file edits to overwrite each other in a race condition. What is the core orchestration design flaw?
Frequently asked
Showing 14 of 14 questions
while block in the coordinator that runs tool_use to tool_result cycles. A subagent is a separate execution: the coordinator spawns it, it loops internally, and returns a summary. Subagents are best for isolated tasks; loops are best for single threads with complex tool interactions.tool_result blocks, then append them to the coordinator's message list in a single user-role block. The coordinator can now reason over all N results together.stop_reason: "max_tokens" with a partial summary. Handle it in the coordinator: either accept the partial result or spawn a new subagent with a refined task ("focus on files X to Y only").max_iterations, define a clear output format (so the subagent knows when it's done), and ensure the task is well-scoped. A wandering subagent is usually a sign of vague task or vague output format.allowed-tools list) or MCP definitions (via .mcp.json). Tool access is scoped per subagent; the SDK enforces the restrictions.Sources and next steps
- Claude Certified Developer - Foundations Exam Guide v1.0 (July 2026), PDF page 5, section: Domain 1: Agents and Workflows (Agent Architecture, Agent Construction, Agent Patterns). Checked 2026-10-16.
- Claude Certified Developer - Foundations Exam Guide v1.0 (July 2026), PDF page 7, section: Domain 4: Debugging and Error Handling; Domain 6: Context Engineering. Checked 2026-10-16.
- Claude Certified Architect - Professional Exam Guide v1.0 (July 2026), PDF page 4, section: Domains 1 and 2, detailed objectives. Checked 2026-10-16.
- Create custom subagents (Claude Code docs), section: What a subagent receives; Subagents vs the main conversation. Checked 2026-10-16.
- Effective context engineering for AI agents (Anthropic engineering), section: Context as a finite resource; Compaction; Structured note-taking; Sub-agent architectures; Tool-set bloat. Checked 2026-10-16.
- Building effective agents (Anthropic engineering), section: Prompt chaining; Parallelization; Orchestrator-workers; Agents. Checked 2026-10-16.