Claude Subagents Tutorial: Architect Patterns That Scale

This claude subagents tutorial is written for engineers preparing for the Claude Certified Architect, Foundations (CCAR-F) exam and for practitioners who need production-grade patterns today. Domain 1 (Agentic Architecture and Orchestration) carries 27% of the exam weight, making subagent design the single heaviest topic on the paper. We cover the mechanics, the failure modes, and the enforcement decisions that separate a passing answer from a correct production system.

What exactly is a subagent in Claude's architecture?

A subagent is a Claude model instance that receives a scoped task from a coordinator, executes it with a limited set of tools, and returns a structured result. The coordinator never does the work itself; it decomposes, delegates, and synthesises. Subagents do not share a conversation thread with the coordinator or with each other, which is the property that makes the pattern both powerful and tricky.

Per Anthropic's documentation, each subagent call is a fresh Messages API request. The coordinator constructs the full context for that request, sends it, reads the response, and decides what to do next. Nothing persists between calls except what the coordinator explicitly passes.

This isolation is a feature, not a limitation. It means a subagent that hallucinates or errors cannot corrupt the coordinator's reasoning unless the coordinator blindly trusts its output. The subagent context isolation concept is one of the most-tested ideas in Domain 1.

How does the hub-and-spoke architecture organise subagents?

The hub-and-spoke pattern places one coordinator (the hub) at the centre and N subagents (the spokes) around it. The coordinator holds the goal, the decomposition logic, and the synthesis responsibility. Each subagent holds only the tools and context it needs for its specific task.

User request
     |
     v
 Coordinator (hub)
  /     |      \
SA-1   SA-2   SA-3
(web)  (code)  (db)

The hub-and-spoke architecture concept maps directly to exam task statement 1.3. The exam tests whether you can identify when a coordinator is doing too much (narrow decomposition failure) versus when it is delegating correctly.

Key coordinator responsibilities include:

1. Decompose the user goal into independent or sequenced sub-tasks.
2. Select the right subagent for each sub-task (static assignment or dynamic selection).
3. Pass only the context each subagent needs, nothing more.
4. Validate subagent outputs before using them downstream.
5. Synthesise results into a coherent final response.
6. Handle errors without cascading failure.

The coordinator responsibilities concept lists these in detail with exam-relevant nuance.

How do you pass context to subagents without leaking irrelevant information?

Structured context passing is the mechanism. Instead of forwarding the entire conversation history, the coordinator builds a minimal, typed payload for each subagent call.

{
  "task": "summarise_document",
  "document_id": "doc-8821",
  "target_length_words": 150,
  "output_schema": {
    "summary": "string",
    "key_claims": ["string"]
  }
}

Passing the full conversation history to every subagent causes two problems. First, it wastes tokens and inflates cost. Second, it introduces the attention dilution problem: the model's attention spreads across irrelevant turns and the subagent performs worse on its actual task.

The rule of thumb: pass the minimum context required for the subagent to complete its task and return a verifiable result. If the subagent needs background, inject a structured summary, not raw history.

When should subagents run in parallel versus in sequence?

The answer depends on data dependencies, not on performance preference alone.

Parallel subagent spawning is the correct choice when tasks are genuinely independent. The exam frequently presents scenarios where a candidate must identify whether a dependency exists before recommending parallelism.

import anthropic
import asyncio

client = anthropic.Anthropic()

async def run_subagent(task_payload: dict) -> dict:
    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        system="You are a focused subagent. Complete only the task in the user message.",
        messages=[{"role": "user", "content": str(task_payload)}]
    )
    return {"task_id": task_payload["task_id"], "result": response.content[0].text}

async def run_parallel_subagents(tasks: list[dict]) -> list[dict]:
    return await asyncio.gather(*[run_subagent(t) for t in tasks])

Note that the coordinator collects all results before synthesising. It does not stream partial results into a final answer mid-flight, because that would make error handling nearly impossible.

How does the coordinator select which subagent to call dynamically?

Static assignment works when the task decomposition is known at design time. Dynamic selection is needed when the coordinator must route based on the content or complexity of the incoming request.

Coordinator dynamic subagent selection covers the two main approaches:

• Model-driven routing: the coordinator asks Claude to classify the request and select from a named set of subagents. Flexible, but introduces a probabilistic step.
• Pre-configured routing: the coordinator uses deterministic rules (regex, schema validation, keyword matching) to assign tasks. Less flexible, but auditable and reliable.

For high-stakes routing decisions, the exam expects you to prefer deterministic rules. For exploratory or open-ended tasks where the space of sub-tasks cannot be enumerated in advance, model-driven routing is acceptable. The model-driven vs pre-configured decision-making concept walks through the trade-offs with scenario examples.

How do you handle errors when a subagent fails?

Error handling is one of the most-tested areas in Domain 1. The exam presents scenarios where a subagent returns an error, a partial result, or a malformed output, and asks what the coordinator should do.

The multi-agent error handling and routing concept defines four response strategies:

1. Retry with error feedback: pass the error back to the same subagent with a corrective prompt. Appropriate for transient or recoverable failures.
2. Route to a fallback subagent: if the primary subagent is unavailable or consistently failing, delegate to an alternative.
3. Escalate to a human: for irreversible actions or when the error exceeds the system's recovery capability.
4. Abort and surface: terminate the workflow and return a structured error to the caller. Appropriate when continuing would produce unreliable results.

