The core loop, built properly

Errors from the API itself

Separate from what the model says, the HTTP call can fail. When a phone call fails, a busy signal means try again later, and a wrong number means check the number. Sort failures the same way, by whether retrying could help:

The official SDKs already retry 429 and 5xx a couple of times with exponential backoff. A harness adds a cap on total attempts, and logs each retry. Never retry a 400 in a loop: the same bad request fails the same way, and an agent stuck doing that burns time and money.

Append-only transcripts

Treat the message list like a ship's log written in pen. Add each reply and each batch of results to the end, and don't edit or reorder what's already there. That's what append-only means.

There are two reasons. Prompt caching reuses an unchanged prefix, so edits near the start make every later call pay full price. And models that think keep signed reasoning blocks in their replies; changing earlier turns can invalidate them. When the context does need to shrink, use the deliberate tools in the context lesson.

A turn budget

You'd give a contractor a limit on hours, so a small job can't run on forever. A loop with no limit can run forever too: the model keeps calling tools without converging. Count model calls and stop at a budget (often 20 to 100 for coding agents). When the budget runs out, return a clear status, not an exception, so the caller can report it or ask the user to continue.

statuses = [529, 429, 200]
delay, waits = 1, []
for s in statuses:
    if s in (429, 500, 529):
        waits.append(delay)
        delay *= 2
print(waits)

def next_action(reply):
    reason = reply["stop_reason"]
    if reason in ("end_turn", "stop_sequence"):
        return "finish"
    if reason == "tool_use":
        return "run_tools"
    if reason == "pause_turn":
        return "continue"
    if reason == "max_tokens":
        return "retry_bigger"
    if reason == "refusal":
        return "refused"
    return "unknown"

for r in ["end_turn", "tool_use", "pause_turn", "max_tokens", "refusal", "something_new"]:
    print(r, "->", next_action({"stop_reason": r}))

Trying it on the API

Here is the same shape against the real endpoint. Without an API key, the academy's practice server answers, in the real response format. It always uses the first tool, so it shows the loop's shape rather than real reasoning.

import requests

TOOLS = [{"name": "get_time", "description": "Current time in a city.",
          "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}]

def call(messages, max_tokens=800):
    r = requests.post("https://api.anthropic.com/v1/messages",
        headers={"x-api-key": "added-by-the-academy-server", "anthropic-version": "2026-10-21"},
        json={"model": "claude-opus-5-5", "max_tokens": max_tokens, "tools": TOOLS, "messages": messages},
        timeout=60)
    r.raise_for_status()
    return r.json()

messages = [{"role": "user", "content": "What time is it in Lisbon?"}]
for turn in range(4):
    reply = call(messages)
    messages.append({"role": "assistant", "content": reply["content"]})
    print(turn, reply["stop_reason"])
    if reply["stop_reason"] != "tool_use":
        break
    results = [{"type": "tool_result", "tool_use_id": b["id"], "content": "14:05"}
               for b in reply["content"] if b["type"] == "tool_use"]
    messages.append({"role": "user", "content": results})
print([b["text"] for b in reply["content"] if b["type"] == "text"][-1][:120])

Stop reasons that catch people out

Don't run a tool from a reply cut off at max_tokens. Its input may be half-written JSON. Parsing might fail, or worse, it might succeed with a truncated value. If the reply ran out of room, raise the limit or ask for less, then try again.

Only end_turn means finished. refusal and max_tokens also end a reply, and neither means success. Give each one its own branch, as in this lesson's example, and an unknown stop reason should stop the loop with a clear message.

Parallel results go in one message. Sending each tool's result as its own user message breaks the alternation that the API expects, and it teaches the model to stop asking for parallel calls.

Don't retry a 400. It failed because of the request, and it'll fail the same way next time. Log it and stop.