Claude Platform Docs
メッセージツール

ツール使用の仕組み

ツール使用のループ、ツールが実行される場所、そして文章ではなくツールを使用すべき場面について理解します。

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

ツール使用の契約

「tool use」(ツール使用)は、アプリケーションとモデルの間の契約です。利用可能な操作と、その入力および出力の形式をあなたが指定し、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、ファイルシステム。ツール使用は、自然言語のリクエストとそれを満たすシステムの間の橋渡しです。

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

ツール使用が適さないのは次の場合です。

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

アプローチ間の選択

アプローチ使用するタイミング期待できること詳細
ユーザー定義クライアントツールカスタムビジネスロジック、内部API、独自データ実行とエージェント型ループを処理しますツールの定義
Anthropicスキーマクライアントツール標準的な開発操作(bash、ファイル編集、デスクトップおよびブラウザ制御)実行を処理します。スキーマが訓練に組み込まれているため、Claudeはツールを信頼性高く呼び出しますツールリファレンス
サーバー実行ツールウェブ検索、コードサンドボックス、ウェブフェッチAnthropicが実行を処理します。結果を生成するのではなく読みますサーバーツール

次のステップ

単一のツール呼び出しから本番環境まで、エージェントを段階的に構築します。

スキーマ仕様、説明、およびtool_choice。

Anthropicが提供するツールのディレクトリ。

このページは役に立ちましたか?