Measured Academy Measured Academy
Français Pilot Progress 0

Module 4 · Lesson 1 of 4

The loop, drawn once

  1. What happenedSix questions went through one two-tool agent and took different numbers of model calls, from a single call to several, with no change to the code between them.
  2. Why it changedIn an agent the model asks for a tool and your code runs it and sends the result back, so the number of round trips is decided by the question at run time, not by the source file.
  3. How it is measuredEach model call is counted as a step, and the stop reason and the name and input of every tool request are logged per step.
  4. How to improve itIterate over every content block, send the assistant turn back unchanged, keep the message list, and print the trace before you need it.
Step through

One question, step by step

Try it. Pick one of the six questions and press "Next step" to follow the loop one model call at a time.

Where this data comes from · claude-opus-4-6, 2026-08-28; claude-opus-5, 2026-11-20

Read from the book's saved record. Nothing here is simulated.

  • BOOK.md Measured findings
  • chapters/chapter-04-your-first-agent.md "How you verify"
  • scripts/ch03_trace.py
  • runs/ch4-course-agent-2026-11-20-run3.jsonl

Step counts and tool requests are the chapter's results table. The run's output was not kept, so each result shown is recomputed by running the tool's own code from scripts/ch03_trace.py on the recorded input.

What happened

A small agent was given two tools, a stock lookup and a calculator, and six questions about a four-item inventory. The same code ran all six. The number of model calls it took was different almost every time.

In order, the six questions took 2, 2, 3, 2, 4, 1 steps on the book's run (BOOK.md, Measured findings, claude-opus-4-6, 2026-08-28), and 2, 1, 3, 2, 3, 1 on the course's passing run on a current model (runs/ch4-course-check-2026-11-20-run3.txt, claude-opus-5, 2026-11-20).

Question Book run, claude-opus-4-6 Steps Course run, claude-opus-5
How many headsets are in stock? one lookup first in each list above one lookup
What is twelve times forty-five? the calculator 2 on the book run no tool: answered in one step
What are the webcams on hand worth? a lookup, then the calculator 3 on both a lookup, then the calculator
More keyboards or headsets? two lookups in one response 2 on both two lookups in one response
Cost to bring mice up to ten units? a lookup that missed, a second lookup, the calculator 4 on the book run a lookup for "mouse", then the calculator
A good reorder policy for slow items? none 1 on both none

The two runs disagree on two questions, and the code was the same. Use the "Recorded run" switch on the stepper above to walk through either one; on the course run the answers are the model's own words, read from the run file.

One thing to know about the book's column: the output of that run was not kept. Its figures survive as rows in BOOK.md. The course run's file holds every request, result and answer. Lesson 4 comes back to what stands behind each.

Why it changed

In Module 2 you drew the line between a chain and an agent: in a chain you write the order of the calls, and in an agent the model chooses the next step. This is what that looks like in code.

A tool-using call has four moves:

  1. You declare tools. Each has a name, a description and a schema for its input.
  2. The model asks. When it wants a tool, the response's stop reason is tool_use and its content holds one or more request blocks, each with an id, a tool name and an input that is already parsed.
  3. Your code decides. The model runs nothing. It emits a request, and your code chooses whether and how to execute it.
  4. The result goes back. You append the model's turn to the message list unchanged, then a user turn holding a result for each request, matched by id.

Then you call again. The loop ends when a response comes back that is not a tool request.

Chain (Module 2) Agent (this module)
Who picks the next call you, in the source the model, in its response
Number of calls fixed, readable in the file varies with the question
Where the sequence is written down the code only in the message list of a run

That last row is the practical consequence. You cannot read what the agent did from the file. Step through one question in the viewer above and watch the message list grow: that list is the only record of the order things happened in.

How it is measured

  • A step is one model call. Count every call to the model, including the last one that returns the answer. A question answered directly is one step.
  • The stop reason, every step. It is the loop's control variable: tool_use means go round again, end_turn means the model considers itself finished.
  • Tool name and full input, every request. The name tells you which tool. The input tells you what was asked, and Lesson 3 shows a retry you can only see in the inputs.
  • What kind of evidence this is. One run of six prompts on each of two models. The mechanics in the list above (the shapes of the request and result blocks) are separate rows in BOOK.md, confirmed against SDK 1.2.0.

How to improve it

  • Iterate the content list. Never index it. A response can hold more than one block, as Lesson 4 shows.
  • Send the assistant turn back as it arrived. The SDK accepts the response content unchanged; rebuilding it by hand is where blocks get lost.
  • Dispatch on the tool's name through a dictionary of functions, so adding a tool is one entry.
  • Keep the message list. It is the trace. Print it before you have a wrong answer to explain.
  • Treat the description as part of the prompt. It is the main thing telling the model when a tool applies. Module 10 measures how far it goes.

The four moves and the loop are printed in Chapter 4 of the book, "The concept" and "Before / After". Next: two exits and a cap.

Every number in this lesson, and the file it came from (7)
ValueFile in the book's recordConditions
2, 2, 3, 2, 4, 1BOOK.mdclaude-opus-4-6, SDK 1.2.0, 2026-08-28, one run, MAX_STEPS = 5; the output was not kept
2, 1, 3, 2, 3, 1runs/ch4-course-check-2026-11-20-run3.txtclaude-opus-5, 2026-11-20, third attempt, check PASS
2BOOK.md
3BOOK.md
2BOOK.md
4BOOK.md
1BOOK.md

Reference: Chapter 4, "The concept", the architecture diagram description and "Before / After".