Agentic Loops

Official Exam Guide Objectives

Task 1.1: Design and implement agentic loops for autonomous task execution.

Knowledge of

• The agentic loop lifecycle: sending requests to Claude, inspecting stop_reason ("tool_use" vs "end_turn"), executing requested tools, and returning results for the next iteration
• How tool results are appended to conversation history so the model can reason about the next action
• The distinction between model-driven decision-making (Claude reasons about which tool to call next based on context) and pre-configured decision trees or tool sequences

Skills in

• Implementing agentic loop control flow that continues when stop_reason is "tool_use" and terminates when stop_reason is "end_turn"
• Adding tool results to conversation context between iterations so the model can incorporate new information into its reasoning
• Avoiding anti-patterns such as parsing natural language signals to determine loop termination, setting arbitrary iteration caps as the primary stopping mechanism, or checking for assistant text content as a completion indicator

What You Need to Know

An agentic loop is the core execution cycle behind every Claude-based agent. It is deterministic control flow that you write in code — not a prompt trick, not a retry wrapper, not a chatbot turn. Claude never runs the loop; it answers one question per pass and your code decides what happens next. Get this lifecycle right and most of Domain 1 follows from it, because orchestration, hooks and session state all attach to points on this cycle. Get it wrong and the agent stops halfway through a task in production while passing every test you wrote.

The Agentic Loop Lifecycle

Four steps, repeated until the model reports that it is finished:

1. Issue the request. Call the Messages API carrying the entire conversation so far — the system prompt, every previous message, and the tool results produced on the last pass. The API is stateless, so anything absent from this payload does not exist as far as the model is concerned.

2. Branch on stop_reason. The response carries a field stating why generation stopped. Two values drive a basic loop:

   • "tool_use" — one or more tools have been requested. Another pass is needed.
   • "end_turn" — the model considers the work complete. Exit here.

3. When stop_reason is "tool_use": run each requested tool, add the results to the conversation as a new message, and return to step 1 with that extended history.

4. When stop_reason is "end_turn": stop looping and hand the final response back to the caller.

The append in step 3 is the step people drop, and dropping it fails quietly. Conversation history is the only route by which a tool result reaches the model — there is no side channel and no server-side memory of the call. Skip the append and pass 2 is byte-identical to pass 1, so the model is asked an unchanged question and has no reason to give a changed answer. It will either reissue the same tool call indefinitely, or decide it cannot proceed and stop with the task half-done. Both look like the model behaving badly and both are your control flow.

Model-Driven Decision-Making

Inside the loop, tool selection belongs to the model: it reads the task, weighs the tools it has been described, and chooses. That is model-driven decision-making. Its opposite is a pre-configured decision tree or a fixed tool sequence, where the developer settles the order at design time and the model only supplies arguments.

The exam prefers the model-driven option, and the reason is worth carrying rather than memorising. A hard-coded sequence covers exactly the paths its author imagined; the first request that does not fit one falls through it. A model choosing at runtime handles that request, and chains tools in orders nobody wrote down. What you give up is predictability of order — which is precisely why it is the wrong choice whenever the order is itself the requirement.

That exception is standing rather than occasional: where business logic demands deterministic compliance — financial operations, security checks, regulatory requirements — programmatic enforcement overrides model flexibility, because "almost always in the right order" is not a property a regulator accepts. Task Statement 1.4 covers where that enforcement is implemented.

The Three Anti-Patterns

Three anti-patterns recur for loop termination. All three are worth recognising on sight, because the exam presents them as reasonable-looking code rather than as obvious errors.

Anti-Pattern 1: Parsing natural language signals. Deciding the loop is over because Claude said "I'm done" or "task complete". The model was never constrained to a vocabulary of completion phrases, so no list of phrases detects completion reliably — and the near misses are the dangerous part. "I've finished analysing the first file" is a completion sentence about an unfinished task, and it will end the run with four files unread. Expanding the phrase list does not converge on correctness, because the space of things the model might say is not enumerable. stop_reason exists to delete the interpretation step rather than improve it.