{
  "status": "error",
  "error_code": "TOOL_UNAVAILABLE",
  "subagent_id": "db-reader-01",
  "task_id": "fetch-user-profile",
  "retry_eligible": true,
  "message": "Database connection timed out after 5000ms"
}

The coordinator should never silently suppress an error and proceed as if the sub-task succeeded. Silent suppression is an anti-pattern that produces confident-sounding but factually incomplete final responses.

What is narrow decomposition failure and how do you avoid it?

Narrow decomposition failure occurs when the coordinator assigns a sub-task so narrowly that the subagent lacks the context to complete it correctly, or so broadly that the subagent must make decisions that belong to the coordinator.

A common exam scenario: a coordinator delegates "write the database migration" to a subagent without telling it the target schema, the existing table structure, or the rollback requirement. The subagent produces a migration that is syntactically valid but semantically wrong. The failure is in the decomposition, not in the subagent.

The fix is structured context passing combined with explicit output contracts. Every subagent call should specify:

• What the subagent must produce (schema or format)
• What constraints apply (length, tone, safety rules)
• What the subagent must NOT do (scope boundary)
• How the coordinator will validate the result

How do goal-based prompts differ from step-based prompts for subagents?

Goal-based vs step-based prompts is a Domain 1 and Domain 4 crossover concept. The distinction matters for subagents because over-specifying steps removes the model's ability to adapt, while under-specifying goals produces unpredictable outputs.

For exam purposes: use goal-based prompts when the subagent has the tools and context to self-direct, and step-based prompts when the execution path must be auditable or when a specific tool sequence is required for safety.

How do you manage context across a long-running multi-subagent workflow?

Long-running workflows accumulate context debt. Each round trip adds tokens, and after enough iterations the coordinator's context window fills with stale intermediate results that dilute attention on the current task.

The stale context problem and summary injection for fresh sessions concepts address this directly. The pattern:

1. After each major phase, the coordinator generates a structured summary of what has been established.
2. When starting a new phase, the coordinator injects the summary rather than the full history.
3. Subagents receive only the summary plus their specific task payload.

def build_phase_summary(completed_tasks: list[dict]) -> str:
    facts = [f"- {t['task_id']}: {t['result_summary']}" for t in completed_tasks]
    return "Established facts from prior phases:\n" + "\n".join(facts)

This keeps each subagent call lean and prevents the attention dilution problem from degrading output quality as the workflow grows.

What does the CCAR-F exam actually test about subagents?

Domain 1 (Agentic Architecture and Orchestration) carries 27% of the 60-item exam, making it the largest single domain. The exam draws 4 scenarios at random from a bank of 6 at each sitting, so you cannot predict which specific scenario will appear. Every item is scenario-based and tests practical judgement, not recall.

The exam consistently rewards answers that prefer deterministic, auditable, and minimal-blast-radius solutions. When two options both work technically, choose the one that is easier to debug, easier to roll back, and less likely to produce silent failures.

Our concept library at /concepts maps all 174 atomic concepts to the five CCAR-F domains and 30 task statements. The Domain 1 cluster covers every subagent pattern listed in this post, with worked examples and exam-style scenario questions for each.

How should you structure a subagent system for a production deployment?

Production subagent systems differ from prototypes in three ways: they enforce scope programmatically, they log every subagent call with a correlation ID, and they define explicit termination conditions before the workflow starts.

import uuid

def invoke_subagent(
    coordinator_id: str,
    task: dict,
    tools: list[dict],
    max_retries: int = 2
) -> dict:
    call_id = str(uuid.uuid4())
    for attempt in range(max_retries + 1):
        response = client.messages.create(
            model="claude-opus-4-5",
            max_tokens=2048,
            system=task["system_prompt"],
            tools=tools,
            messages=[{"role": "user", "content": task["payload"]}],
            metadata={"user_id": coordinator_id}
        )
        if response.stop_reason != "end_turn" and attempt < max_retries:
            # log and retry
            continue
        return {
            "call_id": call_id,
            "coordinator_id": coordinator_id,
            "task_id": task["task_id"],
            "stop_reason": response.stop_reason,
            "content": response.content
        }
    return {"call_id": call_id, "status": "failed", "task_id": task["task_id"]}

Key production requirements:

1. Every subagent call carries a correlation ID linking it to the parent coordinator call.
2. Tools are scoped per subagent: a web-search subagent does not receive database write tools.
3. The coordinator validates output schema before passing results downstream.
4. Termination conditions are defined upfront: maximum iterations, timeout, and error budget.
5. Irreversible actions (writes, sends, deploys) require a confirmation step or a human-in-the-loop gate.

The prerequisite gate design concept covers how to enforce ordering and approval requirements without hard-coding them into every subagent prompt.

For teams preparing for the CCAR-F exam, our adaptive practice engine on AI Skill Certs (independent of Anthropic) surfaces the specific Domain 1 task statements where your Bayesian knowledge trace falls below the 0.90 mastery threshold, so revision time goes where it is actually needed.