# Agent Orchestration & MCP Integration Walkthrough

> Exam-style deep dive on Domains 1–2 (45% combined weight): agentic loops and stop_reason, AgentDefinition and hub-and-spoke subagents, Task spawning with explicit context passing, SDK hooks, MCP server configuration, tool descriptions, isError handling, and tool_choice — with step-by-step walkthroughs mirroring Customer Support Agent and Multi-Agent Research System scenarios, including common pitfalls like missing coordinator context and unstructured subagent errors.

- Repository: paullarionov/claude-certified-architect
- GitHub: https://github.com/paullarionov/claude-certified-architect
- Human wiki: https://grok-wiki.com/public/wiki/paullarionov-claude-certified-architect-1b20f95d81b9
- Complete Markdown: https://grok-wiki.com/public/wiki/paullarionov-claude-certified-architect-1b20f95d81b9/llms-full.txt

## Source Files

- `guide_en.MD`
- `README.md`
- `practical_test_en.html`
- `practical_test_ru.html`
- `practical_test_ja.html`
- `practical_test_zh.html`
- `practical_test_ko.html`

---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [guide_en.MD](guide_en.MD)
- [README.md](README.md)
- [practical_test_en.html](practical_test_en.html)
- [practical_test_ru.html](practical_test_ru.html)
- [practical_test_ja.html](practical_test_ja.html)
- [practical_test_zh.html](practical_test_zh.html)
- [practical_test_ko.html](practical_test_ko.html)

</details>

# Agent Orchestration & MCP Integration Walkthrough

Domains 1 and 2 together account for **45%** of the Claude Certified Architect — Foundations exam (27% agent architecture and orchestration, 18% tool design and MCP integration). This page is an exam-style deep dive: it walks through the agentic loop, coordinator–subagent patterns, MCP integration, and the decision points that appear repeatedly in the **Customer Support Agent** and **Multi-Agent Research System** scenarios. Every pattern below is grounded in the study guide and practice questions—not in hypothetical APIs.

---

## Why These Topics Matter on the Exam

The certification tests whether you can make sound trade-off decisions in production agent systems. Exam questions rarely ask you to recite definitions; they present a log pattern, a metric regression, or an architectural proposal and ask which fix is *most effective*. Domains 1–2 reward candidates who understand:

1. **When the model drives the loop** (`stop_reason`) vs when **your code must enforce guarantees** (hooks, preconditions).
2. **How context flows** in hub-and-spoke multi-agent systems—and what breaks when it does not.
3. **How tools are selected and scoped** (descriptions, `tool_choice`, least-privilege `allowed_tools`).
4. **How MCP errors are surfaced** so agents can recover intelligently.

Sources: [guide_en.MD:40-48](guide_en.MD), [guide_en.MD:54-61](guide_en.MD)

---

## Domain Map: What You Must Know

| Topic | Domain | Exam weight | Typical scenario |
|---|---|---|---|
| Agentic loop & `stop_reason` | 1 | 27% | Any autonomous agent |
| `AgentDefinition`, hub-and-spoke, `Task` spawning | 1 | 27% | Multi-Agent Research System |
| SDK hooks (PreToolUse, PostToolUse) | 1 | 27% | Customer Support Agent |
| Tool descriptions & `tool_choice` | 2 | 18% | Customer Support, data extraction |
| MCP config, `isError`, resources | 2 | 18% | Customer Support Agent |
| Structured subagent errors | 1 + 2 | 45% | Multi-Agent Research System |

---

## Part 1: The Agentic Loop and `stop_reason`

### How the loop works

An agentic system is not a single API call. It is a **model-driven loop** where Claude decides which tool to call next based on accumulated context:

```text
Send request with tools
    │
    ▼
Receive response → check stop_reason
    │
    ├─ "tool_use"  → execute tool(s), append results, loop
    └─ "end_turn"  → task complete, return to user
```

Sources: [guide_en.MD:310-321](guide_en.MD)

### `stop_reason` values that control flow