Anti-Pattern 2: Arbitrary iteration caps as the primary stopping mechanism. Making "stop after 10 loops" the mechanism that ends the run. This is wrong in both directions simultaneously: a task genuinely needing 12 iterations is truncated, and a task finishing in 3 keeps circling to the ceiling. The truncation is the worse half, because a cut-off run returns a partial answer with no marker distinguishing it from a complete one. The model is already reporting completion on every pass; a cap discards that report in favour of a number chosen before the task began. Caps remain legitimate as a safety net — an upper bound that stops a runaway agent burning tokens — but never as the mechanism that decides the work is done.

Anti-Pattern 3: Checking for assistant text content as a completion indicator. Using response.content[0].type == "text" to conclude the loop has finished. content is an array that can hold several blocks of different types in one response, and Claude routinely returns explanatory text alongside a tool_use block — "I'll now search for the customer's order history", followed immediately by the call itself. What sits at index [0] reflects what the model chose to say first, which carries no information about whether work remains. Moving the check to [1] does not repair it either: block ordering is a presentational detail, not an interface guarantee.

Practical Example: The Premature Termination Bug

A developer builds a customer support agent. Simple queries work; complex ones sometimes stop mid-task. Completion is decided by if response.content[0].type == "text".

What happens on a failing request: the customer asks something needing a lookup, and Claude returns a text block explaining its intent ("Let me look up your order") followed by a tool_use block requesting lookup_order. Index [0] holds text, the condition is satisfied, the loop exits, and the customer receives a promise that their order will be looked up — while nothing looks it up. No error is raised anywhere, because from the code's point of view the agent finished normally.

Why it survived testing is the instructive part. Simple queries need no tools, so the model answers them with a single text block and the check happens to be correct. The condition only misfires on responses that contain a tool call — the path that is most awkward to cover in a unit test and most common in production traffic.

The fix is to stop inferring completion from output and read the field that states it: continue while stop_reason == "tool_use", terminate on stop_reason == "end_turn". That condition is indifferent to how many content blocks came back, what types they are, and what order they arrived in.

Deep Dive

The complete stop_reason enum

The exam keys on two values. The API reference documents seven, and a production loop has to branch on all of them. Every one of these arrives on a successful HTTP 200 response with valid content — stop reasons are part of the response body, not errors. Errors are 4xx/5xx and carry error details instead.

Anthropic's guidance is blunt: "Make it a habit to check the stop_reason in your response handling logic." The same page draws the line between stop reasons and errors: "stop reasons indicate why generation stopped normally (successful responses), while errors indicate request processing failures."

Sourcesplatform.claude.com › messagesplatform.claude.com › handling-stop-reasonsfetched 2026-07-30

Correct loop control for each value

The documented handling per value maps directly onto branch arms in your loop. Note that only tool_use continues the loop by executing tools; pause_turn continues it by resending unchanged.

pause_turn is the one most loops forget. It fires when a server-tool loop reaches its internal iteration limit, and the docs are explicit that "your application should handle pause_turn in any agent loop that uses server tools."

Sourceplatform.claude.com › handling-stop-reasonsfetched 2026-07-30

The canonical loop, and its exit condition

The documented shape is a while loop keyed on stop_reason:

// 1. Send a request with your tools array and the user message.
// 2. Claude responds with stop_reason "tool_use" and one or more tool_use blocks.
// 3. Execute each tool. Format the outputs as tool_result blocks.
// 4. Send a new request containing the original messages, the assistant's
//    response, and a user message with the tool_result blocks.
// 5. Repeat from step 2 while stop_reason is "tool_use".
while (response.stop_reason === "tool_use") {
  // ...
}

# 1. Send a request with your tools array and the user message.
# 2. Claude responds with stop_reason "tool_use" and one or more tool_use blocks.
# 3. Execute each tool. Format the outputs as tool_result blocks.
# 4. Send a new request containing the original messages, the assistant's
#    response, and a user message with the tool_result blocks.
# 5. Repeat from step 2 while stop_reason is "tool_use".
while response.stop_reason == "tool_use":
    ...

