Główna pętla

A single call to Claude returns one response. But real agents need to act: look something up, run a tool, then keep going. The agentic loop is the engine that makes this happen.

The model itself is stateless — it keeps no memory between calls. Your code holds the conversation and decides when to keep going and when to stop. Master this loop and you have mastered the foundation every Claude agent is built on.

In this lesson you will trace one full turn: request → stop_reason → tool execution → history append, and repeat.

Because the model keeps no state, you must send the entire conversation history on every request. The key fields of a Messages API request:

• model — which Claude model
• max_tokens — output ceiling
• system — the persistent instructions
• messages — the full history (user, assistant, tool results)
• tools — tool definitions the model may call
• tool_choice — auto, any, or a forced tool

If you forget to append a turn to messages, the model simply won't see it. The history is the agent's memory.

After every response, the first thing you check is stop_reason. It tells you exactly why the model stopped and what to do next:

• end_turn — the model is done. Stop the loop.
• tool_use — the model wants a tool run. Execute it, append the result, call again.
• max_tokens — output was truncated. Raise the limit or stream.
• stop_sequence — a custom stop string was hit.

The stop_reason is your loop's control signal. Everything the agent does next is driven by this single field — never by reading the text.

When stop_reason is tool_use, the response content contains one or more tool_use blocks. Each block carries:

• id — a unique id you must echo back
• name — which tool to run
• input — the arguments (already parsed for you by the SDK)

The model has decided what to call and with what. It has not run anything — Claude never executes your tools. Running them is your code's job. The model only requests; your harness acts.

You map the tool name to a real function and run it with the model's input. This runs entirely on your side — your database, your APIs, your business logic.

This is also where guarantees live. The model decides which tool to call, but deterministic code decides whether it is allowed to run — identity checks, spend limits, permission gates. Decisions are model-driven; hard guarantees stay in code.

Now you grow the history. Two appends happen, in order:

• First, append the assistant's full response.content — this preserves the tool_use blocks.
• Then append a user message containing a tool_result block for each call, each with the matching tool_use_id.

Append the whole content, not just the text — dropping the tool_use blocks breaks the pairing and the next call will fail.

With the tool result now in the history, you call the API again. The model sees the result and continues — maybe it answers, maybe it calls another tool. You inspect stop_reason again and do the same thing.

This is the whole loop: request → inspect stop_reason → if tool_use, run tools and append results → repeat until end_turn. The cycle continues for as many tool calls as the task needs, then ends naturally when the model returns end_turn.

Here is the single most important rule of the loop: terminate on stop_reason, never by parsing the text for words like "done" or "finished".

Reading the visible text to decide when to stop is a classic anti-pattern. The model might say "I'm done!" mid-thought, or never say it at all, or say it inside a sentence that isn't actually the end. The stop_reason is a structured, reliable signal; free-text is not.

If you find yourself writing if "done" in response_text, stop — you are building on sand.

A robust loop usually adds a maximum iteration count — but understand its role. The cap is a safety net to prevent a runaway loop, not the primary stop mechanism.

The primary, expected way the loop ends is end_turn. The cap only fires in abnormal situations. Treating an arbitrary iteration cap as the main way to stop is an anti-pattern: it cuts off legitimate work and hides the fact that the model never naturally concluded.

The core loop divides responsibility cleanly:

• The model decides what to do — which tool, which arguments, when the task is complete (end_turn).
• Your code enforces guarantees — what is allowed to run, spend limits, identity verification, and the safety-net cap.

Reserve hard-coded control for things that must be guaranteed (a refund over a limit, a destructive action). Let the model drive the flexible, decision-heavy parts. Over-constraining with rigid code makes a brittle agent; under-constraining critical actions makes an unsafe one.

Here is the entire core loop in one place. Read it top to bottom — every concept from this lesson is in it: full history each turn, inspect stop_reason, execute tools, append both the assistant turn and the tool results, and exit on end_turn with an iteration cap as a backstop.

This same skeleton scales from a one-tool helper to a complex multi-step agent. The loop never changes; only the tools and the task do.

An architect is reviewing a teammate's agent. The loop reads each response's text and breaks when it contains the phrase "task complete". It also has a hard cap of 3 iterations as the main way it ends. Which change best fixes the design?

You now own the foundation of every Claude agent:

• Stateless model — send the full messages history every turn; the history is the memory.
• Inspect stop_reason first — end_turn stops, tool_use means run a tool, max_tokens means truncated.
• Claude requests, your code executes — map name + input to a function and run it.
• Append both turns — the assistant's full content, then a tool_result per call with the matching tool_use_id.
• Terminate on stop_reason, never on text; the iteration cap is a safety net, not the brake.
• Model decides, code guarantees.

Internalize this cycle — every advanced pattern in the certification builds directly on it.