| Value | Meaning | Your action |
|---|---|---|
| `"tool_use"` | Model wants to call a tool | Execute tool(s), append `tool_result` to history, send another request |
| `"end_turn"` | Model finished | Stop the loop; show result to user |
| `"max_tokens"` | Response truncated | Increase limit or handle partial output |
| `"stop_sequence"` | Hit a stop sequence | Application-specific handling |

For agentic systems, `"tool_use"` and `"end_turn"` are the control signals. The **only reliable completion signal** is `stop_reason == "end_turn"`.

Sources: [guide_en.MD:156-167](guide_en.MD), [guide_en.MD:325-330](guide_en.MD)

### Anti-patterns the exam penalizes

| Anti-pattern | Why it fails |
|---|---|
| Parsing assistant text for "Task completed" | Model wording is unreliable |
| Using `max_iterations=5` as primary stop condition | Arbitrary limit, not completion |
| Treating any text response as "done" | Model may still need tools |

**Exam takeaway:** Continue the loop on `"tool_use"`; stop on `"end_turn"`. Full conversation history must be sent on every request—the model does not persist state between calls.

Sources: [guide_en.MD:1519-1527](guide_en.MD), [guide_en.MD:154-154](guide_en.MD)

### Worked example: reducing loop count (Customer Support)

**Situation:** The agent averages 4+ API loops per resolution because `get_customer` and `lookup_order` are requested in separate sequential turns.

**Decision point:** Should you add composite tools, speculative execution, or prompt bundling?

**Correct approach:** Instruct Claude in the prompt to **bundle related tool requests into one turn**. Claude can request multiple tools in a single response; prompting for bundling fixes the sequential pattern with minimal architectural change.

**Why not the others:** Speculative execution wastes calls; composite tools add maintenance; increasing `max_tokens` does not change tool-call behavior.

Sources: [practical_test_en.html](practical_test_en.html) (Q53), [guide_en.MD:1519-1521](guide_en.MD)

---

## Part 2: `AgentDefinition` and Hub-and-Spoke Orchestration

### `AgentDefinition` — the agent configuration object

`AgentDefinition` configures each agent's identity, instructions, and tool access:

```python
agent = AgentDefinition(
    name="customer_support",
    description="Handles customer requests for returns and order issues",
    system_prompt="You are a customer support agent...",
    allowed_tools=["get_customer", "lookup_order", "process_refund", "escalate_to_human"],
    # Coordinator also needs:
    # allowed_tools=["Task", "get_customer", ...]
)
```

| Parameter | Purpose |
|---|---|
| `name` / `description` | Agent identification; helps coordinator select subagents |
| `system_prompt` | Behavioral rules and constraints |
| `allowed_tools` | Least-privilege tool scoping |

**Exam rule:** Too many tools per agent (e.g., 18 instead of 4–5) **reduces** tool selection reliability. Scope tools to each agent's role.

Sources: [guide_en.MD:332-350](guide_en.MD), [guide_en.MD:1638-1646](guide_en.MD)

### Hub-and-spoke topology

Multi-agent systems use a **coordinator at the center** with specialized subagents on the spokes:

```mermaid
flowchart TB
    subgraph coordinator_layer [Coordinator Layer]
        C[Coordinator Agent]
    end
    subgraph subagent_layer [Subagent Layer]
        WS[Web Search Subagent]
        DA[Document Analysis Subagent]
        SY[Synthesis Subagent]
    end
    User([User Request]) --> C
    C -->|Task spawn + context| WS
    C -->|Task spawn + context| DA
    WS -->|structured results| C
    DA -->|structured results| C
    C -->|both result sets| SY
    SY -->|integrated report| C
    C --> User
```

**Coordinator responsibilities:**
- Task decomposition and dynamic subagent selection
- Delegation via the `Task` tool
- Result aggregation and validation
- Error handling, retries, and routing
- All inter-agent communication (observability)

**Critical principle:** Subagents have **isolated context**. They do not automatically inherit the coordinator's conversation history. All required context must be **explicitly passed** in the subagent prompt.