The exit condition is stated as the inverse: "the loop exits on any other stop reason (end_turn, max_tokens, stop_sequence, or refusal), which means Claude has either produced a final answer or stopped for another reason that your application should handle." That phrasing matters — exiting the loop is not the same as the task being complete.

Two structural facts underpin the whole design. First, "the model never executes anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation." Second, "the model can't run your code, so every tool call is a round trip: the model asks, you execute, you report back, the model continues."

Sourceplatform.claude.com › how-tool-use-worksfetched 2026-07-30

How tool_result blocks are appended — the placement rules

Appending tool results is not "add a message somewhere". There are hard formatting rules, and breaking them produces a 400 rather than degraded behaviour.

• A tool_use block carries three fields: id (unique, used to match the result later), name, and input (conforming to the tool's input_schema).
• Results go back in a user-role message containing tool_result blocks, each with tool_use_id matching the request's id, optional content, and optional is_error.
• "Tool result blocks must immediately follow their corresponding tool use blocks in the message history. You cannot include any messages between the assistant's tool use message and the user's tool result message."
• "In the user message containing tool results, the tool_result blocks must come FIRST in the content array. Any text must come AFTER all tool results."
• An empty result is valid: a tool_result block may carry only type and tool_use_id.
• On failure, return the error text as content with "is_error": true; Claude "will then incorporate this error into its response to the user." Distinct mechanism, same page: if Claude's own tool request is invalid or missing parameters, "Claude will retry 2-3 times with corrections before apologizing to the user" — that retry loop is about malformed calls, not about your tool failing at execution time.

There is no tool or function role in this API: "user messages include client content and tool_result, while assistant messages contain AI-generated content and tool_use."

Sourceplatform.claude.com › handle-tool-callsfetched 2026-07-30

Parallel tool calls in one iteration

"By default, Claude may call multiple tools in a single response," and Claude 4 and later models do so by default when the request benefits from it. Your loop must therefore treat tool_use as n calls, not one:

• Return "one tool_result for each tool_use block, all together in the next user message", matched by tool_use_id, with every tool_result before any text.
• Execution order is yours to choose: "you can run the calls concurrently (Promise.all, asyncio.gather), sequentially in the order they appear, or in any combination".
• Even a call you decline to run needs a result: return it "with is_error: true and a brief explanation".
• Splitting results across separate user messages "teaches" Claude to avoid parallel calls in future turns — the two rules that keep parallelism alive are one user message for all results, and no text before them.

To restrict this, disable_parallel_tool_use: true goes inside the tool_choice object, not at the top level. With tool_choice auto it means at most one tool per response; with any or tool it means exactly one.

Sourceplatform.claude.com › parallel-tool-usefetched 2026-07-30

Iteration caps are a safety bound, not a stop condition

Anthropic's own agent guidance treats caps as control, not completion: it is "common to include stopping conditions (such as a maximum number of iterations) to maintain control", precisely because "the autonomous nature of agents means higher costs, and the potential for compounding errors". The recommendation that goes with it is extensive sandboxed testing plus guardrails — not shorter loops.

The Agent SDK exposes the same idea as a first-class option, maxTurns/max_turns, documented in the SDK reference as "maximum agentic turns (tool-use round trips)". It bounds the loop; it never tells you the task finished. Completion is still stop_reason.

Sourcesanthropic.com › building-effective-agentscode.claude.com › typescriptfetched 2026-07-30

Why text alongside tool_use is normal, and why forcing tools backfires

Under the default tool_choice of {"type": "auto"}, "Claude determines on each turn whether to call a tool or respond directly" (tool-use overview), and "Claude often comments on what it's doing or responds naturally to the user before calling tools". The docs add the warning that kills anti-pattern 3 outright: "your code should treat these responses like any other assistant-generated text, and not rely on specific formatting conventions."

The distractor fix — forcing tool_choice: "any" so the model never returns bare text — has a documented side effect: "when you have tool_choice as any or tool, the API prefills the assistant message to force a tool to be used", so the model emits no natural-language response before the tool_use blocks even if asked to. It also cannot be combined with manual extended thinking, where only auto and none are supported (adaptive thinking, including models where thinking is on by default, does support forced tool use), and changing tool_choice invalidates cached message blocks under prompt caching.

Sourcesplatform.claude.com › define-toolsplatform.claude.com › overviewfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Build a Multi-Tool Agent Loop

Difficulty: Intermediate (2/4)

45 minutes

1. Set up a Claude API client with two tools: a calculator tool (accepts expression, returns result) and a web search stub (accepts query, returns mock results)

Why: Multi-tool setups expose model-driven decision-making — Claude must select the right tool based on context, which is core to agentic architecture.

You should see: Two tool definitions registered with proper JSON Schema input_schema, each with name, description, and parameters.

2. Implement the agentic loop that sends requests to Claude and inspects stop_reason after each response

Why: The agentic loop is the core execution pattern — the exam tests whether you use stop_reason (deterministic) versus content-type checks or natural language parsing (unreliable).

You should see: A while loop that calls client.messages.create() and checks response.stop_reason after each iteration.

3. Handle the tool_use stop_reason by executing the requested tool, creating a tool result message, and appending it to conversation history

Why: This is the critical handoff in the loop — the exam specifically tests whether you correctly extract tool calls, execute them, and return results in the right message format.

You should see: When Claude requests a tool, your code extracts the tool_use block, runs the corresponding function, and appends both the assistant response and a user message with tool_result to the conversation.

4. Handle the end_turn stop_reason by extracting and returning the final response

Why: end_turn is Claude signal that it has completed the task — extracting the final text response correctly closes the loop and returns the result to the user.

You should see: When stop_reason is end_turn, your loop exits and returns the text content from the final response.

5. Test with a prompt that requires multiple sequential tool calls (e.g., search for a value then calculate something with it) and verify the loop continues correctly through all iterations

Why: Sequential tool calls test the full loop lifecycle — the agent must complete one tool call, receive the result, reason about it, and decide to call another tool before finally returning.

You should see: At least two tool call iterations before end_turn. The agent searches first, uses the search result in a calculation, then returns the combined answer.

6. Add a safety iteration cap of 20 as a maximum bound (not the primary stopping mechanism) and log a warning if it triggers

Why: The exam distinguishes safety caps (acceptable as a fallback) from using caps as the primary stopping mechanism (an anti-pattern). Your cap should never trigger in normal operation.

You should see: A MAX_ITERATIONS constant, a counter that increments each loop, and a warning log if the cap is hit. Normal queries should terminate via stop_reason well before reaching 20.

Sources

• Claude Agent SDK Overview — Anthropic
• Messages API Reference — Anthropic
• Building with Claude API (Skilljar) — Anthropic
• Messages API — request and response reference — Anthropic
• Handling stop reasons — Anthropic
• How tool use works — Anthropic
• Handle tool calls — Anthropic
• Parallel tool use — Anthropic
• Define tools — Anthropic
• Building Effective Agents — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Set up a Claude API client with two tools: a calculator tool (accepts expression, returns result) and a web search stub (accepts query, returns mock results)

Why: Multi-tool setups expose model-driven decision-making — Claude must select the right tool based on context, which is core to agentic architecture.

You should see: Two tool definitions registered with proper JSON Schema input_schema, each with name, description, and parameters.

const tools = [
  {
    name: "calculator",
    description: "Evaluates a mathematical expression",
    input_schema: {
      type: "object" as const,
      properties: { expression: { type: "string" } },
      required: ["expression"]
    }
  }
];

tools = [
    {
        "name": "calculator",
        "description": "Evaluates a mathematical expression",
        "input_schema": {
            "type": "object",
            "properties": {"expression": {"type": "string"}},
            "required": ["expression"],
        },
    }
]

Step 2. Implement the agentic loop that sends requests to Claude and inspects stop_reason after each response

Why: The agentic loop is the core execution pattern — the exam tests whether you use stop_reason (deterministic) versus content-type checks or natural language parsing (unreliable).

You should see: A while loop that calls client.messages.create() and checks response.stop_reason after each iteration.

const messages: Anthropic.MessageParam[] = [{ role: "user", content: userPrompt }];
while (true) {
  const response = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    tools,
    messages
  });
  if (response.stop_reason === "end_turn") break;
  // Handle tool_use next
}

