Chapter 1: Foundations: The Agent Loop and the Tool-Use Primitive

What an Agent Actually Is

Strip away the marketing and an "agent" is a small idea: a language model, a set of tools it is allowed to call, and a loop that keeps handing control back and forth until the work is done. Memory, planning, and autonomy are emergent behaviors of running that loop repeatedly. The tool-use primitive is what turns a text model into an actor — without tools, a model can only describe how to check the weather; it cannot check it.

This separation is the load-bearing wall of the whole book. The model owns reasoning: interpreting intent, selecting a tool, and composing well-formed arguments. Your code owns acting: executing the tool, handling the file system, network, authentication, and side effects, and returning a faithful result. Because execution lives entirely in your code, tool use is inherently sandboxable — the model can request a database delete, but your code can refuse. Security, rate limiting, and human-in-the-loop approval all live on your side of the line.

Figure 1.1: The reasoning/acting boundary — the model emits a request, the application executes and returns a result, control ping-pongs across a single dividing line.

Not everything that calls a model is an agent. A single-shot completion is one request and one response — a classifier or summarizer. A workflow is a fixed, developer-authored sequence of model calls; the control flow is decided in advance by you. An agent is different in kind: the model itself decides the control flow at run time, and the loop continues until it signals it is done.

Anatomy of the tool_use / tool_result Cycle

Tools are simply a tools parameter attached to an ordinary message request — the entire agentic machinery is built on the same stateless request/response endpoint you already use for plain text. Each tool entry has a name (matching ^[a-zA-Z0-9_-]{1,64}$), a detailed description (aim for three to four or more sentences: what it does, when to use it and when not to, and what each parameter means), and an input_schema — a JSON Schema object declaring the arguments' type, properties, and which are required. Setting strict: true guarantees inputs conform exactly but requires additionalProperties: false.

When Claude calls a tool, its response content contains a tool_use block — often preceded by a natural-language text block — carrying type: "tool_use", a unique id (e.g. toolu_01A09...), the tool name, and an input object. Never depend on the leading text's exact wording; it varies and can be absent. After your code runs the tool, you return a tool_result block inside a user-role message — conversationally, you are speaking on behalf of the tool. Its tool_use_id must exactly match the originating id, or the API rejects the request.

Figure 1.2: The four-message cycle — user question, assistant tool_use, user tool_result, assistant final answer — with the tool_use_id as the thread stitching call to result. Think of it as a coat-check ticket: hand over your coat, get ticket toolu_01A09, present the same ticket to retrieve exactly the right coat.

Every response carries a stop_reason — the authoritative, deterministic signal for what your loop should do next. Never parse natural-language text to decide whether to continue.

Figure 1.3: Branching on stop_reason — the deterministic signal that decides whether your loop continues, stops, or raises.

The Agent Loop in Code

The canonical five steps: (1) send a request with the tools array and user message; (2) Claude responds with stop_reason: "tool_use" and one or more tool_use blocks; (3) execute each tool and format outputs as tool_result blocks; (4) send a new request containing the prior messages, the assistant's response (with tool_use blocks preserved), and a user message of tool_result blocks; (5) repeat while stop_reason == "tool_use". The while loop is your code — the moment stop_reason comes back as tool_use, control has returned to your application; only the next create call hands it back to the model. This ping-pong is the loop.

Figure 1.4: The agent loop — call the model, branch on stop_reason, execute tools, append results, and repeat until end_turn.

Claude 4 models make parallel calls whenever a request benefits from multiple tools, so a single response can contain several tool_use blocks. Independent, read-only operations are typically run concurrently for lower latency; tools with side effects or ordering requirements are safer run sequentially. Whatever strategy you pick, obey the one-user-message rule — splitting results across multiple user messages "teaches" Claude to stop making parallel calls, the most common cause of lost parallelism. Also place every tool_result block before any text in that user message, or the API returns a 400.

Tools fail — networks time out, inputs are malformed, prerequisites are missing. The rule is to never silently drop a tool_result. Return is_error: true with an informative message; the error text is input to the model's next reasoning step, so make it descriptive. Claude typically retries with a different approach or reissues the call next turn. The SDK Tool Runner (beta) can drive the whole loop for you and auto-wraps raised exceptions as is_error results; reach for the manual loop when you need control over batching, ordering, custom error handling, or human-in-the-loop approval.

How Claude Decides to Call a Tool

The model's raw material for selection is the tool description and input_schema. A thin description like "gets data" forces the model to guess; a rich one lets it match user intent to capability confidently. In effect, you are not calling the tool — you are writing the documentation from which the model decides whether to call it. Under the default setting, Claude calls a tool when the request maps to a described capability and the answer is not already in context; "Use the tools to investigate before responding" pushes tool use up, while "Use your judgment..." keeps it conservative.

Figure 1.5: The tool_choice decision — how the four modes gate whether and which tool Claude may call.

Two behaviors are easy to trip over. With any or tool, the API prefills the assistant turn to force a tool call, so Claude will not emit natural-language text before the tool_use block. And with extended thinking, only auto and none are supported — any and tool return an error, precisely because they suppress the reasoning preamble that thinking depends on. In auto mode Claude often emits a natural-language text block first — a lightweight chain of thought that improves tool selection and argument quality.

The unifying lesson: most "model" failures are specification failures. Wrong arguments usually mean an under-constrained schema; over- and under-calling usually mean an ambiguous description or the wrong tool_choice. Because you own the specification, you own most of the fix. Guard the one genuinely unrecoverable case — a hallucinated tool name — in code: your run_tool dispatcher should return a clear is_error result for any unknown name rather than crashing, letting the model self-correct next turn.