Claude Multi-Agent Coordinator and Subagent Design

The coordinator owns the plan. It decomposes the question, picks subagents, sends each a task, collects results and decides what happens next. Subagents never talk to each other. The exam guide calls this hub-and-spoke: all communication, error handling and information routing go through the coordinator.

flowchart LR
    U[User question] --> C((Coordinator))
    C -->|task prompt| W[Web search subagent]
    C -->|task prompt| D[Document analysis subagent]
    W -->|structured findings| C
    D -->|structured findings| C
    C -->|all findings in prompt| S[Synthesis subagent]
    S -->|draft with citations| C
    C --> R[Final report]

The hub gives you one place for logging, consistent error handling and control over what each subagent sees. A design where search sends results straight to synthesis loses all three, and it is a common wrong answer.

The coordinator also scales effort to the query: the guide expects it to pick subagents by query complexity instead of always running the full pipeline.

No. A subagent starts with a fresh context. It does not see the coordinator's conversation history, earlier tool results or system prompt, and it keeps no memory between calls. The task prompt the coordinator writes is the only content passed in, so every finding, file path and decision the subagent needs must be written into that prompt.

So "Using the search results above, write the summary" fails: the synthesis subagent never saw anything above. Passing the whole coordinator transcript is the opposite mistake, because it buries the task in planning chatter. Pass the findings the subagent needs, as structured records.

A minimal coordinator setup with the Python Agent SDK:

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    system_prompt=(
        "Goal: a cited report that answers the user's question. "
        "Quality bar: every claim has a source; report conflicts and gaps. "
        "Launch independent research subagents in the same response."
    ),
    allowed_tools=["Agent"],  # the exam guide calls this tool "Task"
    agents={
        "web-search": AgentDefinition(
            description="Researches ONE assigned subtopic on the web.",
            prompt="Return findings as JSON records with claim, source_url, excerpt, published_date.",
            tools=["WebSearch", "WebFetch"],
        ),
        "synthesis": AgentDefinition(
            description="Writes the report from findings supplied in its prompt.",
            prompt="Use only the records you are given. Keep every source_url.",
            tools=[],
        ),
    },
)

Without the spawning tool in its allowed tools, the coordinator cannot delegate and does all the research itself. The coordinator prompt states a goal and a quality bar instead of steps, which the guide prefers.

⚠ The exam guide names the spawning tool Task and says allowedTools must include "Task". Current Agent SDK docs name it Agent, and newer releases let subagents spawn their own subagents. On the exam, go with the guide.

Split the question into distinct slices that together cover all of it. The guide names overly narrow decomposition as a risk: if "plastic recycling policy in Southeast Asia" becomes three subtasks about Vietnam, Thailand and Vietnamese packaging law, every subagent can succeed and the report still misses most of the region.

Partition by subtopic or source type so subagents do not duplicate searches. Then run the refinement loop: the coordinator checks the synthesis for gaps, re-delegates targeted queries, and calls synthesis again until coverage is sufficient.

Independent subtasks should run in parallel: the guide's pattern is several Task calls in one coordinator response, not one call per turn. Four country searches then take about as long as the slowest one. Stay sequential only when a step needs another's output, as synthesis needs the research.

With structured error context: failure type, what was attempted, partial results and possible alternatives. A generic "search unavailable" hides what the coordinator needs. An empty list marked as success is worse: the coordinator turns a failed lookup into a confident claim of absence.

The guide separates access failures (timeouts that need a retry decision) from valid empty results (a query that ran and matched nothing). Make them different statuses:

{
  "status": "partial",
  "query": "Indonesia plastic recycling target 2025 site:go.id",
  "findings": [{"claim": "...", "source_url": "...", "published_date": "2024-06-12"}],
  "failure": {"type": "timeout", "attempts": 3, "detail": "Government portal did not respond"},
  "alternatives": ["UNEP country profile", "national news archive"]
}

Subagents should retry transient failures locally with a small, fixed budget, then report. A subagent that retries forever never returns, so the coordinator cannot reroute. Aborting the whole workflow on one failure is also an anti-pattern, because it discards every result that succeeded. The final report should annotate coverage: which findings are well supported, and which areas have gaps from unavailable sources.

Make provenance part of the data. Each finding travels as a record with the claim, source URL or document name, a supporting excerpt and a date, and the synthesis agent must preserve and merge these mappings. Every free-text summary step is a place where citations drop off.

When two credible sources disagree, report both values with their sources instead of picking one. Dates prevent false conflicts: 31% in 2022 and 45% in 2025 is a trend. The guide also asks for separate sections for well-established and contested findings.

A document analysis subagent finds two credible reports for the same year: one says 38% of small firms use e-invoicing, the other 44%, from different survey samples. What should the subagent do?

A) Return the more recent report's figure. B) Return the average, 41%, and cite both reports. C) Return both values, each with its source, date and method, marked as a conflict for the coordinator to resolve. D) Stop and return an error to the coordinator, because the data is unreliable.

Answer: C. The guide wants conflicting values completed, annotated with attribution, and left for the coordinator to reconcile before synthesis.

• A picks one value arbitrarily; both cover the same year.
• B invents a number neither source reported and hides the disagreement.
• D treats a normal research outcome as a failure and discards finished work.

• The coordinator owns decomposition, routing, error handling and synthesis; subagents never message each other.
• Subagents start with fresh context. Put the findings they need in the task prompt, and leave the rest of the transcript out.
• Partition scope so it covers the whole question, spawn independent subagents in one response, and loop on gaps.
• Report failures with type, attempted query, partial results and alternatives. Keep "failed" and "no matches" apart.
• Carry claim, source, excerpt and date through every step, and report conflicts instead of resolving them silently.