Messagesツール

ツール使用の仕組み

Copy page



ツール使用のループ、ツールが実行される場所、そして散文の代わりにツールを使用するタイミングを理解します。

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

ツール使用の契約

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

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

ツールが実行される場所

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

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

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

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

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

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

実行モデルはユーザー定義ツールと同一です。レスポンスには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である場合。実行するものがなければ、ツールが行うことは何もありません。
• ツール呼び出しのレイテンシが些細なレスポンスを支配する場合。すべてのツール呼び出しは少なくとも1つの追加のラウンドトリップです。軽量なタスクでは、オーバーヘッドが作業を上回る可能性があります。

アプローチ間の選択

次のステップ