Claude Certification Guide CCAR-F

Curriculum › Agentic Architecture & Orchestration · 27% of the exam

Subagent invocation and context passing

What you’ll be able to do

  • Configure a coordinator to spawn subagents through the Task tool, with “Task” included in allowedTools
  • Define each subagent type with an AgentDefinition: description, system prompt, and tool restrictions
  • Pass complete prior findings in the subagent’s prompt, structured so content stays separate from attribution metadata
  • Spawn parallel subagents by emitting multiple Task tool calls in a single coordinator response
  • Write coordinator prompts that set research goals and quality criteria rather than step-by-step procedures

What you need to know

The Task tool is how subagents get spawned

In the Claude Agent SDK, a coordinator spawns a subagent by calling the Task tool. From the coordinator's point of view it's a tool call like any other: it names the subagent type and supplies a prompt, and the subagent's final output comes back as the tool result. Because it is a tool, the normal tool permissions apply — the coordinator's allowedTools must include "Task". Leave it out and the coordinator can describe the delegation it would like to do, but it can't actually spawn anything.

AgentDefinition: one configuration per subagent type

Each subagent type is configured with an AgentDefinition, which carries three things:

  • Description — what this subagent is for. The coordinator reads it to decide when to delegate to this type, so it should state the job and its boundaries clearly.
  • System prompt — the subagent's role, standards, and output expectations.
  • Tool restrictions — the tools this type may use. A synthesis agent that only combines findings it's given doesn't need web search; a search agent doesn't need to write reports.
