Ask Knox

Three subagents completed their work. The web search agent found 47 relevant sources. The document analysis agent extracted key findings from each. The synthesis agent produced a well-structured report.

The report covered only visual arts. Music, writing, and film production were completely absent.

Every subagent performed flawlessly within its assigned scope. The coordinator was the failure point — it decomposed "creative industries" into "digital art," "graphic design," and "photography," and never assigned the rest. The downstream agents had no way to know what they were never asked to do.

The Hub-and-Spoke Architecture

Every multi-agent system in the Claude Agent SDK follows a hub-and-spoke pattern. One coordinator manages all communication. Subagents never talk to each other directly.

This is not a suggestion. It is an architectural constraint with specific reasons:

Observability. All information flows through a single point where it can be logged, inspected, and debugged.
Error handling. The coordinator decides how to handle failures — retry, reroute, or degrade gracefully. Subagents that communicate directly cannot make system-level recovery decisions.
Information routing. The coordinator decides what context each subagent needs. Without this control, subagents would either receive too much context (wasting tokens, diluting attention) or too little (producing incomplete results).

The coordinator's responsibilities are specific and testable: task decomposition (breaking a broad query into assignable subtasks), delegation (spawning the right subagent with the right context), result aggregation (combining subagent outputs into a coherent whole), and gap detection (evaluating whether the aggregated result actually covers the original query).

The Task Tool as Spawning Mechanism

In the Agent SDK, subagents are spawned through the Task tool. This is not an abstraction — it is the literal mechanism. A coordinator that needs to invoke subagents must have "Task" in its allowedTools configuration.

const coordinator: AgentDefinition = {
  name: "research-coordinator",
  description: "Coordinates multi-agent research by decomposing queries and delegating to specialists",
  systemPrompt: `You are a research coordinator. Analyze the query,
    decompose it into subtasks that cover the full scope, and delegate
    each subtask to the appropriate specialist agent. After receiving
    results, evaluate coverage and re-delegate if gaps exist.`,
  allowedTools: ["Task"],  // Required for subagent spawning
};

Each Task tool call includes the subagent's name and a prompt. That prompt is the only context the subagent receives from the coordinator. This is the most tested concept on the CCA exam.

Context Isolation: The Hard Rule

Subagents operate in complete isolation. They do not inherit the coordinator's conversation history. They do not see other subagents' results. They do not have access to previous tool call outputs from the coordinator's session.

If the coordinator wants the synthesis subagent to work with web search results, it must include those results directly in the Task prompt:

// The coordinator's Task tool call to the synthesis agent
{
  tool: "Task",
  input: {
    agent: "synthesis-agent",
    prompt: `Synthesize findings on AI in creative industries.

    WEB SEARCH RESULTS:
    ${JSON.stringify(webSearchResults)}

    DOCUMENT ANALYSIS:
    ${JSON.stringify(documentAnalysis)}

    Requirements: Cover all domains mentioned. Flag any
    gaps where source material is insufficient.`
  }
}

The parallel holds. Subagents with implicit context assumptions are subagents operating on incomplete information. The coordinator must pass context explicitly — complete findings, source URLs, document names, page numbers — because the subagent has no other way to obtain it.

Parallel Subagent Execution

When subtasks are independent — web search and document analysis can run simultaneously — the coordinator emits multiple Task tool calls in a single response. The Agent SDK runs them concurrently.

When subtasks have dependencies — synthesis depends on search and analysis results — the coordinator must wait for the first batch to complete before spawning the dependent subagent.

The exam tests whether you understand when parallel execution is valid (independent subtasks) versus when sequential execution is required (dependent subtasks). The mechanism is the same in both cases — Task tool calls — but the coordinator's reasoning about ordering is what the CCA evaluates.

Iterative Refinement: The Gap Detection Loop

A coordinator that delegates once and accepts whatever comes back is a weak coordinator. Production systems implement iterative refinement:

Coordinator decomposes the query and delegates to subagents
Subagents return results
Coordinator evaluates the aggregated output against the original query
If gaps exist, the coordinator re-delegates with targeted queries
Re-invokes synthesis with the expanded result set

// Coordinator evaluates synthesis output
// If coverage is insufficient, it re-delegates:
{
  tool: "Task",
  input: {
    agent: "web-search-agent",
    prompt: `The current research on "AI in creative industries"
    covers visual arts thoroughly but has no findings on:
    - Music composition and production
    - Creative writing and publishing
    - Film production and editing

    Search specifically for these missing domains.
    Return structured findings with source URLs.`
  }
}

fork_session: Divergent Exploration

fork_session creates an independent copy of the current conversation state. The fork inherits the analysis baseline — everything discussed so far — but subsequent messages in the fork do not affect the original session.

Use cases tested on the CCA:

Comparing two testing strategies from the same codebase analysis
Exploring alternative refactoring approaches without committing to one
Running parallel investigation branches that may reach different conclusions

The key distinction: forking preserves existing context (unlike spawning a new subagent, which starts empty). Forking is for "explore two paths from this point." Subagent spawning is for "execute this specific task with this specific context."

The Narrow Decomposition Trap

The exam question about "AI in creative industries" being decomposed into only visual arts is drawn directly from Task Statement 1.2. It tests a specific failure mode: the coordinator's task decomposition is too narrow, and the subagents — which have no awareness of the broader scope — execute their narrow assignments perfectly.

The fix is not more subagents. It is a better coordinator prompt that requires broad decomposition and self-evaluation of coverage before delegation.

Lesson 124 Drill

Apply these checks to any multi-agent system you design or evaluate:

Verify the coordinator has "Task" in its allowedTools configuration
For each subagent invocation, confirm that all necessary context is passed explicitly in the Task prompt — never assume inheritance
Identify which subtasks are independent (can run in parallel) versus dependent (must run sequentially)
Write a coordinator prompt that specifies goals and quality criteria, not step-by-step procedures
Add a gap detection step: after receiving subagent results, the coordinator evaluates coverage against the original query before producing final output
Test with broad queries to verify the coordinator decomposes comprehensively, not narrowly

Bottom Line

The coordinator-subagent architecture is not a framework feature. It is an information routing pattern with a specific set of rules: context is explicit, communication routes through the hub, and the coordinator owns decomposition quality.

When the CCA exam presents a multi-agent system that produces correct but incomplete results, the root cause is almost always the coordinator — either its decomposition was too narrow, or it failed to pass sufficient context to the subagents. The subagents themselves are doing exactly what they were told. The question is whether what they were told was sufficient.

The coordinator routes. The subagents execute. The gap between those two responsibilities is where production multi-agent systems fail — and where the CCA exam finds its hardest questions.

Multi-Agent Orchestration with Agent SDK — Coordinators, Subagents, and fork_session