messages = [{"role": "user", "content": user_prompt}]
while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason == "end_turn":
        break
    # Handle tool_use next

Step 3. Handle the tool_use stop_reason by executing the requested tool, creating a tool result message, and appending it to conversation history

Why: This is the critical handoff in the loop — the exam specifically tests whether you correctly extract tool calls, execute them, and return results in the right message format.

You should see: When Claude requests a tool, your code extracts the tool_use block, runs the corresponding function, and appends both the assistant response and a user message with tool_result to the conversation.

const toolUse = response.content.find(b => b.type === "tool_use");
const result = executeTool(toolUse.name, toolUse.input);
messages.push({ role: "assistant", content: response.content });
messages.push({
  role: "user",
  content: [{ type: "tool_result", tool_use_id: toolUse.id, content: result }]
});

tool_use = next(b for b in response.content if b.type == "tool_use")
result = execute_tool(tool_use.name, tool_use.input)
messages.append({"role": "assistant", "content": response.content})
messages.append(
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": result}
        ],
    }
)

Step 4. Handle the end_turn stop_reason by extracting and returning the final response

Why: end_turn is Claude signal that it has completed the task — extracting the final text response correctly closes the loop and returns the result to the user.

You should see: When stop_reason is end_turn, your loop exits and returns the text content from the final response.

