Claude Architect · Lesson

Coordinator Responsibilities

Decompose, delegate, aggregate, route and handle errors.

Coordinator Responsibilities is a free Claude Architect lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Coordinator's Job

In a multi-agent system, Claude orchestration follows a hub-and-spoke shape: one coordinator at the hub, several subagents on the spokes. The coordinator never does the deep work itself — it manages the work.

A coordinator has exactly five responsibilities you must master for the exam:

Decompose — split a task into subtasks
Delegate — hand each subtask to a subagent
Aggregate — merge subagent results
Route — send work to the right specialist
Handle errors — recover or escalate failures

This lesson walks through each, with the patterns and anti-patterns that separate a passing answer from a plausible distractor.

Subagents Start With a Blank Slate

The single most tested coordinator fact: subagents do NOT inherit the coordinator's conversation history. Each subagent is a fresh Claude context.

The model keeps no state between turns or across agents. Whatever a subagent needs to do its job — the user's goal, prior findings, constraints, IDs — must be passed explicitly inside that subagent's prompt.

Forgetting this is a classic failure: the coordinator 'knows' the customer ID or the research question, assumes the subagent does too, and the subagent fabricates or stalls. Context isolation is a feature (it keeps focus tight), but it puts the burden of context-passing squarely on the coordinator.

Passing Context Explicitly

Because nothing is inherited, the coordinator builds each subagent prompt as a self-contained briefing. Notice how the goal, the constraints, and the specific slice of work are all spelled out — the subagent could run on a machine that never saw the conversation.

This is also why an AgentDefinition carries a system_prompt and least-privilege allowed_tools: each subagent is scoped to its role and given only what it needs.

from claude_agent_sdk import AgentDefinition

researcher = AgentDefinition(
    name="researcher",
    description="Researches one sub-question and returns cited findings.",
    system_prompt=(
        "You research a SINGLE sub-question. "
        "You have no prior context except this prompt. "
        "Return findings with claim->source (URL, quote, date)."
    ),
    allowed_tools=["WebSearch", "WebFetch"],  # least privilege
)

# The coordinator injects ALL needed context per call:
subagent_prompt = (
    f"Overall goal: {user_goal}\n"
    f"Your sub-question: {sub_question}\n"
    f"Constraints: only sources newer than 2023."
)

Decompose: Fixed vs Adaptive

Decomposition is choosing how to break the work apart. Two strategies, and the exam wants you to match strategy to situation:

Fixed pipeline / prompt chaining — for a known, sequential set of steps (e.g. extract -> validate -> format). The structure is decided in advance.
Adaptive decomposition — for open-ended investigations where you can't know the subtasks until you start (e.g. a research question that branches as you learn).

A second decomposition pattern worth knowing: multi-pass code review. Do a per-file local pass first, then a separate cross-file integration pass. A single-pass multi-file review dilutes the model's attention and misses both local bugs and integration issues.

Delegate: One Response, Parallel Work

The coordinator delegates by issuing Task calls. The key performance fact: multiple Task calls in a single response run in parallel.

For independent subtasks — three research questions, three files to scan — emit all the Task calls together rather than one per turn. You get concurrency for free.

Two prerequisites the exam tests: the coordinator's allowedTools must include "Task", and each subagent must receive its full context explicitly (Scene 2).

# Coordinator delegating THREE independent sub-questions at once.
# Emitting them in a single response runs them in parallel.

tasks = [
    {"subagent": "researcher", "prompt": brief(goal, q)}
    for q in [
        "What are the market size figures?",
        "Who are the top 3 competitors?",
        "What regulatory constraints apply?",
    ]
]

# allowedTools on the coordinator MUST include "Task"
coordinator_allowed_tools = ["Task", "Read", "Write"]

# Each prompt is fully self-contained — no inherited history.

Route: Descriptions Pick the Specialist

Routing means sending each subtask to the right subagent. Claude chooses based primarily on the agent and tool descriptions — not the names.

A good description states purpose, what it returns, input formats with examples, and applicability boundaries. Overlapping or ambiguous descriptions cause misrouting: if two subagents sound like they both handle 'data', the coordinator may pick wrong.

Scope each subagent narrowly. Keep 4-5 tools per agent as the sweet spot; 18+ tools degrades selection reliability. Least-privilege tooling isn't only about security — it sharpens routing.

billing_agent = AgentDefinition(
    name="billing",
    # Sharp, non-overlapping description -> correct routing
    description=(
        "Handles refunds and invoice questions ONLY. "
        "Input: order_id (str) + verified customer_id. "
        "Returns: refund status or invoice PDF link. "
        "Does NOT handle shipping or account changes."
    ),
    system_prompt="...",
    allowed_tools=["lookup_order", "process_refund"],  # 2 tools, scoped
)