illustrative shape — check the SDK reference for exact field names in your language
options = { allowedTools: ["Task"], // without "Task", no subagents can be spawned agents: { "web-search": { // an AgentDefinition description: "Finds and returns sources for one assigned research subtopic.", prompt: "You are a web research specialist. Return every claim with its source URL.", tools: ["WebSearch", "WebFetch"] }, "synthesis": { description: "Combines findings it is given into a cited summary. Does not search.", prompt: "Synthesize only the findings provided. Preserve every citation.", tools: ["Read"] } } }

Context must be passed explicitly

A spawned subagent does not inherit the coordinator's conversation and does not share memory between invocations — calling the same subagent type twice gives you two strangers. It knows its AgentDefinition and the prompt the coordinator writes, nothing else.

So when a subtask builds on earlier work, the coordinator must include the complete findings directly in the prompt. A synthesis subagent told "summarize what the search agent found" has no idea what that was. Pass the actual web search results and the actual document-analysis outputs. A recap or a pointer to "earlier results" forces the subagent to guess, and a guessing synthesis agent invents findings.

Structure the handoff to keep attribution intact

How findings are passed matters as much as whether they are. If the coordinator flattens everything into a paragraph, the source URLs, document names, and page numbers blur into the text or disappear, and the final report can't cite reliably. Use a structured format that keeps the content of each finding separate from its metadata:

before — prose recap, attribution lost
"The search agent found that several studies show heat deaths rising, and one report mentioned cooling centers helped. Please synthesize."
after — content and metadata in separate fields
{ "findings": [ { "claim": "Heat-related ER visits rose 18% between 2019 and 2024", "source_url": "https://example.org/heat-report", "document": "County Heat Health Report 2024", "page": 12 }, { "claim": "Extended cooling-center hours reduced heat calls", "source_url": "https://example.org/cooling-eval", "document": "Cooling Center Evaluation", "page": 4 } ] }

Parallel subagents: many Task calls, one response

When subtasks are independent — three search subagents each covering a different subtopic — the coordinator should spawn them in parallel by emitting multiple Task tool calls in a single response. They then run concurrently and their results come back together. Emitting one Task call, waiting for its result, then emitting the next turns parallel work into a sequential chain and multiplies latency for no benefit.

Goals and quality criteria, not procedures

The prompt the coordinator writes for a subagent should say what is needed and how good it has to be — the research goal, scope, what counts as a credible source, the required output fields — not a step-by-step script ("search X, then open the first three results, then…"). Subagents are useful because they can adapt to what they find. A procedural script removes that, and breaks the moment reality doesn't match the script.

Forking for divergent approaches

Sometimes you want two different approaches explored from the same starting analysis. Fork-based session management creates independent branches from a shared baseline so each can diverge without contaminating the other. The mechanics (fork_session) are covered in lesson 1.7.

Key concept

Subagents are spawned with the Task tool (“Task” must be in allowedTools), configured by an AgentDefinition, and inherit nothing. The coordinator passes complete, structured findings, fans out with several Task calls in one response, and specifies goals and quality criteria rather than procedures.

When a subagent "should have known" something, check whether it was ever in its prompt. When a coordinator won't delegate at all, check allowedTools for "Task".

Practice scenario

ScenarioIn a research system, final reports contain accurate claims but frequently cite the wrong document or no page number. Each run also takes much longer than expected: logs show the coordinator spawning its three search subagents one after another, each in its own turn. The coordinator passes findings to synthesis as a paragraph it writes summarizing "what the searches turned up."
Work it through, then open this

Two separate fixes. Attribution: the coordinator’s prose summary merges claims and sources, so synthesis can’t map each claim to its document and page. Pass the complete findings in a structured format with content and metadata (source URL, document name, page) in separate fields. Latency: the three searches are independent, so the coordinator should emit all three Task calls in a single response, letting them run in parallel instead of across three turns.

Build exercise — Wire a coordinator with two subagent types

Intermediate · 30 min

What you’ll learn

  • Configuring the Task tool and AgentDefinitions
  • Emitting parallel Task calls from one coordinator response
  • Passing structured findings that preserve attribution

  1. Define two subagent types with AgentDefinitions — a search agent and a synthesis agent — each with a clear description, a focused system prompt, and only the tools it needs. Add “Task” to the coordinator’s allowedTools.

    • Why: The coordinator chooses subagents from their descriptions and can only spawn them if the Task tool is allowed.
    • You should see: The coordinator successfully spawning a subagent; remove “Task” once to confirm delegation stops working.

  2. Prompt the coordinator to research a topic with three independent subtopics, and check the first coordinator response.

    • Why: Parallel spawning happens when multiple Task calls are emitted in one response, not across turns.
    • You should see: Three Task tool calls in a single response. If they arrive one per turn, revise the coordinator prompt to fan out independent subtopics together.

  3. Have the coordinator pass the search results to synthesis as structured records (claim, source URL, document, page) and state goals and quality criteria (“every claim cited; flag weakly supported claims”) instead of steps.

    • Why: Synthesis has none of the search context unless it’s passed, and structure keeps attribution intact.
    • You should see: A synthesis output where every claim carries the correct source and page.

Exam traps

Expecting a coordinator to spawn subagents when its allowedTools doesn’t include “Task”

Spawning a subagent is a Task tool call. If the tool isn’t allowed, delegation can’t happen.

Assuming a subagent inherits the coordinator’s conversation history or remembers earlier invocations

Each invocation starts isolated. Context must be written into the prompt every time.

Passing a vague pointer or lossy recap instead of the complete findings the subtask depends on

A synthesis agent can only combine what it receives. Pass the actual search results and analysis outputs.

Flattening findings into prose so source URLs, document names, and page numbers are lost

Structured data that separates content from metadata is what lets downstream agents keep citations correct.

Spawning parallel subagents one per turn instead of as multiple Task calls in one response

Independent subagents run in parallel only when the coordinator emits their Task calls together.

Scripting a subagent with step-by-step procedures instead of goals and quality criteria

Procedures strip out the adaptability that makes subagents useful. State what’s needed and the bar it must meet.

Sources

Quick check

A research system produces a report on "the economic effects of an aging population." Every subagent returns accurate, well-cited findings, but the report covers only pensions and healthcare costs, with nothing on labor markets, housing, or consumer spending. The coordinator's logs show two subtasks: "pension system strain" and "healthcare spending growth." Which change most directly addresses this?