Agentic Architecture & Orchestration (27%)

What the exam tests: whether you can build a correct agentic loop, run a coordinator with subagents, pass context between them explicitly, and enforce must-never-fail business rules in code rather than in the prompt. This is the largest domain, about 16 of 60 items, and it appears in four of the six scenarios.

2.1 The agentic loop (Task 1.1)

An agent is a loop around the Messages API. You send the conversation and tool definitions; Claude replies; you read stop_reason. If it is "tool_use", you run each requested tool, append the results as tool_result blocks in a new user message, and call again. If it is "end_turn", Claude has finished and you return its answer.

Figure 2. The agentic loop: stop on stop_reason, never on heuristics messages = [{"role": "user", "content": task}]

results = [run_tool(b) for b in resp.content if b.type == "tool_use"] messages.append({"role": "user", "content": results})

Three points the exam checks:

Tool results go back into the history. Claude reasons about the next step only from what is in messages. Dropping results, or summarising them away too early, breaks the next decision. The model decides what to call next. That is what makes it an agent rather than a hardcoded decision tree. Use a fixed sequence only when the order is genuinely fixed. Stop on stop_reason, not on heuristics. The guide names three anti-patterns: parsing the text for phrases like "I'm done", using an iteration cap as the main stopping rule, and treating "the reply contains text" as completion. A safety cap is fine as a backstop; it must not be the design.

2.2 Coordinator and subagents (Task 1.2)

The exam's model for multi-agent systems is hub and spoke. One coordinator decomposes the task, decides which subagents to invoke, sends each its brief, receives results, handles their errors and aggregates the output. Subagents do not talk to each other; everything routes through the coordinator for observability, consistent error handling and controlled information flow.

Figure 3. Hub and spoke: every brief and every result routes through the coordinator

Each subagent receives a self-contained brief and returns results or a structured error to the coordinator, never to a sibling. Good coordinators:

Pick subagents per query. A simple question should not run the full search, analyse, synthesise, report pipeline.

Subagents never talk to each other.

Partition scope to avoid duplication, for example by subtopic or source type. Decompose broadly enough. The guide's sample case splits "AI in creative industries" into digital art, graphic design and photography, and the report misses music, writing and film. Every subagent did its job; the coordinator's decomposition was the root cause. Iterate. After synthesis, the coordinator checks for gaps, sends targeted follow-up queries to search and analysis, and re-runs synthesis until coverage is sufficient.

2.3 Spawning subagents and passing context (Task 1.3)

In the Claude Agent SDK, a coordinator spawns subagents through the Task tool, so the coordinator's allowedTools must include "Task". Each subagent type is an AgentDefinition with a description (used to decide when to delegate), its own system prompt and a restricted tool list. The single most tested fact: subagents start with a clean context. They do not inherit the coordinator's conversation and they do not share memory between invocations. Anything a subagent needs must be in the prompt the coordinator writes for it. Pass prior agents' complete findings into the next agent's prompt, for example search results and document analysis into the synthesis agent.

Use structured formats that separate content from metadata (URL, document name, page) so attribution survives the hand-off.

For parallelism, emit several Task calls in one coordinator response. Calls spread across separate turns run one after another.

Brief subagents with goals and quality criteria, not step-by-step procedures, so they can adapt to what they find.

2.4 Enforcement and hand-off (Task 1.4)

Prompt instructions are probabilistic. Even a very clear instruction has a non-zero failure rate, which is unacceptable when the step guards money or identity. The exam's answer is programmatic enforcement: a gate in code that blocks process_refund (and lookup_order) until get_customer has returned a verified customer ID. Better wording and more few-shot examples improve the odds; a gate makes it certain.

Two related patterns:

Multi-concern requests. Split "my order arrived late, I was double-charged and I want to change my address" into separate items, investigate them (in parallel where possible) with shared context, then give one unified answer.

Structured escalation hand-off. A human agent does not see the transcript, so the hand-off must carry customer ID, root cause, amounts, what was tried and the recommended action.

2.5 Hooks (Task 1.5)

Hooks are code the SDK runs at fixed points in the loop. Two uses dominate the exam: Hook point Use Example

• Before a tool runs
• (PreToolUse)
• Block or redirect a call
• that breaks a rule

Deny process_refund above US$500 and route to escalate_to_human

• After a tool returns
• (PostToolUse)
• Transform the result be‐
• fore Claude sees it
• Normalise Unix timestamps, ISO 8601 strings and numeric status
• codes from different MCP servers into one format

Rule of thumb: if the requirement says always, never or guaranteed, use a hook. If it is a preference or a style, use the prompt.

2.6 Task decomposition (Task 1.6)

