エージェントツール呼び出し: エージェントに実際に行動させる · 第 2 回 / 全 6 回

レッスン2: ツール呼び出しの完全なラウンドトリップ

学習目標:

1回のツール呼び出しラウンドトリップにおいて、リクエストとレスポンスがそれぞれ持つキーフィールドの名前を言える

tool_use / tool_result コードの一部が正しくマッチしているかどうかを判断できる

同じ並列バッチ内の呼び出し間のデータ依存関係を見抜き、呼び出しを2ラウンドに分割すべきタイミングを知る

「モデルがツールを呼び出す」というフレーズそのものが不正確である理由を説明できる

前提: レッスン1を読み、エージェントにツールが必要な理由を知っている | 前: レッスン1 << | 次: レッスン3 >>

3つのJSONの塊から始める

サポートボットを構築しています。ユーザーが「注文ORD-2026-8842がどこにあるか確認してもらえますか?」と尋ねます。あなたのコードはそのメッセージをツール定義と一緒にモデルに送信します:

JSON

{
  "model": "claude-sonnet-5",
  "tools": [
    {
      "name": "get_order_status",
      "description": "注文の現在のステータスと配送情報を検索します。ユーザーが注文の進捗、配送、または配達予定日について尋ねたときに使用します。",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "description": "注文番号、ORD-2026-0001の形式" }
        },
        "required": ["order_id"]
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "Can you check where my order ORD-2026-8842 is?" }
  ]
}

新しいtoolsフィールドに注目してください。これはメッセージではありません; モデルに手元にどんなツールがあるか、それぞれがどのように見えるか、そしてそれぞれが必要とするパラメータは何かを伝えるマニフェストです。¹ このマニフェストはリクエストごとに送信する必要があります — モデルはそれを「記憶」しないので、あなたのコードは毎回それを含めなければなりません。

モデルはマニフェストを読み、注文ステータスを直接答える代わりに、このようなものを返します:

JSON

{
  "id": "msg_01A2b3C4d5E6f7G8h9",
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    { "type": "text", "text": "Let me check on that order for you." },
    { "type": "tool_use", "id": "toolu_01XYZ89AbCdEfGhIjKlMnOp", "name": "get_order_status", "input": { "order_id": "ORD-2026-8842" } }
  ]
}

ここで2つの新しいことが現れます: stop_reasonが"tool_use"になり、content配列にtype: "tool_use"を持つ新しいブロックがあります。モデルは注文情報を調べていません — 注文システムがどこにあるかさえ知りません。ただ「これらのパラメータでget_order_statusを呼び出してください、そして結果を教えてください」と言っているだけです。

ここからあなたのコードが引き継ぎ、実際に注文システムにクエリを投げ、結果を取得し、その結果を次のリクエストにパックして送り返します:

JSON

{
  "model": "claude-sonnet-5",
  "tools": [ /* 上記と同じ; このラウンドもそれが必要 */ ],
  "messages": [
    { "role": "user", "content": "Can you check where my order ORD-2026-8842 is?" },
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "Let me check on that order for you." },
        { "type": "tool_use", "id": "toolu_01XYZ89AbCdEfGhIjKlMnOp", "name": "get_order_status", "input": { "order_id": "ORD-2026-8842" } }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01XYZ89AbCdEfGhIjKlMnOp",
          "content": "{\"status\":\"in_transit\",\"location\":\"Shanghai transit center\",\"eta\":\"2026-08-27\"}"
        }
      ]
    }
  ]
}

何が追加されたかに注目してください: 前のラウンドのモデルの完全な応答がmessagesに逐語的に戻され、その後に新しいuserメッセージが続きます。そのメッセージはユーザーが入力したテキストを保持していません — モデルがちょうど渡してきたidと正確に一致するtool_use_idを持つtype: "tool_result"ブロックを保持しています。

このリクエストを見て初めて、モデルは最終的に「ご注文は上海トランジットセンターを出発中で、8月27日に配達予定です」のようなことを言います。3つのJSONの塊、3つのロールの切り替え: モデルがリクエストを出し、あなたのコードがそれを実行し、結果がフィードバックされます。これが1回のツール呼び出しラウンドトリップのすべてです。

