D1 · Agentic Architecture › Cluster 2 · Stop Reasons

2.2 · Handling tool_use

The continue path that drives every agent

CONCEPT tool_use is the "keep looping" signal

When stop_reason == "tool_use", the model has decided it needs a tool before it can finish. The response's content is a list of blocks: some may be text (the model thinking aloud), and one or more are tool_use blocks — each with an id, a name, and an input dict. Your job is a fixed four-step cycle.

StepActionDetail
1Append the WHOLE assistant turnmessages.append({"role":"assistant","content": resp.content}) — the entire content list, text blocks included.
2Extract every tool_use blockThere can be more than one in a single turn (parallel tool calls).
3Run each tool; build a tool_resulttool_result.tool_use_id MUST match the block's id.
4Send results back in a user turnAll tool_result blocks go in one user message; call the API again.
🔑 Two hard rules from Cluster 1 apply here: append the whole response.content (not just the tool_use block), and tool_result.tool_use_id must equal the tool_use.id. A mismatch or a dropped block is a 400-class error.

DIAGRAM The tool_use cycle

flowchart TD A([stop_reason == tool_use]) --> B["append WHOLE assistant turn
(role: assistant, content: resp.content)"] B --> C{"iterate content blocks"} C -->|text block| D["(optional) log / show thinking"] C -->|tool_use block| E["run tool(name, input)
→ result"] E --> F["build tool_result
tool_use_id = block.id"] D --> G F --> G["collect all tool_result blocks"] G --> H["append ONE user turn
(role: user, content: [tool_result, ...])"] H --> I([call messages.create again → loop]) classDef loop fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef act fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; class A,I loop; class E,F act;

CODE The tool_use branch (handles multiple calls)

Note the loop over all blocks — a single turn may contain several tool_use blocks, and every one needs a matching tool_result.

def handle_tool_use(resp, messages):
    # 1) Append the WHOLE assistant turn (text + tool_use blocks).
    messages.append({"role": "assistant", "content": resp.content})

    # 2) + 3) Run EVERY tool_use block; collect results.
    results = []
    for block in resp.content:
        if block.type != "tool_use":
            continue                      # skip text/thinking blocks
        output = run_tool(block.name, block.input)   # your dispatch
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,     # MUST match the tool_use id
            "content": output,
        })

    # 4) Send ALL results back in ONE user turn, then loop.
    messages.append({"role": "user", "content": results})
    return messages                    # caller re-invokes messages.create()
Because you append the assistant turn and the user tool_result turn, the next stateless request carries the full context: the model sees what it asked for and what came back.

TRADE-OFFS One tool per turn vs. parallel tool_use

✅ Handle all blocks in a turn

  • Model can request several tools at once → fewer round-trips
  • Lower latency for independent lookups
  • Correct: every tool_use gets its tool_result

⚠️ Only handling the first block

  • Leaves tool_use blocks without results → API error next turn
  • Silently drops work the model asked for
  • Breaks as soon as the model parallelizes

EXAM TRAPS

Trap: Appending only the tool_use block instead of the whole resp.content. → You lose accompanying text blocks and can desync the turn. Append the entire content list.
Trap: Putting tool_result in an assistant turn. → Tool results are the user's turn (you are speaking on the environment's behalf). Role must be user.
Trap: Assuming exactly one tool call per turn. → A turn can contain multiple tool_use blocks. Loop over all of them; each needs a matching tool_result.
Trap: Mismatched IDs. → tool_result.tool_use_id must equal the originating tool_use.id. Copy it verbatim; don't regenerate.

PRACTICE

Q1 · The model returns a text block AND two tool_use blocks. What goes back to the API?

First append the whole assistant turn (text + both tool_use blocks). Then run both tools and append one user turn containing two tool_result blocks, each with a tool_use_id matching its tool_use. Then call again.

Q2 · Your next request fails with an error about an unresolved tool call. Likely cause?

You handled only the first tool_use block and left another without a matching tool_result, or an ID didn't match. The API requires every tool_use in the prior assistant turn to be answered.

Q3 · After appending tool_result, do you set stop_reason yourself to keep looping?

No — you never set stop_reason. You just call messages.create again with the updated messages; the next response carries its own stop_reason (possibly end_turn now, or another tool_use).