ツール使用の仕組み

このページでは、ツール使用の背後にある概念について説明します。ツールが実行される場所、エージェントループの仕組み、およびツール使用が正しいアプローチである場合についてです。実践的なガイダンスについては、チュートリアルまたは実装ガイドから始めてください。

ツール使用契約

ツール使用は、アプリケーションとモデル間の契約です。利用可能な操作とその入出力の形状を指定します。Claudeは、いつどのように呼び出すかを決定します。モデルは独自に何も実行しません。構造化されたリクエストを発行し、コード（またはAnthropicのサーバー）が操作を実行し、結果が会話に戻ります。

この契約により、モデルはテキストジェネレーターのように動作するのではなく、呼び出す関数のように動作します。古典的なAPI経験を持つエンジニアは、他の型付きインターフェースと同じ方法でツール使用を統合できます。スキーマを定義し、コールバックを処理し、結果を返します。違いは、呼び出し側が言語モデルであり、会話に基づいて呼び出す関数を選択することです。

ツールが実行される場所

ツールが異なる主な軸は、コードが実行される場所です。すべてのツールは3つのカテゴリのいずれかに分類され、カテゴリはアプリケーションが責任を負うものを決定します。

ユーザー定義ツール（クライアント実行）

スキーマを作成し、コードを実行し、結果を返します。これがメインイベントです。ツール使用トラフィックの大部分はユーザー定義ツールがアプリケーション固有のロジックを呼び出しています。

Claudeがいずれかのツールを使用することを決定すると、APIレスポンスにはツール名とJSON引数オブジェクトを含むtool_useブロックが含まれます。アプリケーションはこれらの引数を抽出し、操作を実行し（データベースクエリ、HTTPコール、ファイル書き込み、ツールが実行するもの）、次のリクエストでtool_resultブロックで出力を送り返します。Claudeは実装を見ません。提供したスキーマと返した結果のみを見ます。

Anthropicスキーマツール（クライアント実行）

一般的な操作のいくつか（シェルコマンドの実行、ファイルの編集、ブラウザの制御、スクラッチパッドメモリの管理）については、Anthropicがツールスキーマを公開し、アプリケーションが実行を処理します。このカテゴリのツールはbash、text_editor、computer、およびmemoryです。

実行モデルはユーザー定義ツールと同じです。レスポンスにtool_useブロックが含まれ、コードが操作を実行し、tool_resultを送り返します。Anthropicスキーマツールを使用する理由は、独自の同等のツールを定義する代わりに、これらのスキーマが訓練済みであるためです。Claudeはこれらの正確なツール署名を使用する成功した軌跡で数千回最適化されているため、より確実に呼び出し、同じことを行うカスタムツールよりもエラーからより優雅に回復します。スキーマはモデルがすでに期待しているインターフェースです。

サーバー実行ツール

web_search、web_fetch、code_execution、およびtool_searchについては、Anthropicがコードを実行します。リクエストでツールを有効にすると、サーバーが他のすべてを処理します。レスポンスがあなたに到達する前に、サーバー側ループが操作を実行し、出力をモデルに戻すため、これらのツールに対してtool_resultブロックを構築することはありません。

受け取るレスポンスには、実行内容と結果を示すserver_tool_useブロックが含まれていますが、それを見る時点で実行は既に完了しています。アプリケーションの仕事は、ツールを有効にして最終的な答えを読むことであり、実行ループに参加することではありません。

エージェントループ（クライアントツール）

クライアント実行ツール（ユーザー定義とAnthropicスキーマの両方）は、アプリケーションがループを駆動する必要があります。モデルはコードを実行できないため、すべてのツール呼び出しはラウンドトリップです。モデルが要求し、実行し、報告し、モデルが続行します。

正規の形状はstop_reasonをキーにしたwhileループです。

1. tools配列とユーザーメッセージを含むリクエストを送信します。
2. Claudeはstop_reason: "tool_use"と1つ以上のtool_useブロックで応答します。
3. 各ツールを実行します。出力をtool_resultブロックとしてフォーマットします。
4. 元のメッセージ、アシスタントのレスポンス、およびtool_resultブロックを含むユーザーメッセージを含む新しいリクエストを送信します。
5. stop_reasonが"tool_use"である間、ステップ2から繰り返します。

実際には、これは次のように読みます。stop_reason == "tool_use"である間、ツールを実行して会話を続けます。ループは他の停止理由（"end_turn"、"max_tokens"、"stop_sequence"、または"refusal"）で終了します。これはClaudeが最終的な答えを生成したか、アプリケーションが処理すべき別の理由で停止したことを意味します。

リクエストの構築、並列ツール呼び出しの処理、および結果のフォーマットの仕組みについては、ツール呼び出しの処理を参照してください。

サーバー側ループ

サーバー実行ツールはAnthropicのインフラストラクチャ内で独自のループを実行します。アプリケーションからの単一のリクエストは、レスポンスが返される前に複数のウェブ検索またはコード実行をトリガーする可能性があります。モデルは検索し、結果を読み、再度検索することを決定し、必要なものが得られるまで反復します。すべてアプリケーションが参加することなく。

この内部ループには反復制限があります。モデルがキャップに達したときにまだ反復している場合、レスポンスは"end_turn"の代わりにstop_reason: "pause_turn"で返されます。一時停止されたターンは、作業が完了していないことを意味します。会話を再送信（一時停止されたレスポンスを含む）して、モデルが中断したところから続行できるようにします。継続パターンについては、サーバーツールを参照してください。

ツールを使用する場合（および使用しない場合）

ツール使用は、タスクがテキストだけではモデルが実行できないことを必要とする場合に適しています。

• 副作用のあるアクション。 メールの送信、ファイルの書き込み、レコードの更新。モデルはこれらのアクションを説明できますが、ツールのみが実行できます。
• 新鮮または外部データ。 現在の価格、今日の天気、データベースの内容。訓練データの外側またはシステムに固有のものはすべて、ツールがそれをフェッチする必要があります。
• 構造化された保証された形状の出力。 プローズが情報を含むのではなく、特定のフィールドを持つJSONオブジェクトが必要な場合、ツールスキーマは形状を強制します。
• 既存のシステムへの呼び出し。 データベース、内部API、ファイルシステム。ツール使用は、自然言語リクエストとそれを実現するシステム間のブリッジです。

ツールを使用すべき兆候は、モデル出力から決定を抽出するために正規表現を書いている場合です。その決定はツール呼び出しであるべきでした。自由形式のテキストを解析して構造化された意図を回復することは、構造がスキーマに属すべきであることの兆候です。

ツール使用が適さない場合：

• モデルが訓練だけから答えられる場合。要約、翻訳、一般知識の質問はツールラウンドトリップを必要としません。
• インタラクションが副作用のない1回限りのQ&Aである場合。実行するものがなければ、ツールが実行するものはありません。
• ツール呼び出しのレイテンシーが些細な応答を支配する場合。すべてのツール呼び出しは少なくとも1つの追加ラウンドトリップです。軽量なタスクの場合、オーバーヘッドが作業を超える可能性があります。

アプローチの選択

次のステップ