stop_reasonはシグナルであり、実行記録ではない

初心者が最も頻繁に間違えることがこれです: stop_reason: "tool_use"はツールがすでに呼び出されたことを意味すると思い込むことです。そうではありません。これはモデルがこのメッセージを終えたときに停止した理由に過ぎず、"end_turn"(話し終わった)や"max_tokens"(スペースが足りなくなった)と同じ種類のフィールドで、ただ値が異なるだけです。²

モデルは決してデータベースに触れたり、HTTPリクエストを発行したり、シェルコマンドを自力で実行したりしません。できることは構造化されたリクエストを発行することだけです; 残りの作業はあなたのコードまたはAnthropicのサーバーに委ねられます。³ だからこそツールは「クライアントツール」(ホストアプリケーションが実行する)と「サーバーツール」(Anthropicがあなたの代わりに実行する)に分かれています — 違いは誰がこのステップを実行するかだけで、モデルが自分でそれを実行できるかどうかではありません。²

tool_useブロックの3つのフィールド、どれもオプションではない

そのtool_useブロックを見返してください。必須フィールドは3つだけです:⁴

id: この呼び出しの一意の識別子で、toolu_01XYZ...の形式です。1つの仕事しかありません — 後で結果を送り返すときに照合することです。
name: モデルが選んだツールで、toolsマニフェスト内のツールの1つのnameと正確に一致しなければなりません。
input: この呼び出しのパラメータを保持するオブジェクトで、input_schemaで定義したルールを満たすように形成されています。

これら3つのフィールドをまとめると、モデルが表現できるすべてが揃います:「このidでnameツールを呼び出したい、そしてこれがinputです。」「3回リトライ」のようなロジックを付け加えることはありません — それはホストコードで自分で書きます。モデルがパラメータミスを減らすようにツールインターフェースを設計する方法はレッスン3の領域です; このレッスンはこれら3つのフィールドがどのようにパックされ、読み返されるかだけを気にします。

tool_resultはtool_use_idで照合する

モデルからの1つの応答には複数のtool_useブロックが含まれることがあります。ユーザーが「注文ORD-2026-8842がどこにあるか確認して、それとORD-2026-9001が発送されたかどうかも確認してください」と尋ねたとします。モデルは同じcontent配列に2つのtool_useブロックを入れ、stop_reasonは依然として"tool_use"です。

あなたのコードは両方の注文を調べ、それから同じuserメッセージで、両方の結果をcontent配列に一緒に入れ、各tool_resultが自分のtool_use_idで呼び出しを主張します:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01XYZ89AbCdEfGhIjKlMnOp",
      "content": "{\"status\":\"in_transit\",\"eta\":\"2026-08-27\"}"
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_02QRS45TuVwXyZaBcDeFgH",
      "content": "{\"status\":\"pending\",\"eta\":null}"
    }
  ]
}

ショートカットを取って最初のtool_use_idだけで1ラウンド送信すると、モデルは会話を続けることを拒否します。なぜなら「前のラウンドにはtool_resultを得なかったtool_useブロックがあった」からです — 両方のブロックは次のuserメッセージで一緒に主張される必要があります; それらを2つのリクエストに分割してバッチで送り返すことはできません。⁵ tool_resultブロックにはオプションのis_errorフィールドもあります: ツールが失敗したときにtrueに設定すると、モデルはこの呼び出しが問題に遭遇したことを知ります。⁴

同じバッチ内の呼び出しは互いの結果を見ることができない

バッチ返却ルールが確立されたので、より深い罠があります: 同じバッチ内のtool_useブロック間のデータ依存関係です。

シナリオを切り替えます。送金エージェントが2つのツールで設定されています: read_balance(account_id)は残高を読み、withdraw(account_id, amount)はお金を引き出します。ユーザーが「A001から$100を引き出して、十分あるなら」と言います。1つのレスポンスで、モデルは2つのtool_useブロックを返します: read_balance({"account_id": "A001"})とwithdraw({"account_id": "A001", "amount": 100})。

