[{"id":"ccarf-loop-stop-reason","courseId":"ccar-f","domain":"agentic-architecture-orchestration","topic":"Loop control by stop_reason","prompt":"Your support agent's loop ends whenever a response contains a text block. Logs show turns like \"Let me check that order\" plus a lookup_order call, after which the loop exits and the customer never gets an answer. What is the root cause?","hint":"Which response field states why Claude stopped generating?","explain":"A reply can mix narration text with tool requests in one message. Consider what metadata the response carries about why the reply was produced, and how a loop might read it.","source":"https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons","interaction":{"type":"single"},"options":[{"id":"a","text":"The system prompt lacks a rule forbidding text before tool calls, so Claude narrates and the loop exits.","whyNot":"Text alongside tool_use is normal output, so the fix belongs in loop control, not in the prompt."},{"id":"b","text":"The loop treats any text block as \"done\" instead of checking stop_reason for \"tool_use\".","why":"A response can hold text and tool_use blocks together. stop_reason \"tool_use\" means Claude wants a tool run and the result sent back; \"end_turn\" means it is done. Text content is not a completion signal."},{"id":"c","text":"The loop needs a fixed cap of ten iterations so it keeps going after text appears.","whyNot":"An iteration cap is a safety limit, not a signal that the task is finished."},{"id":"d","text":"lookup_order should be forced with tool_choice so no text is emitted alongside it.","whyNot":"Forcing one tool on every turn would stop Claude from ever finishing with a final answer."}],"answer":"b","explanation":"An agentic loop is a cycle of request, tool execution and result. The API's stop_reason field, not the content of a reply, tells your code whether to run another cycle or stop.","concept":"An agentic loop is a cycle of request, tool execution and result. The API's stop_reason field, not the content of a reply, tells your code whether to run another cycle or stop.","rev":1,"kind":"scenario","takeaways":["Drive the loop by stop_reason: run tools on \"tool_use\", stop on \"end_turn\"."]},{"id":"ccarf-error-max-turns","courseId":"ccar-f","domain":"agentic-architecture-orchestration","topic":"Recovering from turn limits","prompt":"A nightly Agent SDK job that writes boilerplate sometimes ends with a ResultMessage whose subtype is \"error_max_turns\". The script then reads the result field and gets nothing. What should the architect do?","hint":"Even an error result carries something you can use to continue.","explain":"A run can halt at a configured ceiling on loop iterations, which differs from completing its task. Outcome labels tell those cases apart in the report. Consider what a script can still reuse after an early stop.","source":"https://code.claude.com/docs/en/agent-sdk/agent-loop","interaction":{"type":"single"},"options":[{"id":"a","text":"Use the last assistant message as the final output instead.","whyNot":"Hitting the limit means the loop stopped early, so the last message is not a final answer."},{"id":"b","text":"Treat the run as unfinished and resume its session_id with a higher turn limit.","why":"When a limit stops the loop, the SDK returns an error subtype such as error_max_turns, and only the success subtype carries result. Every result still carries session_id, so you can resume with prior context and a higher limit."},{"id":"c","text":"Remove maxTurns and rerun the whole job from the start whenever it fails.","whyNot":"Restarting throws away finished work, and without a limit a runaway loop has no safety cap."},{"id":"d","text":"Raise maxTurns globally and keep reading result without checking the subtype.","whyNot":"The result field exists only on success, so the subtype must still be checked first."}],"answer":"b","explanation":"An Agent SDK run always ends with a ResultMessage, but only a successful run has a final answer. Limit-hit runs are resumable, so a stopped job can continue rather than start over.","concept":"An Agent SDK run always ends with a ResultMessage, but only a successful run has a final answer. Limit-hit runs are resumable, so a stopped job can continue rather than start over.","rev":1,"kind":"scenario","takeaways":["Check ResultMessage.subtype before reading result; resume by session_id after a limit error."]},{"id":"ccarf-parallel-tool-results","courseId":"ccar-f","domain":"agentic-architecture-orchestration","topic":"Returning parallel tool results","prompt":"Your research agent asks for three web_search calls in one response. Your loop runs them and sends each tool_result back in its own user message. Over time Claude stops batching searches and latency climbs. Which change best fixes this?","hint":"How many user turns should answer one assistant turn?","explain":"Each requested call carries an identifier that its answer must echo back. Consider how the transcript is divided into turns, and how many user-side messages respond to one assistant message.","source":"https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use","interaction":{"type":"single"},"options":[{"id":"a","text":"Keep one message per result, but label which call each answers.","whyNot":"Splitting results across messages is the pattern that teaches Claude to stop calling tools in parallel."},{"id":"b","text":"Send all three tool_result blocks together in one user message, before any text.","why":"For parallel calls, every tool_result belongs in a single user message, with any text after the results. Sending a separate message per result is the most common reason Claude stops making parallel calls."},{"id":"c","text":"Disable parallel tool use and have the agent run one search per turn.","whyNot":"That locks in the slow sequential behavior instead of fixing the result format."},{"id":"d","text":"Merge the three outputs into one tool_result for the first tool_use_id.","whyNot":"Each tool_use_id needs its own tool_result, so merging leaves two calls unanswered."}],"answer":"b","explanation":"Claude can request several independent tools in one turn. How you format the replies is part of the conversation it learns from, so the reply shape affects whether it keeps batching.","concept":"Claude can request several independent tools in one turn. How you format the replies is part of the conversation it learns from, so the reply shape affects whether it keeps batching.","rev":1,"kind":"scenario","takeaways":["Parallel calls: one user message, all tool_result blocks first, text after."]},{"id":"ccarf-subagent-context-passing","courseId":"ccar-f","domain":"agentic-architecture-orchestration","topic":"Passing context to subagents","prompt":"The coordinator gathers 30 sourced findings, then spawns the synthesis subagent with the prompt \"Write the report from our findings.\" The report is generic and cites nothing. What is the root cause?","hint":"List what a non-fork subagent actually receives when it starts.","explain":"Compare a parent's accumulated session, including earlier tool outputs, with what a newly launched agent is handed. Standing project files and per-run task text are different channels.","source":"https://code.claude.com/docs/en/agent-sdk/subagents","interaction":{"type":"single"},"options":[{"id":"a","text":"The synthesis subagent runs on a smaller model that can't reliably recall the coordinator's earlier turns.","whyNot":"No model can recall turns it never received, because parent history is not inherited."},{"id":"b","text":"The subagent only saw the one-line prompt; findings in the coordinator's history aren't inherited.","why":"A non-fork subagent starts fresh, without the parent's conversation or tool results. The only content passed from parent to subagent is the Agent tool's prompt, so complete findings and their source metadata must go there."},{"id":"c","text":"The synthesis subagent should get web search so it can find the sources again.","whyNot":"Searching again duplicates work and still ignores the findings the coordinator already holds."},{"id":"d","text":"The findings belong in CLAUDE.md so that every subagent loads them at startup.","whyNot":"CLAUDE.md holds standing instructions, not per-run data, and rewriting it each run is fragile."}],"answer":"b","explanation":"A subagent is a separate conversation with its own context window. It knows only what the delegating agent writes into its task, so everything it needs must be handed over explicitly.","concept":"A subagent is a separate conversation with its own context window. It knows only what the delegating agent writes into its task, so everything it needs must be handed over explicitly.","rev":1,"kind":"scenario","takeaways":["Subagents inherit no parent history: put findings and source metadata in the delegation prompt."]},{"id":"ccarf-parallel-subagents","courseId":"ccar-f","domain":"agentic-architecture-orchestration","topic":"Spawning subagents in parallel","prompt":"Your coordinator splits a market question into four independent subtopics but spawns one search subagent per turn, waiting for each before starting the next. Runs take 12 minutes. Which change best cuts latency without losing coverage?","hint":"The subtopics don't depend on each other. What does that allow?","explain":"A coordinator can run child agents one after another or launch several at once. Think about what sets the length of the whole run, and how one long child compares with several short ones started together.","source":"https://www.anthropic.com/engineering/multi-agent-research-system","interaction":{"type":"single"},"options":[{"id":"a","text":"Merge the four subtopics into one subagent prompt so a single agent covers the whole question end to end.","whyNot":"One agent then works through the subtopics in series and fills its context faster."},{"id":"b","text":"Lower each subagent's turn limit so every run in the sequence finishes sooner.","whyNot":"Shorter runs give up coverage while keeping the serial bottleneck."},{"id":"c","text":"Issue all four Agent tool calls in a single coordinator response so the subagents run concurrently.","why":"Independent subtasks are the case for parallel subagents: total time approaches the slowest one, not the sum. Anthropic's research system cut research time sharply by having the lead agent start several subagents at once instead of serially."},{"id":"d","text":"Drop the subagents and let the coordinator call web search itself in a loop.","whyNot":"That keeps the work serial and floods the coordinator's context with raw results."}],"answer":"c","explanation":"Subagents exist partly to run work concurrently. Tasks that don't depend on each other can run side by side, so wall-clock time tracks the longest task rather than the total.","concept":"Subagents exist partly to run work concurrently. Tasks that don't depend on each other can run side by side, so wall-clock time tracks the longest task rather than the total.","rev":1,"kind":"scenario","takeaways":["Independent subtopics: spawn the subagents in one coordinator response, not one per turn."]}]