Designing Agentic Loops

The core agentic loop pattern: send a request, inspect stop_reason, execute tools, return results, and repeat. Master the lifecycle that powers every Claude agent and learn exactly how stop_reason drives loop control -- the single most tested concept in Domain 1.

Quick Reference

→An agentic loop repeats: send request -> inspect stop_reason -> execute tools -> append results -> repeat
→stop_reason 'tool_use' means Claude wants to call a tool -- continue the loop
→stop_reason 'end_turn' means Claude has finished -- break the loop and return
→stop_reason 'max_tokens' means the response was truncated -- handle gracefully
→Tool results are appended as a 'user' message with tool_result content blocks
→The model decides which tool to call next -- never hard-code tool sequences
→Always include the full assistant response in conversation history before appending tool results
→Safety limits (max iterations) are a secondary safeguard, not the primary termination mechanism
→Each loop iteration grows the conversation history -- monitor token usage
→Parallel tool calls: Claude may return multiple tool_use blocks in a single response

What Is an Agentic Loop?

Definition

An agentic loop is a programmatic while-loop that repeatedly sends messages to Claude, inspects the stop_reason of each response, executes any requested tool calls, and appends the results back to the conversation -- continuing until Claude signals completion with stop_reason 'end_turn'.

Every Claude-powered agent -- from a simple file-editing assistant to a complex multi-step research pipeline -- is built on the same fundamental loop. The key insight is that the model itself drives the decision-making. You do not write if/else trees to decide what tool to call next. Instead, you give Claude a set of tools, send it a task, and let it decide the sequence of actions needed to accomplish the goal. Your code's only job is to faithfully execute the tool calls Claude requests and feed the results back.

This is what distinguishes an agent from a simple chatbot. A chatbot processes one request and returns one response. An agent processes a request, takes actions, observes results, and iterates until the task is complete. The agentic loop is the engine that makes this possible.

The Agentic Loop Lifecycle

The agentic loop: Claude calls tools until stop_reason is "end_turn"

Understanding stop_reason Values

The stop_reason field is the single most important signal in the agentic loop. It tells your code exactly what to do next. Getting this wrong is the number one cause of broken agents.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.