if (response.stop_reason === "end_turn") {
  const textBlock = response.content.find(b => b.type === "text");
  return textBlock?.text ?? "";
}

if response.stop_reason == "end_turn":
    text_block = next((b for b in response.content if b.type == "text"), None)
    return text_block.text if text_block else ""

Step 5. Test with a prompt that requires multiple sequential tool calls (e.g., search for a value then calculate something with it) and verify the loop continues correctly through all iterations

Why: Sequential tool calls test the full loop lifecycle — the agent must complete one tool call, receive the result, reason about it, and decide to call another tool before finally returning.

You should see: At least two tool call iterations before end_turn. The agent searches first, uses the search result in a calculation, then returns the combined answer.

const result = await runAgentLoop(
  "Search for the current price of Bitcoin and calculate what 3.5 coins would cost"
);
console.log("Iterations:", iterationCount);
console.log("Result:", result);

result = run_agent_loop(
    "Search for the current price of Bitcoin and calculate what 3.5 coins would cost"
)
print("Iterations:", iteration_count)
print("Result:", result)

Step 6. Add a safety iteration cap of 20 as a maximum bound (not the primary stopping mechanism) and log a warning if it triggers

Why: The exam distinguishes safety caps (acceptable as a fallback) from using caps as the primary stopping mechanism (an anti-pattern). Your cap should never trigger in normal operation.

You should see: A MAX_ITERATIONS constant, a counter that increments each loop, and a warning log if the cap is hit. Normal queries should terminate via stop_reason well before reaching 20.

const MAX_ITERATIONS = 20;
let iterations = 0;
while (true) {
  if (iterations >= MAX_ITERATIONS) {
    console.warn("Safety cap reached");
    break;
  }
  iterations++;
  // ... rest of loop
}

MAX_ITERATIONS = 20
iterations = 0
while True:
    if iterations >= MAX_ITERATIONS:
        logging.warning("Safety cap reached")
        break
    iterations += 1
    # ... rest of loop

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the code you actually wrote.