withdrawのamountを見てください: 100、ユーザーの文の数字から直接コピーされ、残高が十分かどうかとは無関係です。これはモデルが怠惰だからではありません; 選択肢がないのです。このレスポンスを生成する瞬間、read_balanceはまだ「それがやろうとしていること」に過ぎません — その戻り値はまだ存在していないので、withdrawはそれを読むことができません。1つのバッチのtool_useブロック内では、どの呼び出しもそのバッチ内の他の呼び出しの結果を見ることができません。なぜならそれらの結果はその時点でまだ実行されておらず送り返されていないからです。

だからあなた自身が守らなければならない線がこれです: 書き込み操作のパラメータが、理論上は同じバッチ内の読み取り操作の戻り値と等しくあるべきなら、その2つの呼び出しは同じレスポンスに現れるべきではありません。本当に安全なアプローチは、それらを2ラウンドに分割することです: まずread_balanceだけを実行し、実際の残高をtool_resultとして送り返し、モデルが「残高は60しかない」と見たら、withdrawを呼び出すかどうか、いくらで呼び出すかを決めさせます。

実際に機能する3つの戦術:

ツールの説明に前提条件を書く。 withdrawのdescriptionに一行追加します:「read_balanceから返された最新の残高を見た後にのみ呼び出してください。」ツールの説明はモデルが読めるプロンプトの一部そのものなので、モデルが依存関係を自力で把握することを期待するよりもはるかに信頼できます。⁶
disable_parallel_tool_useで並列性をオフにする。リクエストのtool_choiceに{"type": "auto", "disable_parallel_tool_use": true}を設定すると、モデルは1レスポンスにつき最大1つのツールを呼び出します。⁵ 動作をまず1回ずつに絞り、ステップ間の依存関係を頭の中で明確にし、その後でそれを緩めることを検討します。
実行レイヤーでバックストップする。 withdrawを実行するコードに最新の残高を再チェックさせ、条件が満たされていない場合は実行を拒否し、理由をtool_resultエラー情報に書いてモデルに見せます。成功したふりをするのではなく。たとえモデルが今回また2つの呼び出しをバンドルしても、このチェックがリスクを捕捉します。

図として描く

上記のラウンドトリップを描くとこのようになります:

mermaid

sequenceDiagram    participant U as User    participant H as Host app (your code)    participant M as Model
    U->>H: "Check where my order is"    H->>M: Request (tools manifest + messages)    M-->>H: Response (stop_reason: tool_use, tool_use block)    Note over H: Read name / input, run the real query    H->>M: New request (append assistant's tool_use + user's tool_result to messages)    M-->>H: Response (stop_reason: end_turn, final text answer)    H->>U: "Your order is on its way out of the Shanghai transit center..."

sequenceDiagram    participant U as User    participant H as Host app (your code)    participant M as Model
    U->>H: "Check where my order is"    H->>M: Request (tools manifest + messages)    M-->>H: Response (stop_reason: tool_use, tool_use block)    Note over H: Read name / input, run the real query    H->>M: New request (append assistant's tool_use + user's tool_result to messages)    M-->>H: Response (stop_reason: end_turn, final text answer)    H->>U: "Your order is on its way out of the Shanghai transit center..."

この図で最も頻繁に間違えられるステップは「append」矢印です: tool_resultだけを単独で送信し、そのラウンドのモデルの完全なtool_use応答をmessagesに戻すのを忘れることです。すると、モデルは自分が出したリクエストの記録がコンテキストにないまま、どこからともなく現れたツール結果を受け取ることになります — 論理の飛躍やあからさまなエラーが起こりやすくなります。正しい動きは、毎ラウンドのレスポンスを逐語的に履歴に保存することです; messagesは常に長くなるだけで、決してトリミングされません。³

1つのタスクが複数回のラウンドトリップを必要とすることがある