• Pattern Use when Example
• Prompt chaining
• (fixed pipeline)
• The steps are known in
• advance

Review each file on its own, then run one cross-file integration pass Dynamic decom‐

• position
• What to do next depends
• on what you find

"Add tests to this legacy codebase": map the structure, find high-impact areas, plan, and re-plan as dependencies appear

Splitting a 14-file review into per-file passes plus an integration pass fixes attention dilution, where one big pass gives uneven depth and contradictory findings.

2.7 Sessions: resume, fork or start fresh (Task 1.7)

Figure 4. Resume, fork or start fresh

--resume <session-name> continues a named earlier session. Use it when the earlier context is still mostly valid, and tell the agent which files changed so it re-reads only those. Continue earlier

work?

fork_session branches an independent copy from a shared baseline, for example to compare two refactoring approaches from one codebase analysis. Start fresh with a structured summary when the old tool results are stale. Resuming on outdated file contents is less reliable than a clean session seeded with what still holds.

Worked examples

Each example below follows the same shape as an exam item: a production symptom, the evidence, the tempting wrong answers and the fix the domain's principles point to. Work through the diagnosis yourself before reading the answer.

Worked example 2.A: The loop that quits early

Situation. A developer-productivity agent sometimes stops halfway through a task. Asked to "rename getUser to fetchUser everywhere", it edits two files and returns "I'll now update the remaining callers." Nothing more happens. Evidence. The loop code reads:

• while True:
• resp = client.messages.create(...)
• messages.append({"role": "assistant", "content": resp.content})
• text = [b for b in resp.content if b.type == "text"]
• if text:
• return text[0].text # treat any prose as the final answer
• run_tools_and_append(resp, messages)

Diagnosis. Claude often writes a sentence of narration in the same response as a tool call. This loop treats that sentence as completion and returns before running the tool. It is the third antipattern the guide lists: "checking for assistant text content as a completion indicator". Tempting wrong answers.

Tell Claude in the system prompt not to write text until it is finished. That fights the model's normal behaviour and still fails some of the time. Add a minimum iteration count. Arbitrary counts are the second anti-pattern.

Search the text for "done" or "complete". That is the first anti-pattern.

Fix. Branch on stop_reason. Continue while it is tool_use; finish on end_turn. Handle max_tokens separately, for example by raising the limit or asking Claude to continue, and keep a generous safety cap that logs an alert rather than acting as the stopping rule. Takeaway. The only reliable signal that Claude is finished is stop_reason == "end_turn". Worked example 2.B: Parallel research that runs in series

Situation. The research coordinator handles "compare EU, US and UK rules on AI in hiring". It takes 9 minutes. Each regional search takes about 3.

Evidence. The coordinator's transcript shows three turns. In each, it emits one Task call, waits for the result, then emits the next.

Diagnosis. Subagents run concurrently only when the coordinator emits several Task calls in one response. The coordinator prompt says "research each region, then compare", which reads as a sequence.

Fix. Rewrite the coordinator's instructions to plan first and dispatch independent work together: "Identify which sub-questions are independent. Launch all independent searches in a single response, then wait for all results before synthesis." Wall-clock time falls to roughly the slowest single search plus synthesis.

Watch for. The fix is in the coordinator's behaviour, not in the infrastructure. Options such as "move to the Batches API" (no, that is for latency-tolerant work) or "give one subagent all three regions" (loses parallelism and focus) are distractors.

Worked example 2.C: The forgetful synthesis agent

Situation. The final report cites "a 2024 study" with no title, URL or numbers, although the web search agent returned all three.

Evidence. The coordinator's Task call to the synthesis agent says: "Synthesise the findings from the research so far into a report with citations."

Diagnosis. "The findings so far" exist only in the coordinator's context. The synthesis agent starts clean and received a sentence, not the findings. It wrote the best report it could from nothing.

Fix. Pass the findings themselves, in a structured form that keeps metadata separate from content: {

• "findings": [
• {"claim": "34% of EU employers use automated CV screening",
• "excerpt": "...roughly a third (34%) of surveyed employers...",
• "source": "https://example.org/eu-hiring-survey-2024",
• "document": "EU Hiring Technology Survey",
• "published": "2024-05-14"}
• ],
• "gaps": ["No UK data after 2023"]
• }

Takeaway. If a subagent needs it, it must be in the subagent's prompt. Nothing is inherited.

Worked example 2.D: Prompt rule versus hook

Situation. Finance requires that refunds above US$500 always go to a human. The system prompt says so in bold. Monitoring shows 0.7% of large refunds still go through. Analysis. 0.7% looks small, but at 2,000 large refunds a month that is 14 policy breaches. The requirement uses the word always, so probabilistic compliance is the wrong tool. Fix. A pre-tool hook on process_refund:

