Building a Multi-Turn Tool Use Loop

Loop tool_use and tool_result exchanges until Claude returns an end_turn.

Summary

The Messages API is stateless - each call is a fresh request with no memory of prior turns except what you send in messages. When Claude decides a tool is needed, it doesn't run the tool itself. It stops generating, returns a tool_use block describing what it wants to call, and hands control back to your code.

Your job is to execute the tool, package the result as a tool_result block, and send the whole conversation back. Claude then either asks for another tool call or produces its final answer. Many real tasks (looking something up, then acting on what was found, then verifying the result) take several such round trips before Claude is done.

This back-and-forth is the "agentic loop": call the API, inspect stop_reason, execute tools if asked, append results, call again. It ends when response.stop_reason == "end_turn". Get the loop wrong - drop content, forget a stop_reason, or skip the iteration guard - and you get either a crash on the next call or an agent that spins forever.

This page builds that loop by hand in Python with the official anthropic SDK, then shows the higher-level Tool Runner shortcut once the manual version is understood.

Recipe

Quick-reference recipe card - copy-paste ready.

import anthropic
 
client = anthropic.Anthropic()
messages = [{"role": "user", "content": user_input}]
 
while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
 
    if response.stop_reason == "end_turn":
        break
 
    if response.stop_reason == "pause_turn":
        messages.append({"role": "assistant", "content": response.content})
        continue
 
    tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
    messages.append({"role": "assistant", "content": response.content})
 
    tool_results = []
    for block in tool_use_blocks:
        result = execute_tool(block.name, block.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": result,
        })
    messages.append({"role": "user", "content": tool_results})
 
final_text = "".join(b.text for b in response.content if b.type == "text")

When to reach for this:

• Claude needs to call one or more tools before it can give a final answer (lookups, calculations, side effects).
• The task may require multiple dependent steps - e.g. search, then fetch a specific record, then summarize.
• You're building an agent that runs unattended and must keep going until Claude is actually finished, not just after one tool call.
• You want full control over how tools execute (concurrency, retries, sandboxing) rather than delegating that to a framework.

Working Example

import json
import anthropic
 
client = anthropic.Anthropic()
 
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. 'Denver'"},
            },
            "required": ["city"],
        },
    },
    {
        "name": "convert_temperature",
        "description": "Convert a temperature between Celsius and Fahrenheit.",
        "input_schema": {
            "type": "object",
            "properties": {
                "value": {"type": "number"},
                "from_unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["value", "from_unit"],
        },
    },
]
 
 
def get_weather(city: str) -> str:
    # Stand-in for a real weather API call.
    fake_data = {"Denver": 8.0, "Miami": 29.0}
    celsius = fake_data.get(city, 20.0)
    return json.dumps({"city": city, "celsius": celsius})
 
 
def convert_temperature(value: float, from_unit: str) -> str:
    if from_unit == "celsius":
        result = value * 9 / 5 + 32
        return json.dumps({"fahrenheit": round(result, 1)})
    result = (value - 32) * 5 / 9
    return json.dumps({"celsius": round(result, 1)})
 
 
def execute_tool(name: str, tool_input: dict) -> str:
    if name == "get_weather":
        return get_weather(tool_input["city"])
    if name == "convert_temperature":
        return convert_temperature(tool_input["value"], tool_input["from_unit"])
    return json.dumps({"error": f"unknown tool: {name}"})
 
 
def run_agent(user_input: str, max_iterations: int = 12) -> str:
    messages = [{"role": "user", "content": user_input}]
    response = None
 
    for _ in range(max_iterations):
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
 
        if response.stop_reason == "end_turn":
            break
 
        if response.stop_reason == "pause_turn":
            messages.append({"role": "assistant", "content": response.content})
            continue
 
        if response.stop_reason == "max_tokens":
            raise RuntimeError("Response truncated at max_tokens; increase the limit.")
 
        if response.stop_reason == "refusal":
            raise RuntimeError(f"Claude declined the request: {response.stop_reason}")
 
        tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
        messages.append({"role": "assistant", "content": response.content})
 
        if not tool_use_blocks:
            # No tool calls and no end_turn - nothing left to do safely.
            break
 
        tool_results = []
        for block in tool_use_blocks:
            result = execute_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
        messages.append({"role": "user", "content": tool_results})
    else:
        raise RuntimeError("Exceeded max_iterations without reaching end_turn.")
 
    return "".join(b.text for b in response.content if b.type == "text")
 
 
if __name__ == "__main__":
    answer = run_agent(
        "What's the weather in Denver right now, in Fahrenheit?"
    )
    print(answer)

What this demonstrates:

