Ussama Assad Start a project

Domain 1 of 5 · 27% of the exam

Agentic Architecture & Orchestration

What it covers

Agent loops and stop_reason, coordinators and subagents, passing context, enforcing step order, Agent SDK hooks, task decomposition, resuming and forking sessions. About 27% of scored items, by the official exam guide.

Know cold

One idea per card. Open the ones you aren't sure of.

stop_reason runs the loop

Run the requested tools and continue on "tool_use"; stop on "end_turn". Never decide from the shape of the content: one response can hold a text block and a tool_use block, in that order.

The other stop_reason values

Current docs list seven: end_turn, tool_use, max_tokens (your output limit cut it off), stop_sequence, pause_turn (a server-tool loop hit its iteration limit; send the content back to continue), refusal, and model_context_window_exceeded (the response filled the model's context window). Treat max_tokens and model_context_window_exceeded as truncated output.

A truncated tool call never runs

If max_tokens cut a tool_use block short, retry with a higher max_tokens.

The coordinator is the only pipe

Subagents don't see each other or the coordinator's history. Whatever the next subagent needs, the coordinator passes in its prompt, ideally as structured findings with a source on each.

Order that matters goes in code

"Verify before refund" belongs in the tool handler or a hook, not in a prompt line.

Agent SDK hooks

PreToolUse runs before a call and can deny it. PostToolUse runs after and can work on the result before the model sees it.

Decomposition

For review across many files: a local pass per file, then a separate pass for cross-file issues.

Sessions

Resume a named session with --resume. Fork (fork_session in the Agent SDK) to try two approaches from the same analysis. A git worktree splits code, not conversation.

Traps

  • Reading "done" from a text block. A response can hold text and then a tool call. Read stop_reason, not the shape of the content.
  • Step order in a prompt line. A prompt line makes the right order likely, not certain. When order must hold, check it in the handler or deny it in a PreToolUse hook.
  • A worktree for a second approach. A git worktree splits code, not conversation. To try two approaches from the same analysis, fork the session.
  • Adding a component to fix a handoff. A shared queue or a shared context sounds thorough. When a subagent is missing facts, the fix is what the coordinator passes it.

Practice: 4 questions

Q1 · Domain 1 · Agentic Architecture & Orchestration

A trip-planning assistant runs its own loop on the Messages API. The loop ends as soon as the latest response contains a text block. Users report the assistant saying "Let me check flights for you" and then going quiet. What is the bug, and what is the fix?

  1. A. The model needs a firmer instruction to finish its work before it replies, so add one to the system prompt.
  2. B. The loop needs a hard cap of 20 iterations so that it cannot stop before the work is done.
  3. C. Drive the loop from stop_reason: run the tools and continue on "tool_use", stop on "end_turn".
  4. D. Set tool_choice to "any" on every turn so that the model never answers in plain text at all.
Answer and explanation

Answer: C. stop_reason is the field the API sets to say why generation stopped. A text block can come before a tool_use block in the same response, so the text check exits while a tool call is still waiting. A cap is a safety net, not a completion signal. "any" on every turn would stop the assistant from ever giving a final answer. A prompt line is advice the model can still miss.

  • A. A prompt line is advice the model can still miss, and the loop would still exit on the first text block.
  • B. A cap is a safety net against a runaway loop. It is not a completion signal, and the loop would still exit on the first text block.
  • C. Right. stop_reason is the field the API sets to say why generation stopped. A text block can come before a tool_use block in the same response, so the text check exits while a tool call is still waiting.
  • D. Forcing a tool call on every turn means the assistant can never give its final answer in text.

Q2 · Domain 1 · Agentic Architecture & Orchestration

Your agent gets a response with stop_reason "max_tokens". The last content block is a tool_use block for create_invoice, and its input is cut off halfway through the line items. What should the loop do?

  1. A. Don't run it. Retry the request with a higher max_tokens so the whole tool call comes back.
  2. B. Run create_invoice with the line items that did arrive, then ask the model for the rest.
  3. C. Treat the turn as finished and show the user whatever text came before the tool call.
  4. D. Change tool_choice to "auto" and then resend exactly the same request a second time.
Answer and explanation

Answer: A. max_tokens means the output limit you set cut the response off. Anthropic's stop-reason docs say a truncated response with an incomplete tool_use block needs a retry with a higher max_tokens. Running a half-formed call writes a wrong invoice. Treating it as finished ignores pending work, and changing tool_choice does nothing about the limit that caused the cut.

  • A. Right. max_tokens means the output limit you set cut the response off. Anthropic's stop-reason docs say an incomplete tool_use block needs a retry with a higher max_tokens.
  • B. Running a half-formed call writes a wrong invoice. A truncated tool call should never run.
  • C. The response stopped because of the limit, not because the work was done. Treating it as finished ignores the pending tool call.
  • D. tool_choice does nothing about the output limit that caused the cut, so the same request gets cut off again.

Q3 · Domain 1 · Agentic Architecture & Orchestration

A coordinator agent sends a market-research subagent out first and a writing subagent second. The writer often quotes prices with no source, and some of them differ from what the researcher found. The two subagents never talk to each other. Where does the fix belong?

  1. A. Give the writer the same search tools as the researcher so it can look the prices up itself.
  2. B. Add a shared message queue so the writer can send the researcher questions while it drafts.
  3. C. Run both subagents inside one long-lived shared context so each can see what the other knows.
  4. D. Have the coordinator pass the researcher's findings on as claim, value, source and date.
Answer and explanation

Answer: D. A subagent only knows what the coordinator hands it. The writer is guessing because nothing was handed over. Extra search tools repeat work that is already done, a message queue adds a component and breaks the isolation the pattern relies on, and one shared context swaps a handoff problem for a context-size problem.

  • A. The researcher already found the prices. Extra search tools repeat work that is already done.
  • B. A message queue adds a new component and breaks the isolation the coordinator pattern relies on.
  • C. One shared context swaps a handoff problem for a context-size problem.
  • D. Right. A subagent only knows what the coordinator hands it. The writer is guessing because nothing was handed over, so pass each finding with its source and date.

Q4 · Domain 1 · Agentic Architecture & Orchestration

A returns agent must confirm the customer's identity with verify_customer before it may call issue_refund. Logs show it occasionally refunds first. Which two changes make that order impossible to skip? (Select 2)

  1. A. Put "ALWAYS verify the customer first" at the very top of the system prompt, in capitals.
  2. B. In the issue_refund handler, refuse unless the session holds a verified customer ID, and return an error saying why.
  3. C. Add four few-shot examples to the prompt in which verification always comes first.
  4. D. Register a PreToolUse hook in the Agent SDK that denies issue_refund when no verified ID is recorded.
  5. E. Move verify_customer to the first position in the tools array.
Answer and explanation

Answer: B and D. The handler check and the PreToolUse hook both act outside the model's choice, so the refund cannot run without a verified ID. Capitals, examples and tool order all change what the model is likely to do, and "likely" is how it already behaves. The handler check also protects you if the tool is ever called from somewhere else.

  • A. Capitals change how likely the model is to verify first. It already verifies most of the time, and "most of the time" is the failure.
  • B. Right. The handler refuses outside the model's choice, so the refund cannot run without a verified ID. It also protects you if the tool is ever called from somewhere else.
  • C. Examples make the right order more likely. They don't make the wrong order impossible.
  • D. Right. A PreToolUse hook runs before the call and can deny it, so the refund cannot run without a verified ID.
  • E. The order of the tools array is not a rule about call order. Like the prompt options, it only changes what the model is likely to do.