Sources: [guide_en.MD:352-375](guide_en.MD), [guide_en.MD:1529-1540](guide_en.MD)

### Pitfall: missing coordinator context

**Wrong mental model:** "The document analysis subagent already knows what the web search found because they're in the same system."

**Reality:** Each `Task` spawn starts with only what you put in its prompt. If you omit prior search results, the subagent works blind.

```text
# Bad — subagent has no context
Task: "Analyze the document"

# Good — full context in the prompt
Task: "Analyze the following document.
Document: [full document text]
Prior search results: [web search results]
Output format requirements: [schema]"
```

Sources: [guide_en.MD:388-398](guide_en.MD), [guide_en.MD:1544-1552](guide_en.MD)

---

## Part 3: `Task` Spawning and Parallel Subagents

### Spawning mechanics

Subagents are spawned through the **`Task` tool**. The coordinator's `allowed_tools` **must include `"Task"`**.

A coordinator can issue **multiple `Task` calls in one response**—subagents then run **in parallel**:

```text
# One coordinator response:
Task 1: "Search for articles about X"
Task 2: "Analyze document Y"
Task 3: "Search for articles about Z"
# All three run concurrently
```

Sources: [guide_en.MD:377-408](guide_en.MD), [guide_en.MD:1544-1553](guide_en.MD)

### Walkthrough: Multi-Agent Research System — conflicting data

**Situation (Practice Q1):** A document analysis agent finds two credible sources with contradictory statistics: government report says 40% growth, industry analysis says 12%.

| Option | Verdict | Why |
|---|---|---|
| A) Pick one number via heuristics | Wrong | Analysis agent should not unilaterally resolve conflicts |
| B) Include both without marking conflict | Wrong | Synthesis agent cannot reconcile what it cannot see |
| C) Stop and escalate immediately to coordinator | Wrong | Blocks core work unnecessarily |
| **D) Complete analysis with both numbers, annotate conflict with attribution, let coordinator reconcile** | **Correct** | Preserves separation of duties; coordinator has broader context |

**Step-by-step reasoning:**
1. Document analysis agent **completes its core job** (extract and attribute data).
2. Output includes **both values**, source names, and an explicit `conflict_detected` flag.
3. Coordinator—not the subagent—decides reconciliation strategy before synthesis.
4. Synthesis agent receives reconciled or annotated inputs.

This mirrors the provenance pattern in Chapter 12: do not arbitrarily choose one value; preserve both with attribution.

Sources: [guide_en.MD:2130-2141](guide_en.MD), [guide_en.MD:1430-1456](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q1)

### Walkthrough: Multi-Agent Research System — next step after subagents return

**Situation (Practice Q2):** Web-search and document-analysis agents have returned results to the coordinator.

**Correct next step:** Coordinator passes **both result sets** to the synthesis agent for unified integration.

**Why not bypass the coordinator:** Direct agent-to-agent communication breaks centralized error handling, observability, and routing control.

Sources: [guide_en.MD:2145-2156](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q2, Q8)

### Pitfall: narrow coordinator decomposition

**Situation (Practice Q4):** Research on "AI impact on creative industries" covers only visual art. Coordinator logs show decomposition into "AI in digital art," "AI in graphic design," "AI in photography."

**Root cause:** Coordinator decomposition was **too narrow**—not subagent execution failure.

**Fix direction:** Coordinator prompts should express **goals and coverage criteria**, not overly specific subtopics that omit entire domains (music, literature, film).

Sources: [guide_en.MD:2030-2041](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q4)

---

## Part 4: SDK Hooks — Deterministic Enforcement

Hooks intercept agent lifecycle events. They provide **deterministic guarantees** where prompts provide only **probabilistic compliance** (>90%, not 100%).

| Hook type | Use case | Example |
|---|---|---|
| `PostToolUse` | Normalize or trim tool results before model sees them | Convert Unix timestamps to ISO 8601; trim 40+ order fields to 5 |
| `PreToolUse` (outgoing interception) | Block policy-violating actions | Block `process_refund` when amount > $500 |

