The Agent Loop

Time: ~12 minutes. Tangible win: trace one full agent run, name the line that decides when it stops, and say who (model or code) owns each responsibility.

You already know how to call a model and read its response. An agent adds one thing: the model can ask for a tool, and your code runs it and reports back. Everything else in agentic systems is a detail hung on that cycle, so this lesson builds the cycle by hand before any framework enters the picture.

Primary source Building effective agents, Anthropic: the workflow versus agent distinction and why the simplest design that works is the right starting point. Read the first two sections before the next lesson.

The cycle

Every tool-using agent runs the same loop. Your application sends the conversation and the tool definitions to the model. The model answers in one of two ways. It either requests a tool, which sets stop_reason to tool_use, or it finishes, which sets stop_reason to end_turn (stop reasons documentation). On tool_use, your code runs the requested tool, appends the result as a tool_result message, and calls the model again.

messages = [user_request]
steps = 0

while True:
    response = model.create(
        model="claude-sonnet-5-5",
        messages=messages,
        tools=tool_definitions,
    )
    messages.append(response.content)

    if response.stop_reason == "end_turn":
        return response.text              # the model decided it is done

    if response.stop_reason == "tool_use":
        steps += 1
        if steps > MAX_STEPS:              # your guardrail, not the model's
            return "Stopped: step limit reached"
        results = [run_tool(block) for block in response.tool_use_blocks]
        messages.append(tool_results(results))

Who owns what

The model chooses which tool to request and when to stop. It does not run the tool, count the steps, or enforce a budget. Those belong to your code.

ResponsibilityOwner
Choose the next tool and its argumentsModel
Execute the tool and handle its errorsYour code
Decide the run is completeModel signals it, your code acts on it
Cap steps, cost, and timeYour code
Approve risky actionsYour code, or a human through it
Guardrails live outside the model Anything you leave out of the loop does not exist for the agent. A step cap, a cost ceiling, or a permission check must sit in your code, where the model cannot override it.

Practice

  1. Using the pseudocode above, add a MAX_STEPS guardrail set to 10. Confirm that a model stuck in a loop stops at the limit and returns a clear message.
  2. Log each tool name and its input in the order the model requested them. Compare the log with the transcript to confirm the order matches.
  3. Make one tool throw an exception. Decide whether the error goes back to the model as a tool_result marked as an error, or stops the run. Write down which you chose and why.
Check yourself A loop that never ends means the stop condition is missing or unreachable. A model that answers without calling any tool usually means your tool descriptions are unclear, which is the subject of lesson 0003.

Retrieval check

In a standard tool-use loop, which party executes the tool?

Correct. The model requests a tool and your code executes it, then returns the result as a tool_result.

Not quite. The model only requests the tool. Your application runs it and sends the output back in the next message.

What stop reason tells your loop that the model has nothing left to request?

Correct. end_turn means the model finished its answer. Your loop should return it.

Not quite. Only the model's end_turn signal means it is done. A step counter is your guardrail, and a tool_result is an input to the next call.

Ask the agent: "Walk me through what happens when a tool returns an error, step by step, using the loop above." Next lesson separates workflows from agents, which decides how much of this loop you should hand to the model.