1.1 Designing Agentic Loops

Let's start before the jargon. Imagine you ask a colleague, "What's the weather in Paris, and should I pack a coat?" To answer, they can't just think harder — they have to DO something: look up the forecast, read the result, and only then form an opinion. They take an action, observe what comes back, and decide what to do next. If the first website is down, they try another. When they finally know enough, they stop and answer you.

A large language model on its own can't do that. By default it does exactly one thing: you send it text, it sends text back, and the exchange is over. It has no hands — it can't actually call a weather API, read a file, or run a search. It can only describe what it would like to do. That single request-and-reply is powerful for writing or reasoning, but it is a dead end the moment the task requires real actions in the world.

An "agent" is what we call the model once we give it that ability to act — to use tools, see the results, and keep going until the job is done. And the machinery that makes this possible is astonishingly simple: a loop. Your program asks the model what it wants to do, does it, hands back the result, and asks again. Round and round until the model says, "I'm finished." That repeating cycle is the agentic loop, and it is the single most important pattern in this entire domain. Everything else in Domain 1 — orchestration, hooks, handoffs — is built on top of it.

Here is the question that trips people up, and the exam loves it: in an agentic loop, who decides what happens — your code, or the model? The answer is a deliberate split, and getting it clear now will make everything that follows obvious.

The model decides WHAT to do. On each turn it looks at the conversation so far and chooses, in its own words, which tool it wants to use and with what inputs — "call get_weather with city=Paris." This is called model-driven decision-making: the model reasons about the situation and picks the next action, rather than following a fixed script you wrote in advance. That's exactly what makes agents flexible — they can handle a request you never explicitly planned for, and chain tools together in an order you didn't hard-code.

But the model never actually runs anything. It has no power to execute a tool, and it cannot decide to keep going or stop on its own. Your loop — plain code that you control — does all of that: it reads the model's request, runs the real tool, and decides whether to go around again. Think of it like a driving instructor and a learner. The learner (the model) says "turn left here" and "now speed up." The instructor (your code) has the dual controls — they're the one who can actually hit the brakes, and they decide when the lesson is over. The model proposes; your code disposes.

This split has a practical consequence we'll return to in Lesson 1.4: because the model only *proposes*, you can put hard rules in your code that it cannot override. For now, just hold the picture: model chooses the move, your code controls the car.

Now we can walk through the actual loop. It's four steps, repeated until the model is done. We'll follow our weather example the whole way through so it stays concrete.

• 1.SEND. Your code sends a request to Claude through the Messages API. Crucially, you send the ENTIRE conversation so far — the original question, everything the model has said, and the results of any tools you've run. (Why you resend everything is the subject of the next section.)
• 2.INSPECT. The response comes back with a special field called stop_reason. This one field tells your code what just happened. Your code reads it — it does not read the model's prose to guess. This is the decision point of the whole loop.
• 3.ACT (if the model wants a tool). If stop_reason says "tool_use", the model is asking you to run something — say, get_weather(city=Paris). Your code runs the real function, gets the answer ("12°C, rain"), adds that result onto the conversation, and goes back to step 1.
• 4.FINISH (if the model is done). If stop_reason says "end_turn", the model has everything it needs and has written its final answer. Your code exits the loop and shows the user the reply: "It's 12°C and rainy in Paris — yes, pack a coat."

Notice that the loop can run many times for a single user question. "What's the weather in Paris and Tokyo?" might go: ask → tool_use(get_weather Paris) → run it → ask again → tool_use(get_weather Tokyo) → run it → ask again → end_turn. Three trips to the model, two tool calls, one final answer. The model decided it needed two lookups; your loop faithfully carried each one out.

Step 3 said "append the tool result to the conversation, then loop back." That little instruction is where most beginner agents quietly break, so let's slow down and really understand it.

The Messages API is stateless. "Stateless" means it has no memory of your previous requests — each call is a blank slate. The model does not secretly remember that thirty seconds ago it asked for the Paris weather. If you want it to know something, that something must be physically present in the conversation you send THIS time. The API is like a brilliant consultant with total amnesia between meetings: every meeting, you must re-hand them the entire case file, or they'll start from nothing.

So when a tool returns a result, you don't just hold onto it in a variable — you append it to the conversation history as a new message, and then resend the whole history. Now, on the next turn, the model can actually SEE that get_weather returned "12°C, rain" and reason about it: "Rain means a coat is sensible." If you forget to append the result, the model asks for the weather, you fetch it, and then you send back... the same conversation as before, with no weather in it. The model, seeing no answer, asks for the weather AGAIN. You've built an infinite loop of forgetting.

We keep saying "read stop_reason, don't read the model's words." Let's understand why that rule is so absolute, because it's the single most tested idea in this lesson.

When the model finishes a turn, it could in principle TELL you it's done in plain English — "I've finished, here's your answer." The temptation is to write code that scans its reply for phrases like that. Resist it completely. Natural language is ambiguous: the model might write "I've finished analysing the first file" while fully intending to keep going with the next one. If your code sees the word "finished" and stops, you've cut the agent off mid-task. Human language was never designed to be a control signal.

That's exactly why every Messages API response includes stop_reason — a small, fixed, machine-readable field whose entire job is to tell your code, unambiguously, why the model stopped. It is deterministic: the same situation always produces the same value. It is the one true signal. The exam centers on two of its values — "tool_use" (the model wants to run a tool, so continue) and "end_turn" (the model is genuinely done, so stop) — but a production-grade agent should recognise all of them, because the others tell you about real situations you must handle gracefully.

Now that you understand WHY stop_reason rules the loop, the classic mistakes almost explain themselves. Each one is a way of trying to control the loop with the wrong signal. The exam tests these relentlessly, usually as "an agent is misbehaving — what's the fix?" The fix is essentially always: use stop_reason.

• •Reading the model's words to decide it's done. ✗ Checking whether the reply contains "I'm finished." ✓ Check stop_reason — language is ambiguous ("finished the first file" ≠ finished everything), which is the exact problem stop_reason was created to solve.
• •Using an iteration cap as the main stop. ✗ "Stop after 10 loops" as the primary rule. This either cuts off a task that needed 12 steps or wastes turns on one that finished in 3. ✓ Stop on end_turn; keep a cap (say 20) only as a safety net so a buggy agent can't run forever.
• •Checking the content type. ✗ Deciding you're done because response.content[0].type == "text". ✓ Use stop_reason — the model can return explanatory text AND a tool_use request in the very same response, so seeing text first means nothing.
• •Forcing the model to always call a tool. ✗ Setting tool_choice: "any" to stop it from replying in text. ✓ Don't — if the model is forced to call a tool every turn, it can never reach end_turn, and you've built an agent that literally cannot stop.

You now have every piece: why agents need a loop, who controls what, the four-step lifecycle, why history is resent, the role of stop_reason, and the anti-patterns. The fastest way to make it stick is to build a tiny agent and then deliberately break it — because feeling the failure is what cements the rule.

Everything in the rest of Domain 1 is this loop, scaled up. Multi-agent orchestration (1.2) is a loop that spawns more loops. Hooks (1.5) are code that runs at specific moments inside the loop. Workflow enforcement (1.4) is your code using its control of the loop to guarantee certain steps happen. Master the loop here and the rest of the domain becomes a series of natural extensions.