• async def refund_limit(input_data, tool_use_id, context):
• amount = input_data["tool_input"].get("amount", 0)
• if amount > 500:
• return {"hookSpecificOutput": {
• "hookEventName": "PreToolUse",
• "permissionDecision": "deny",
• "permissionDecisionReason":

"Refunds over $500 need a human. Call escalate_to_human with a hand-off summary."}}

return {}

The deny reason goes back to Claude, which then follows the escalation path. Keep the prompt rule too: it reduces how often the hook has to fire, and the hook guarantees the outcome. (Hook field names here follow the Agent SDK docs as of October 2026; check your SDK version.) Worked example 2.E: The multi-concern message

Situation. A customer writes: "My order 7731 arrived broken, I was charged twice for order 7740, and please update my address." The agent fixes the broken item and forgets the rest. Diagnosis. The agent treated the message as one request. The guide's pattern is to decompose into distinct items, investigate each (in parallel where they are independent), then answer once. Fix. Add explicit decomposition instructions with a few-shot example: "List each separate issue the customer raises. Resolve or escalate each one. Your final reply must address every listed issue." Keep a per-issue structured record (issue, order ID, status, outcome) so none drop out of a long conversation (see Chapter 6).

Worked example 2.F: Too-narrow decomposition, again

Situation. Asked about "risks of remote work for companies", the system returns a thorough report on cybersecurity and nothing on productivity, culture, legal or cost. Evidence. Coordinator log: subtasks "VPN vulnerabilities", "phishing risks for remote staff", "endpoint security". Diagnosis and fix. The coordinator anchored on the first sense of "risk" it thought of. Add a decomposition step that first lists the topic's major dimensions, checks them against the question, and only then assigns subtasks. Add a gap check after synthesis: "Which major dimensions of the question have no findings?" If any, re-delegate targeted searches.

Worked example 2.G: Resume, fork or start fresh?

• Situation Choice Why
• Yesterday's investigation is still valid; you
• want to continue
• --resume investigation-auth Prior context still holds

You refactored 3 files since yesterday Resume, and name the 3 changed files

Targeted re-analysis instead of

full re-exploration

Half the codebase was rewritten by a merge New session with a structured summary of what still holds

• Old tool results are stale and
• misleading
• You want to compare two migration
• strategies from the same analysis

fork_session twice from the baseline Independent branches, shared starting point

Deep dive: designing the coordinator prompt

The guide's skill statement is to give subagents goals and quality criteria, not procedures. The same applies to the coordinator itself. A coordinator prompt that works well in practice has five parts:

Role and output. "You coordinate research to produce a cited report answering the user's question."

Available subagents and when to use each. One line each, matching the AgentDefinition descriptions.

Decomposition rules. "First list the main dimensions of the question. Assign each dimension to a search subagent. Launch independent searches together." Quality bar. "Every claim needs a source and date. Note any dimension with weak coverage." Iteration rule. "After synthesis, check coverage against your dimension list. If a dimension is missing or thin, run targeted searches and synthesise again, up to two extra rounds." What it should not contain: hard-coded call sequences ("call search, then analysis, then synthesis, then report") for questions where the right path depends on what is found. That turns an agent back into a fixed pipeline and removes the adaptability that justifies using one.

Deep dive: when not to build an agent

The exam asks you to choose between model-driven loops and fixed pipelines (Task 1.6). A useful test is whether you can write the steps down before you see the input.

If... Prefer

The steps are the same for every input A fixed pipeline (prompt chaining); cheaper, easier to test The next step depends on what the last one found An agentic loop One step needs judgment but the rest are fixed A pipeline with one model call at that step Mistakes are costly and the order is mandated A pipeline, or an agent with hooks enforcing the order

A per-file code review followed by an integration pass is a pipeline. "Find out why checkout is slow" is an agent.

Common traps

Choosing "strengthen the system prompt" when the requirement is a guarantee. Use a hook or gate.

Assuming a subagent "knows" what the coordinator knows.

Blaming a downstream agent when the coordinator's decomposition was too narrow. Spawning parallel subagents across several turns instead of in one response.

Ending the loop on text content or an iteration cap.

Check yourself

Your loop ends whenever the response contains any text block. What goes wrong, and what should it check instead?

The synthesis subagent writes reports with no citations, although the search agent found URLs. Name two likely design faults.

Compliance says refunds over US$500 must always go to a human. Prompt rule or hook, and which hook point?

You changed three files since yesterday's analysis session. Resume or start fresh, and what do you tell the agent?