Subagent
Agent SDKDefinition
A Claude instance spawned by an orchestrator to handle one bounded subtask in complete context isolation. Each subagent starts with a fresh context window — the orchestrator's history is never inherited — and is invoked via the [Task tool](/glossary/task-tool). The subagent runs its own full [Agentic Loop](/glossary/agentic-loop), then returns a single structured result to the orchestrator.
Example Usage
A research orchestrator spawns a subagent for web search and another for document parsing. Each receives only the tools and context relevant to its task. Neither subagent can read the other's work mid-flight, and neither inherits the orchestrator's accumulated conversation history.
Why It Matters for the CCA-F Exam
Subagents are central to Domain 1. Exam questions probe three areas: (1) understanding that subagents are context-isolated, not context-sharing; (2) knowing that the Task tool is the invocation mechanism; (3) recognizing over-narrow decomposition as a performance and coordination anti-pattern.
In Depth
Context isolation is the defining property of a subagent, and it is the concept the exam tests most aggressively. When the orchestrator calls the Task tool, the SDK spawns a new Claude instance with a blank context window. Nothing from the orchestrator's conversation history — no prior tool results, no intermediate reasoning, no accumulated context — is automatically shared. Whatever context the subagent needs must be explicitly injected in the Task tool call's prompt. This is a deliberate design: isolation keeps each subagent's context small and cheap, prevents accumulated orchestrator context from tainting the subagent's reasoning, and limits blast radius if a subagent is compromised by Prompt Injection.
The subagent runs a complete autonomous loop — making tool calls, reasoning across turns — and when it finishes, returns one structured result. That result lands in the orchestrator's context as a tool_result block. The subagent's internal reasoning turns are discarded; they never cross the boundary.
Proper subagent design follows Least Privilege (Tool Access): give each subagent only the tools it needs. A web-search subagent should not have file-write access. A code-review subagent should not have network access. The AgentDefinition object is where this tool allow-list is configured statically, before the subagent runs.
The anti-pattern the exam punishes is over-narrow decomposition: splitting a coherent task into so many micro-subagents that the orchestrator spends more tokens coordinating than the subagents spend working. The right granularity is tasks that are independently executable, produce clear outputs, and genuinely benefit from context isolation — not tasks so small that their result is a single word.
Note what subagents are *not*: they are not threads (sequential within their own loop), not processes (they are model calls with isolated prompts), and not microservices (no persistent state beyond the current invocation unless a Session is explicitly passed in). For intercepting the moment a subagent finishes, see SubagentStop Hook.
Frequently Asked Questions
Does a subagent share the orchestrator's conversation history?
No. A subagent starts with a fresh context window. The orchestrator explicitly passes whatever context the subagent needs as part of the Task tool call's prompt. If the orchestrator's history were automatically shared, context isolation — the core benefit of the pattern — would be lost.
What does a subagent return to the orchestrator?
A structured result — typically a final message or a JSON object — injected into the orchestrator's context as a `tool_result` block. The subagent's internal reasoning turns are discarded; only the final output crosses the boundary.
When should I use a subagent vs. an inline tool call?
Use a subagent when the task (a) benefits from its own isolated context, (b) may require multiple tool calls to complete, or (c) should be parallelizable. Use an inline tool call for single, atomic operations — reading a file, running a query — where delegation overhead exceeds the isolation benefit.