上記の例は1回のツール呼び出しの後に終わりました。実際のシナリオでは、モデルは完了する前に何度も往復することがよくあります。デプロイボットを想像してください。ユーザーが「サービスを再起動して、ログにエラーがないか教えて」と言います:

モデルは最初のラウンドでtool_useを返し、restart_serviceを呼び出します; あなたはそれを実行し、結果を送り返します
モデルは2回目のラウンドで再びtool_useを返し、read_logsを呼び出してエラーをチェックします; あなたはそれを実行し、ログを送り返します
3回目のラウンドで、モデルは最終的にstop_reason: "end_turn"を返し、テキストで要約します

ホスト側のコードロジックは本質的にループです: stop_reasonがまだ"tool_use"である限り、ツールを実行し続け、結果をパックし直し、別のラウンドを送信します; "end_turn"になったら、最終テキストをユーザーに渡します。³

JAVASCRIPT

// toolsはこのレッスンの冒頭のリクエストのtoolsのような、ツール定義のリスト
const messages = [{ role: "user", content: userInput }];

let response = await callModel({ tools, messages });

while (response.stop_reason === "tool_use") {
  const toolUseBlocks = response.content.filter(b => b.type === "tool_use");

  messages.push({ role: "assistant", content: response.content });

  const toolResults = await Promise.all(
    toolUseBlocks.map(async (block) => ({
      type: "tool_result",
      tool_use_id: block.id,
      content: await executeTool(block.name, block.input),
    }))
  );

  messages.push({ role: "user", content: toolResults });

  response = await callModel({ tools, messages });
}

// stop_reasonがend_turnになった; responseは最終テキスト回答を保持

このループには反復回数の固定上限がありません — 1つのユーザーリクエストに対して、モデルは1回だけツールを呼び出すかもしれませんし、十分に集めるまで5回か6回呼び出すかもしれません。レッスン3では、ツールインターフェース設計がラウンドトリップ回数をどのように削減できるかをカバーします; このレッスンでは、ただ覚えておいてください: 複数回のラウンドトリップは例外ではなく標準です。

ホストを交換すると、フィールド名は変わるが、構造は変わらない

OpenAI互換APIを使用している場合、同じメカニズムが異なるラッパーで提供されます: 呼び出しリクエストはchoices[0].message.tool_calls配列に現れ、終了シグナルはstop_reasonではなくfinish_reasonと呼ばれ、その値は"tool_use"ではなく"tool_calls"です。⁷ OpenAIの公式ドキュメントはこのプロセスを次のように説明しています:

"Tool calling is a multi-step conversation between your application and a model via the OpenAI API. When the model calls a function, you must execute it and return the result"

(ツール呼び出しは、OpenAI APIを介したアプリケーションとモデル間の複数ステップの会話です。モデルが関数を呼び出すとき、あなたはそれを実行して結果を返さなければなりません) — モデルが呼び出しリクエストを発行し、アプリケーションがそれを実行して結果を送り返す、まさにClaudeと同じです。⁸

フィールド名はAPIによって変わりますが、骨格 — 「モデルはリクエストを送るだけ、ホストが実行を処理する、結果は識別子を運んで戻ってくる、そして複数ラウンドをループすることがある」 — は普遍的です。

まとめ

モデルは何も直接実行しません。stop_reason: "tool_use"と1つ以上のtool_useブロックを発行するだけです; 実行はホストアプリケーションに留まります
tool_useブロックには3つの必須フィールドしかありません: id(照合用)、name(選ばれたツール)、input(パラメータ)
結果はtool_resultブロックとして戻り、tool_use_idは対応するtool_useブロックのidと正確に一致しなければなりません
1つのレスポンスには複数のtool_useブロックが含まれることがあります; 照合するtool_resultブロックは複数のリクエストに分割するのではなく、同じuserメッセージにパックされなければなりません
同じバッチ内のtool_useブロックは互いの実行結果を見ることができません: 書き込み操作のパラメータが同じバッチ内の読み取り操作の戻り値に依存する場合は、それらを2ラウンドに分割するか、disable_parallel_tool_useで1回ずつに強制します
1つのタスクが複数回のラウンドトリップを必要とすることがあります: ホスト側の実装は本質的にループです — stop_reasonがまだ"tool_use"である間は実行と送り返しを続け、"end_turn"になって初めて完了します