Aggregate: Merge With Provenance

Once subagents return, the coordinator aggregates their outputs into one coherent answer. This is more than concatenation.

Keep provenance: every claim maps to its source (URL, doc name, quote, publication date).
Annotate conflicts rather than silently picking one number — and remember dates often resolve apparent contradictions.
Render by content type: tables for financials, prose for news, lists for technical findings.

Aggregation is also where you preserve partial results: if one subagent failed, the coordinator still merges what succeeded and clearly marks the gap.

Handle Errors: Recover Locally, Escalate Up

The fifth responsibility is the one that breaks fragile systems. The rule:

Recover transient faults locally inside the subagent (e.g. a timeout — retry there).
Escalate non-recoverable failures upward with partial results, so the coordinator can route around them.

Two anti-patterns to avoid: silently suppressing an error (the coordinator never learns), and aborting the whole workflow because one subagent failed. One failed spoke should not collapse the hub.

Crucially, distinguish an access FAILURE (maybe retryable) from a valid EMPTY result (no matches — not an error at all).

Structured Errors Enable Routing

The coordinator can only route around a failure if the failure tells it enough. A generic "Operation failed" blocks recovery. A structured error enables intelligent routing.

Structured error context includes the failure type / category, whether it is retryable, the attempted query, any partial results, and alternatives. With that, the coordinator decides: retry, try another tool, merge partials, or escalate.

# A subagent returning a STRUCTURED error the coordinator can act on:
error_result = {
    "isError": True,
    "errorCategory": "transient",   # transient | validation | business | permission
    "isRetryable": True,
    "message": "Search API timed out after 30s",
    "attempted_query": "market size fintech 2024",
    "partial_results": [{"source": "...", "claim": "..."}],
}

# Coordinator logic:
if error_result["isError"] and error_result["isRetryable"]:
    retry(error_result["attempted_query"])
else:
    escalate_with(error_result["partial_results"])

The Loop Stops on stop_reason

The coordinator runs an agentic loop: send the request, inspect stop_reason, and if it is tool_use, run the tools (including Task delegations), append results to history, and repeat until end_turn.

Terminate on the stop_reason — never by parsing the model's text for words like 'done' or 'finished'. Decisions about when work is complete are model-driven. An iteration cap is a safety net, not the primary stop mechanism.

Reserve hard-coded control for guarantees you must enforce; let the model decide the flow otherwise.

while True:
    resp = client.messages.create(
        model="claude-opus-4-1",
        max_tokens=2048,
        messages=history,   # FULL history every turn — model keeps no state
        tools=tools,
    )
    if resp.stop_reason == "tool_use":
        results = run_tools(resp)           # may include parallel Task calls
        history.append(assistant(resp))
        history.append(tool_results(results))
        continue
    if resp.stop_reason == "end_turn":
        break                               # stop on stop_reason, not on text
    # iteration cap = safety net only, checked separately

When the Coordinator Must Escalate

Some failures aren't the coordinator's to solve — they belong to a human. Good escalation triggers:

An explicit human request — escalate immediately.
Policy gaps the agent has no rule for.
No progress after reasonable attempts.
Threshold violations (e.g. a refund above a limit).

Bad triggers the exam will offer as distractors: sentiment analysis, the model's own self-rated confidence (1-10), or untrained classifiers. And when a business rule has financial, legal, or safety consequences, enforce it with a deterministic hook, not prompt guidance — hooks are 100% deterministic, prompts only ~90% probabilistic.

Quick Check: Delegating a Subtask

A research coordinator delegates a sub-question to a researcher subagent. The coordinator already discussed the user's goal and gathered earlier findings in its own conversation. What MUST the coordinator do for the subagent to succeed?

Recap: The Coordinator in Five Moves

You can now reason about a coordinator like an architect:

Decompose — fixed pipelines for known sequences, adaptive for open-ended work; multi-pass (local then cross-file) for code review.
Delegate — emit multiple Task calls in one response to run in parallel; include 'Task' in allowedTools.
Route — sharp, non-overlapping descriptions pick the right specialist; 4-5 tools per agent.
Aggregate — merge with provenance, annotate conflicts, preserve partial results.
Handle errors — recover transient faults locally; escalate non-recoverable failures with structured context and partial results; never silently suppress or abort the whole workflow.

Above all: subagents inherit no history — pass context explicitly, and stop on stop_reason, never on parsed text. Enforce financial/legal/safety rules with deterministic hooks. Master these and the orchestration scenarios are yours.

Frequently asked questions

Is the “Coordinator Responsibilities” lesson free?

Yes — the full text of “Coordinator Responsibilities” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “Coordinator Responsibilities”?

Decompose, delegate, aggregate, route and handle errors. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Coordinator Responsibilities” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Claude Architect