ツール使用の仕組み

このページでは、ツール使用の背後にある概念、つまりツールがどこで実行されるか、エージェントループがどのように機能するか、そしてツール使用が適切なアプローチとなるのはどのような場合かについて説明します。実践的なガイダンスについては、チュートリアルまたは実装ガイドから始めてください。



ツール使用の契約

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

この契約により、モデルはテキスト生成器というよりも、呼び出し可能な関数のように振る舞います。従来のAPI経験を持つエンジニアは、他の型付きインターフェースと同じ方法でツール使用を統合できます。つまり、スキーマを定義し、コールバックを処理し、結果を返すという流れです。違いは、呼び出し側が言語モデルであり、会話に基づいてどの関数を呼び出すかを選択している点です。



ツールが実行される場所

ツールが異なる主な軸は、コードがどこで実行されるかです。すべてのツールは3つのカテゴリのいずれかに分類され、そのカテゴリによってアプリケーションが担う責任が決まります。



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

スキーマを記述し、コードを実行し、結果を返すのはあなたです。これが主要なケースです。ツール使用トラフィックの大部分は、アプリケーション固有のロジックを呼び出すユーザー定義ツールです。

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



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

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

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



サーバー実行ツール

web_search、web_fetch、code_execution、およびtool_searchについては、Anthropicがコードを実行します。リクエストでツールを有効にすると、サーバーがその他すべてを処理します。これらのツールに対してtool_resultブロックを構築することはありません。ターンがサーバーツールのみを呼び出す場合、サーバー側のループが操作を実行し、レスポンスがあなたに届く前に出力をモデルにフィードバックします。ただし、ループが完了前に停止する場合（最も多いのは一時停止）は例外です。

受け取るレスポンスには、何が実行され何が返されたかを示すserver_tool_useブロックが含まれます。一般的なケースでは、それらを見る時点で実行はすでに完了しており、アプリケーションの役割は実行ループに参加することではなく、ツールを有効にして最終的な回答を読み取ることです。主な例外は、一時停止したループ（pause_turn）と、クライアントツールも呼び出すターンです。



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

クライアント実行ツール（ユーザー定義と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"で返されます。一時停止したターンは作業が完了していないことを意味します。会話（一時停止したレスポンスを含む）を再送信して、モデルが中断したところから続行できるようにします。継続パターンについては、サーバーツールを参照してください。

また、Claudeが同じ並列ツール呼び出しグループ内でサーバーツールとクライアントツールを呼び出す場合、ループはサーバーツールが実行される前に制御をあなたに返します。その場合、レスポンスはstop_reason: "tool_use"と、まだ結果ブロックがないserver_tool_useブロックとともに返されます。APIは、クライアントツールの結果を返した後にそれを実行します。正確な契約については、停止理由とフォールバックを参照してください。



ツールを使用すべき場合（および使用すべきでない場合）

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

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

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

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

• モデルが訓練データだけで回答できる場合。要約、翻訳、一般知識の質問にはツールの往復処理は必要ありません。
• インタラクションが副作用のない単発のQ&Aである場合。実行するものがなければ、ツールが行うことは何もありません。
• ツール呼び出しの「latency」（レイテンシ）が些細なレスポンスを支配してしまう場合。すべてのツール呼び出しは少なくとも1回の追加往復処理です。軽量なタスクでは、オーバーヘッドが作業を上回る可能性があります。



アプローチの選択



次のステップ