>> レッスン3: 5つの一般的なツールタイプ: 読む、書く、実行する、検索する、呼び出す

Define tools — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools ↩
Tool use with Claude — Overview — https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview ↩ ↩²
How tool use works — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works ↩ ↩² ↩³
Handle tool calls — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls ↩ ↩²
Parallel tool use — Claude API — https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use ↩ ↩²
Writing effective tools for AI agents—using AI agents | Anthropic Engineering — https://www.anthropic.com/engineering/writing-tools-for-agents ↩
Tool Use — LM Studio Docs (OpenAI-compatible API) — https://lmstudio.ai/docs/developer/openai-compat/tools ↩
Function calling — OpenAI API Guides — https://developers.openai.com/api/docs/guides/function-calling ↩

練習

モデルがこのレスポンスを返しました(stop_reasonは"tool_use"):

レベル1: tool_resultリクエストを手書きする

JSON

{
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_01Weather9527", "name": "get_weather", "input": { "city": "Hangzhou" } }
  ]
}

あなたは自分の天気検索関数を呼び出し、結果を得ました: 晴れ、26度。

エディタで、次のリクエストのための完全なmessages配列(元のユーザーメッセージ + このラウンドのアシスタントレスポンス + あなたが構築するtool_resultメッセージ)を書いてください。これらの要件で:

tool_use_idが上記のレスポンスのidと正確に一致する
tool_resultのcontentがプログラムが解析できるテキスト(例えばJSON文字列)である
配列内の3つのメッセージがrole値をuser、assistant、userの順に持つ

完了基準 · ローカルでチェック

`messages`配列に3つのメッセージが含まれ、正しい順序と正しいロールを持つ`tool_result`ブロックの`tool_use_id`が正確に`toolu_01Weather9527`で、作り上げた文字列ではない`tool_result`の`content`が実際の天気データを運び、後のコードが解析できるフォーマットである

以下のコードは「ツールを呼び出し、結果を送り返す」ロジックを実装しようとしていますが、3つのことがモデルが正しい結果を得るのを妨げたり、会話をエラーにしたりします。問題を見つけて、修正版を書いてください。(モデルのレスポンスには1つのtool_useブロックしかないと仮定します。)

レベル2: ラウンドトリップコードの3つのバグを見つける

JAVASCRIPT

async function handleTurn(userMessage, tools) {
  const messages = [{ role: "user", content: userMessage }];
  const response = await callModel({ tools, messages });

  if (response.stop_reason === "tool_use") {
    const toolBlock = response.content.find(b => b.type === "tool_use");
    const result = await executeTool(toolBlock.name, toolBlock.input);

    messages.push({
      role: "user",
      content: [{ type: "tool_result", tool_use_id: toolBlock.name, content: result }],
    });

    const finalResponse = await callModel({ messages });
    return finalResponse;
  }

  return response;
}

完了基準 · ローカルでチェック

3つの具体的な問題を特定して説明し、それぞれコード内の正確な行を指している修正されたコードがモデルの`response.content`を`messages`に追加している修正されたコードが`tool_use_id`に`toolBlock.name`ではなく`toolBlock.id`を使用している修正された2回目の`callModel`呼び出しに`tools`が含まれている

レッスン2: ツール呼び出しの完全なラウンドトリップ

3つのJSONの塊から始める

stop_reasonはシグナルであり、実行記録ではない

tool_useブロックの3つのフィールド、どれもオプションではない

tool_resultはtool_use_idで照合する

同じバッチ内の呼び出しは互いの結果を見ることができない

図として描く

1つのタスクが複数回のラウンドトリップを必要とすることがある

ホストを交換すると、フィールド名は変わるが、構造は変わらない

まとめ

Footnotes

練習

モデルがこのレスポンスを返しました(stop_reasonは"tool_use"):