Route worker outcomes through one coordinator

Learning objective

Design hub-and-spoke coordination: route subagent communication, aggregation, and failures through the coordinator for control and observability while respecting isolated subagent contexts.

Core idea

For an architect designing multi-agent research, hub-and-spoke coordination gives one agent responsibility for the whole answer. Workers investigate bounded questions and return findings to that coordinator. The coordinator owns delegation, information routing, aggregation, and recovery decisions. A worker’s successful local investigation does not establish that the user’s broader request is complete.

Anthropic describes this as an orchestrator-worker pattern: a central model decomposes a request, delegates work, and synthesizes the results. Treat the topology as a design choice. The Claude Agent SDK supports nested subagents, and a worker with SendMessage can message other named agents. Disable worker delegation and peer messaging to preserve a strictly centralized hub.

How it works

Establish the communication boundary

In the Agent SDK, define specialists through the agents option passed to query(). Each definition has a description for selection and a prompt for the specialist’s behavior. Claude invokes them through the Agent tool. The subagent’s final message returns to its parent; intermediate investigation stays in its own conversation.

For hub-and-spoke operation, make the parent the coordinator and tell each specialist to return findings, requests for additional information, and unresolved dependencies to that parent. The coordinator decides whether another specialist should receive them. Do not let one worker silently revise another worker’s assignment or declare the entire request complete.

Worker output and communication pass through the coordinator, not from one specialist to another.

Instructions alone do not remove capabilities. The SDK’s AgentDefinition.tools field limits the tools available to a specialist. For a local-document researcher, an explicit list such as Read, Grep, and Glob permits inspection without editing or command execution. Exclude SendMessage if peer messaging is outside your topology, and exclude Agent if workers must not delegate. Choose an explicit tool list suited to the actual research source, rather than copying a local-file list into a web-search task.

SDK subagents can spawn further subagents. In SDK releases that bundle Claude Code v2.1.219 or later—TypeScript v0.3.219 and Python v0.2.127 onward—CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH defaults to 3 layers below the main agent. Set it to 1 through the env option to prevent subagents from spawning their own. TypeScript replaces the subprocess environment with env, so preserve needed inherited variables; Python merges env into the inherited environment. This is a runtime boundary, distinct from a prompt asking workers not to delegate.

Send a complete assignment into isolated context

A non-fork subagent’s context window starts fresh, but not empty. The Agent SDK documents what it holds:

The prompt string is the only content you pass from parent to subagent. Include the question, relevant constraints, source locations, and decisions the specialist needs in that invocation. A reference to “the requirement discussed earlier” does not transfer the requirement.

A useful assignment includes a local objective, its relationship to the whole request, allowed sources, an output format, and conditions for reporting incomplete work. Put stable specialist behavior in AgentDefinition.prompt; put request-specific facts in the Agent prompt. See 1.2.2 for dividing the investigation without losing coverage.

Isolation has an explicit exception: forked subagents inherit the parent conversation. In the Agent SDK and non-interactive claude -p, fork mode is off unless you set CLAUDE_CODE_FORK_SUBAGENT to 1, so subagents there start fresh by default. Do not turn “does not inherit automatically” into “cannot inherit.” Even with a fork, the coordinator still needs an assignment and a result contract. Shared starting information does not confer shared authority to change the research plan.

Aggregate evidence and failures explicitly

Ask workers to distinguish findings, evidence locations, caveats, and unfinished obligations. These are application-defined report fields, not automatic SDK result guarantees. The coordinator associates every report with the assignment that produced it, checks support for its claims, and reconciles conflicts before synthesis.

Keep control centralized without copying every large artifact into the coordinator’s context. Anthropic describes workers writing durable artifacts and returning lightweight references. A report path can preserve a full table while the parent receives its conclusion and location. The coordinator must still inspect the relevant evidence and decide how it affects the final answer; artifact storage does not transfer that decision to the worker.

Failure is another outcome to route. Claude Code documents foreground API interruptions that return partial text with an unfinished-task note, or an Agent terminated early due to an API error failure when no usable text was produced. Background failures identify the API error and include the last output. Do not confuse returned partial work with successful completion. Preserve supported findings, mark remaining obligations incomplete, and let the coordinator choose recovery or an explicit limitation.

Observe the routing you actually run

The SDK documents detecting delegation through tool_use blocks named Agent. Some version surfaces use Task, including the system:init tools list; a version-tolerant detector matches both names. The block’s input identifies the specialist through subagent_type: inspect block.input.subagent_type in TypeScript or block.input.get("subagent_type") in Python. A call without that field selects the built-in general-purpose subagent when built-in agents are enabled. Messages inside a subagent carry parent_tool_use_id, which connects their activity to the parent invocation.

Add application records for the assigned scope, outcome, evidence reference, and recovery decision. Those records let you distinguish an unassigned requirement from a failed worker or a rejected result. A final answer alone cannot reveal which of those caused a coverage gap. Keep instrumentation proportional to the investigation and avoid collecting unnecessary sensitive source content.

Key distinctions and trade-offs

Context isolation versus access isolation: Separate conversations keep intermediate content out of the parent’s conversation. Tool restrictions control what the worker can reach or change. One does not establish the other.

Centralized control versus centralized storage: The coordinator can retain decision authority while workers write artifacts elsewhere. Returning an artifact reference differs from sending instructions directly to another worker.

Prompt policy versus runtime enforcement: A prompt defines expected behavior. An explicit tools list and a supported depth limit constrain available actions. Use both when the topology is an invariant.

The coordinator simplifies attribution and recovery but can become an aggregation bottleneck. Concise evidence-bearing reports reduce that load. Summaries that omit qualifications instead create a polished but misleading synthesis.

Architecture / decision scenario

A research agent must compare deployment approaches for a customer-support system. The coordinator assigns separate investigations of operational failure handling and data-handling constraints. Each prompt includes the original comparison criteria because neither fresh worker has the earlier conversation.

One worker needs a constraint found by the other. It reports that dependency to the coordinator, which forwards the relevant evidence and clarifies the assignment. Explicit tool lists exclude peer messaging and delegation; a supported depth limit prevents a worker-created hierarchy. The application logs invocation and parent relationships alongside its assignment records.

The operational researcher then returns partial findings after an API interruption. The coordinator retains verified evidence, records the unfinished portion, and arranges targeted recovery. It reads the referenced data-handling report, reconciles the two results, and produces one answer with an explicit unresolved limitation if recovery cannot finish. Worker output, communication, and failure all pass through the same accountable decision point.

Common exam traps

• Assuming fresh workers receive the coordinator’s conversation history.
• Treating context isolation as a restriction on filesystem or tool access.
• Calling a workflow hub-and-spoke while workers message peers or create uncontrolled descendants.
• Treating a partial report after an API failure as a completed investigation.
• Requiring every artifact byte to pass through the coordinator to preserve control.
• Logging only the final response and losing assignment-to-outcome attribution.

Where the exam guide differs

What to remember

Keep the coordinator responsible for scope, routing, synthesis, and recovery. Send self-contained assignments into fresh contexts, constrain worker capabilities explicitly, and connect each result or failure to its originating task. Forks and artifact references change information transfer; they do not remove the need for a single accountable coordinator.

Knowledge check

References

• Anthropic, Building effective agents
• Anthropic, Subagents in the SDK
• Anthropic, Create custom subagents
• Anthropic, How we built our multi-agent research system
• Anthropic, Claude Certified Architect – Foundations Exam Guide