```python
# PostToolUse: normalize date formats from different MCP tools
@hook("PostToolUse")
def normalize_dates(tool_result):
    # Convert Unix timestamp -> ISO 8601
    return normalized_result

# PreToolUse: block refunds above threshold
@hook("PreToolUse")
def enforce_refund_limit(tool_call):
    if tool_call.name == "process_refund" and tool_call.args.amount > 500:
        return redirect_to_escalation(tool_call)
```

| Attribute | Hooks | Prompt instructions |
|---|---|---|
| Guarantee | Deterministic (100%) | Probabilistic |
| Best for | Financial ops, compliance, safety | Preferences, formatting, general guidance |

**Exam rule:** When failure has financial, legal, or safety consequences—use hooks, not prompts.

Sources: [guide_en.MD:411-444](guide_en.MD), [guide_en.MD:1568-1578](guide_en.MD)

### Walkthrough: Customer Support — skipping `get_customer`

**Situation (Exam Q1 / Practice Q51):** In 12% of cases the agent skips `get_customer` and calls `lookup_order` with only a customer name, causing misidentified accounts and incorrect refunds.

| Option | Verdict |
|---|---|
| A) Few-shot examples | Insufficient—probabilistic |
| B) Routing classifier | Overengineering for sequencing |
| C) **Programmatic precondition blocking `lookup_order`/`process_refund` until verified ID** | **Correct** |
| D) Stronger system prompt | Probabilistic |

**Implementation pattern:** PreToolUse hook or precondition that blocks downstream financial tools until `get_customer` returns a verified identifier. This is **programmatic enforcement** of a multi-step workflow.

Sources: [guide_en.MD:1940-1951](guide_en.MD), [guide_en.MD:1556-1566](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q51)

---

## Part 5: Tool Descriptions — The Primary Selection Mechanism

Tool descriptions are how the LLM **chooses** which tool to call. Minimal or overlapping descriptions cause misrouting.

### What a strong description includes

The study guide's `get_customer` example demonstrates the pattern:

```json
{
  "name": "get_customer",
  "description": "Finds a customer by email or ID. Returns the customer profile, including name, email, order history, and account status. Use this tool BEFORE lookup_order to verify the customer's identity. Accepts an email (format: user@domain.com) or a numeric customer_id.",
  "input_schema": { ... }
}
```

Include in every description:
- What the tool does and returns
- Input formats and example values
- Edge cases and constraints
- **When to use this tool vs similar alternatives**

Sources: [guide_en.MD:209-236](guide_en.MD), [guide_en.MD:1609-1620](guide_en.MD)

### Walkthrough: Customer Support — wrong tool for order status

**Situation (Practice Q46):** Agent calls `get_customer` when `lookup_order` is more appropriate for order-status questions.

**First diagnostic step:** Check tool descriptions—ensure they clearly differentiate purpose and usage boundaries.