• A bounded loop (for _ in range(max_iterations)) that always terminates, with a RuntimeError raised via the for...else clause if Claude never reaches end_turn.
• The full response.content - not just extracted text - appended as the assistant turn so the tool_use blocks Claude emitted are visible on the next call.
• A tool_use_id-matched tool_result for every tool_use block, batched into a single user message per turn (required when Claude requests parallel tool calls).
• Explicit handling for pause_turn, max_tokens, and refusal alongside the two "keep looping" paths (tool_use and end_turn).
• A single execute_tool dispatcher that keeps tool routing in one place instead of scattered if/elif chains near the API call.

Deep Dive

How It Works

• Each client.messages.create() call is independent. The API has no session state - everything Claude "remembers" is whatever you included in messages on that call.
• When Claude wants a tool, it stops generating output and returns content blocks - some text (rare mid-loop, but possible), one or more tool_use blocks, and a stop_reason.
• Your code executes the requested tool(s) locally (or via a connector) and reports back with tool_result blocks, matched to the originating call via tool_use_id.
• The next messages.create() call re-sends the entire growing conversation - original user turn, Claude's assistant turn with tool_use blocks, your user turn with tool_result blocks - so Claude has full context to continue or conclude.
• The loop is not "call tool, get answer" one-shot; Claude may chain several tool calls (look something up, then act on it, then verify) before it has enough information to answer, which is why looping - not a single request/response - is the right mental model.

stop_reason Values and What To Do

Message Shape at Each Step

# After turn 1 (Claude requests a tool call):
messages == [
    {"role": "user", "content": "What's the weather in Denver?"},
    {"role": "assistant", "content": [ToolUseBlock(id="toolu_01...", name="get_weather", input={"city": "Denver"})]},
]
 
# After you execute the tool and append the result:
messages == [
    {"role": "user", "content": "What's the weather in Denver?"},
    {"role": "assistant", "content": [ToolUseBlock(...)]},
    {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_01...", "content": "..."}]},
]

Python Notes

# Prefer a dispatch dict over long if/elif chains as the tool count grows:
TOOL_HANDLERS = {
    "get_weather": lambda i: get_weather(i["city"]),
    "convert_temperature": lambda i: convert_temperature(i["value"], i["from_unit"]),
}
 
def execute_tool(name: str, tool_input: dict) -> str:
    handler = TOOL_HANDLERS.get(name)
    if handler is None:
        return json.dumps({"error": f"unknown tool: {name}"})
    try:
        return handler(tool_input)
    except Exception as exc:
        # Report failures back to Claude as data, not a crashed process.
        return json.dumps({"error": str(exc)})

Parameters & Return Values

Gotchas

• Appending only the extracted text, not response.content. If you push {"role": "assistant", "content": final_text} instead of the raw content blocks, Claude's next request loses the tool_use blocks it needs to see, and the API will reject the follow-up tool_result message because it doesn't match a preceding tool call. Fix: always append response.content unmodified as the assistant turn.
• No iteration cap. A loop that only exits on end_turn will spin forever if a tool keeps returning ambiguous data or the model gets stuck re-requesting the same call. Fix: wrap the loop in for _ in range(max_iterations) (10-15 is a reasonable default) and raise/log a timeout when it's exhausted.
• Treating pause_turn like a normal tool_use turn. Sending a fresh "Continue" user message after pause_turn (instead of resending the paused assistant turn as-is) confuses the resumed server-side tool state. Fix: append response.content and call the API again immediately, with no extra user message.
• Mismatched or missing tool_use_id. Every tool_result must reference the id of the tool_use block it answers; skipping a block (e.g. when Claude requests two parallel calls but you only handle one) leaves the API waiting on an unresolved tool call. Fix: iterate over all tool_use blocks in the response and produce exactly one tool_result per block, batched into a single user message.
• Letting a tool exception crash the loop. An uncaught exception inside execute_tool kills the whole request instead of giving Claude a chance to recover (e.g. retry with different arguments). Fix: catch exceptions per-tool and return them as tool_result content (e.g. {"error": "..."}) so Claude can react.
• Ignoring max_tokens as a stop reason. Treating max_tokens like end_turn silently ships a truncated answer to the user. Fix: check for it explicitly and either raise max_tokens on the next call or switch to streaming.
• Blindly retrying on refusal. Looping the same prompt again after a safety refusal wastes calls and won't change the outcome. Fix: inspect stop_details, adjust the request or escalate to a human instead of retrying verbatim.

Alternatives

FAQs

Related

• Handling tool_use Requests and Returning tool_result Blocks - the single-turn mechanics this loop repeats on every iteration.
• Executing Parallel Tool Calls in a Single Turn - how to handle multiple tool_use blocks returned in one turn.
• Tool Use Basics - the foundational concepts (tools, tool_choice, schemas) this page builds on.
• Best Practices - broader guidance for reliable, production-ready tool use.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.