**Why not first:** Few-shot examples (adds tokens, doesn't fix root cause), reducing tool count (may remove needed tools), preprocessing classifier (overengineering).

Sources: [guide_en.MD:1955-1966](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q46)

### Walkthrough: Multi-Agent Research — tool name collision

**Situation (Practice Q7):** Requests like "analyze the uploaded quarterly report" route to the web-search agent instead of document analysis.

**Fix:** Rename `analyze_content` → `extract_web_results` (or similar) and update descriptions to explicitly state scope (web results only, not uploaded documents).

Sources: [practical_test_en.html](practical_test_en.html) (Q7), [guide_en.MD:1617-1620](guide_en.MD)

### Built-in tools vs MCP tools

Agents may prefer built-in tools (Read, Grep) over functionally similar MCP tools. Strengthen MCP descriptions by highlighting **unique data or capabilities** built-in tools cannot provide.

Sources: [guide_en.MD:236](guide_en.MD)

---

## Part 6: `tool_choice` — Controlling Tool Selection

`tool_choice` controls whether and which tools the model must call:

| Value | Behavior | When to use |
|---|---|---|
| `{"type": "auto"}` | Model may call a tool or answer in text | Default for conversational agents |
| `{"type": "any"}` | Model **must** call some tool | Guaranteed structured output |
| `{"type": "tool", "name": "extract_metadata"}` | Model **must** call a specific tool | Forced first step / execution order |

**Key distinctions for the exam:**
- `"auto"` → model can return plain text instead of calling a tool
- `"any"` → guarantees a tool call (useful when multiple extraction schemas exist)
- Forced selection → guarantees a specific first action (e.g., `extract_metadata` before enrichment)

Sources: [guide_en.MD:238-250](guide_en.MD), [guide_en.MD:1636-1648](guide_en.MD)

### Allocating tools across agents

| Principle | Rationale |
|---|---|
| 4–5 tools per agent | Reliability drops with 15+ tools |
| Role-scoped `allowed_tools` | Prevents synthesis agent from running full web searches |
| Constrained alternatives | `fetch_url` → `load_document` for document-only agents |
| Limited cross-role utilities | e.g., synthesis gets `verify_fact` for simple checks only |

**Walkthrough (Exam Q9):** Synthesis agent needs simple fact checks (85% of cases) but complex verification should route through coordinator. Give synthesis a **limited `verify_fact` tool**; keep full web-search tools on the search subagent.

Sources: [guide_en.MD:2060-2071](guide_en.MD)

---

## Part 7: MCP Integration

### What MCP provides

The Model Context Protocol connects external systems to Claude through three resource types:

| Type | Purpose | Example |
|---|---|---|
| **Tools** | Actions (CRUD, API calls) | `get_customer`, `process_refund` |
| **Resources** | Read-only context | DB schemas, task catalogs, docs |
| **Prompts** | Reusable prompt templates | Common task patterns |

When connected, all MCP server tools are **discovered automatically** and available simultaneously. Tool descriptions drive how the model uses them.

Sources: [guide_en.MD:450-463](guide_en.MD), [guide_en.MD:1650-1656](guide_en.MD)

### MCP server configuration

**Project scope (`.mcp.json`)** — team-shared, version-controlled:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

| Config location | Scope | Secrets |
|---|---|---|
| `.mcp.json` (project root) | Whole team via VCS | `${GITHUB_TOKEN}` env substitution |
| `~/.claude.json` | Personal experiments | Not shared |

**Exam guidance:** Prefer community MCP servers for standard integrations (Jira, GitHub, Slack). Build custom servers only for unique workflows.

Sources: [guide_en.MD:465-502](guide_en.MD), [guide_en.MD:1650-1661](guide_en.MD)

### MCP resources reduce exploratory calls

Resources act as a "content catalog"—the agent sees what data exists without trial-and-error tool calls. Example: a task-summary resource listing all project issues hierarchically.

Sources: [guide_en.MD:534-543](guide_en.MD)

---

## Part 8: `isError` and Structured Error Responses

When an MCP tool fails, it sets **`isError: true`** in the response. This tells the agent the call failed—not that it succeeded with empty data.

### Structured error (good)

```json
{
  "isError": true,
  "content": {
    "errorCategory": "transient",
    "isRetryable": true,
    "message": "The service is temporarily unavailable. Timeout while calling the orders API.",
    "attempted_query": "order_id=12345",
    "partial_results": null
  }
}
```

### Generic error (anti-pattern)

```json
{
  "isError": true,
  "content": "Operation failed"
}
```

A generic message gives the coordinator no basis to decide: retry? modify query? escalate? continue with partial results?

Sources: [guide_en.MD:504-532](guide_en.MD), [guide_en.MD:1622-1634](guide_en.MD)

### Error categories

| Category | Examples | Retryable | Agent action |
|---|---|---|---|
| **Transient** | Timeout, 503, network | Yes | Retry with backoff |
| **Validation** | Bad input format | No (fix input) | Modify and retry |
| **Business** | Policy violation | No | Explain; propose alternative |
| **Permission** | Access denied | No | Escalate |

Sources: [guide_en.MD:1232-1239](guide_en.MD)

### Pitfall: unstructured subagent errors

**Anti-patterns the exam tests:**

| Anti-pattern | Problem |
|---|---|
| Generic "search unavailable" status | Coordinator cannot recover intelligently |
| Empty result marked as success | Masks failure as "no matches" |
| Abort entire workflow on one failure | Loses all partial results |
| Infinite retries inside subagent | Wastes latency; coordinator should decide |

**Correct pattern — structured subagent error:**

```json
{
  "status": "partial_failure",
  "failure_type": "timeout",
  "attempted_query": "AI impact on music industry 2024",
  "partial_results": [
    {"title": "AI Music Generation Report", "url": "...", "relevance": 0.8}
  ],
  "alternative_approaches": [
    "Try a narrower query: 'AI music composition tools'",
    "Use an alternative data source"
  ],
  "coverage_impact": "Not covered: AI impact on music production"
}
```

The coordinator can then: retry with modified query, use partial results, delegate to another subagent, or continue with **coverage annotations** in the final synthesis.

Sources: [guide_en.MD:1241-1288](guide_en.MD), [guide_en.MD:2045-2056](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q5, Q6, Q8)

### Local recovery vs coordinator escalation

**Situation (Practice Q3):** PDF parsing fails on corrupted sections, password-protected files, and large-file hangs. Every exception currently terminates the subagent and burdens the coordinator.

**Best fix:** Implement **local recovery in the subagent** for transient failures; escalate to coordinator only for errors the subagent cannot resolve, including attempted steps and partial results.

**Principle:** Handle errors at the **lowest level capable of resolving them**.

Sources: [guide_en.MD:2160-2171](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q3)

---

## Part 9: End-to-End Scenario Walkthroughs

### Scenario A: Customer Support Agent (single-agent + MCP tools)

**Architecture:** One `AgentDefinition` with MCP tools: `get_customer`, `lookup_order`, `process_refund`, `escalate_to_human`. Target: 80%+ first-contact resolution.

```mermaid
sequenceDiagram
    participant User
    participant Loop as Agentic Loop
    participant Claude
    participant MCP as MCP Tools
    participant Hook as PreToolUse Hook

    User->>Loop: "Refund for order #1234"
    Loop->>Claude: messages + tools
    Claude-->>Loop: stop_reason=tool_use, get_customer
    Loop->>MCP: get_customer(email)
    MCP-->>Loop: customer profile
    Loop->>Claude: append tool_result
    Claude-->>Loop: stop_reason=tool_use, lookup_order
    Loop->>MCP: lookup_order(order_id)
    MCP-->>Loop: order details
    Loop->>Claude: append tool_result
    Claude-->>Loop: stop_reason=tool_use, process_refund
    Loop->>Hook: intercept process_refund
    alt amount > $500
        Hook-->>Loop: redirect to escalate_to_human
    else within policy
        Hook-->>Loop: allow
        Loop->>MCP: process_refund
    end
    Claude-->>Loop: stop_reason=end_turn
    Loop->>User: resolution
```

**Decision checklist for this scenario:**

| Problem observed | First check | Enforcement level |
|---|---|---|
| Wrong tool selected | Tool descriptions | Prompt + description fix |
| Skips `get_customer` | Precondition hook | Programmatic (hooks) |
| Escalates too much / too little | Escalation criteria + few-shot | Prompt |
| Refund above threshold | PreToolUse hook | Programmatic (hooks) |
| Too many API loops | Prompt to bundle tool calls | Prompt |
| Policy gap (competitor price match) | `escalate_to_human` | Business rule → escalate |

Sources: [guide_en.MD:54-55](guide_en.MD), [guide_en.MD:1129-1209](guide_en.MD), [practical_test_en.html](practical_test_en.html) (Q46–Q53)

### Scenario B: Multi-Agent Research System (coordinator + subagents)

**Architecture:** Coordinator with `Task` in `allowed_tools`; subagents for web search, document analysis, synthesis, report generation.

**Happy-path flow:**
1. Coordinator decomposes topic with **broad coverage criteria** (not overly narrow subtopics).
2. Coordinator spawns parallel `Task` calls with **explicit context** in each prompt.
3. Subagents return **structured results** (not raw dumps).
4. Coordinator forwards combined results to synthesis agent.
5. Synthesis produces report with **coverage annotations** where inputs were partial.

**Error-path flow:**
1. Subagent encounters transient failure → local retry (1–2 attempts).
2. Unrecoverable failure → structured error with `partial_results`, `alternative_approaches`, `coverage_impact`.
3. Coordinator decides: retry, alternate source, or proceed with annotated gaps.
4. Final report marks sections `FULL COVERAGE` vs `PARTIAL COVERAGE`.

Sources: [guide_en.MD:60-61](guide_en.MD), [guide_en.MD:1274-1288](guide_en.MD), [guide_en.MD:2126-2203](guide_en.MD)

---

## Part 10: Common Pitfalls Summary

| Pitfall | Symptom | Correct approach |
|---|---|---|
| Missing coordinator context | Subagent produces irrelevant output | Pass full prior results in `Task` prompt |
| Unstructured subagent errors | Coordinator cannot decide recovery | Return `failure_type`, query, partial results, alternatives |
| Narrow decomposition | All subagents succeed but report has gaps | Coordinator goals + coverage criteria, not narrow subtopics |
| Bypassing coordinator | Proposed direct agent-to-agent routing | Reject—breaks observability and error control |
| Prompt-only enforcement for money | 12% skip verification rate | PreToolUse precondition hooks |
| Generic MCP errors | Agent retries blindly or gives up | `isError` + `errorCategory` + `isRetryable` metadata |
| Silent failure as empty success | "No results" when search actually failed | Distinguish zero results from tool failure |
| Parsing text for completion | Premature or infinite loops | Trust `stop_reason` only |

Sources: [guide_en.MD:1241-1248](guide_en.MD), [guide_en.MD:1371-1380](guide_en.MD)

---

## Exam Decision Framework

When facing a Domain 1–2 question, apply this sequence:

```text
1. Is this about LOOP CONTROL?
   → stop_reason: tool_use = continue, end_turn = stop

2. Is this about MULTI-AGENT FLOW?
   → Hub-and-spoke: all traffic through coordinator
   → Explicit context in Task prompts
   → Structured errors back to coordinator

3. Is this about RELIABILITY / COMPLIANCE?
   → Financial/legal/safety → hooks (deterministic)
   → Preferences/formatting → prompts (probabilistic)

4. Is this about TOOL SELECTION?
   → Descriptions first
   → Scope allowed_tools per role
   → tool_choice: any for forced structure, forced name for order

5. Is this about MCP ERRORS?
   → isError: true + structured metadata
   → Local recovery in subagent, escalate what you cannot fix
```

---

## Practice Resources

The repository includes interactive practical tests covering both scenarios in multiple languages. Work through the **Multi-agent Research System** and **Customer Support Agent** question sets in [practical_test_en.html](practical_test_en.html) after reading Domains 1–2 in [guide_en.MD](guide_en.MD). The README points to Anthropic's free MCP and Agent SDK courses for hands-on depth.

Sources: [README.md:43-47](README.md), [README.md:57-59](README.md)

---

## Summary

Agent orchestration and MCP integration are the exam's largest combined weight (45%) because they test production judgment, not API memorization. Master the agentic loop controlled by `stop_reason`, configure agents with scoped `AgentDefinition` objects, and orchestrate multi-agent work through a hub-and-spoke coordinator that spawns subagents via `Task` with explicit context. Use SDK hooks when business rules demand certainty; use tool descriptions and `tool_choice` when you need correct selection and structured output. Configure MCP servers in `.mcp.json` with env-var secrets, and return structured `isError` responses so coordinators—not guesswork—drive recovery. The Customer Support scenario teaches enforcement and tool scoping; the Multi-Agent Research scenario teaches context passing, decomposition breadth, and structured error propagation. Avoid the traps: missing context in `Task` prompts, generic errors, bypassing the coordinator, and prompt-only guarantees for financial operations.