ツール使用の実装方法
モデルの選択
一般的に、複雑なツールや曖昧なクエリには Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5 または Claude Opus 3 を使用してください。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。
単純なツールには Claude Haiku 3.5 または Claude Haiku 3 を使用しますが、不足しているパラメータを推測する可能性があることに注意してください。
Claude Sonnet 3.7 でツール使用と拡張思考を使用する場合は、詳細についてはこちらのガイドを参照してください。
クライアントツールの指定
クライアントツール(Anthropic定義とユーザー定義の両方)は、APIリクエストのtools
トップレベルパラメータで指定されます。各ツール定義には以下が含まれます:
パラメータ | 説明 |
---|---|
name | ツールの名前。正規表現 ^[a-zA-Z0-9_-]{1,64}$ に一致する必要があります。 |
description | ツールの機能、使用タイミング、動作に関する詳細なプレーンテキストの説明。 |
input_schema | ツールに必要なパラメータを定義するJSON Schemaオブジェクト。 |
ツール使用システムプロンプト
tools
パラメータを指定してAnthropic APIを呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトが構築されます。構築されたプロンプトは、指定されたツールを使用するようモデルに指示し、ツールが適切に動作するために必要なコンテキストを提供するように設計されています:
ツール定義のベストプラクティス
ツールを使用する際にClaudeから最高のパフォーマンスを引き出すには、以下のガイドラインに従ってください:
- 非常に詳細な説明を提供する。 これはツールのパフォーマンスにおいて最も重要な要素です。説明には以下のすべての詳細を含める必要があります:
- ツールの機能
- 使用すべきタイミング(および使用すべきでないタイミング)
- 各パラメータの意味とツールの動作への影響
- ツール名が不明確な場合など、ツールが返さない情報などの重要な注意点や制限事項。Claudeにツールについてより多くのコンテキストを提供するほど、いつどのようにツールを使用するかの判断が向上します。ツールの説明は少なくとも3〜4文、複雑なツールの場合はそれ以上を目指してください。
- 例よりも説明を優先する。 ツールの説明や付随するプロンプトにツールの使用例を含めることはできますが、これはツールの目的とパラメータに関する明確で包括的な説明を持つことよりも重要ではありません。説明を十分に詳細にした後にのみ例を追加してください。
良い説明では、ツールの機能、使用タイミング、返すデータ、およびticker
パラメータの意味が明確に説明されています。不十分な説明は簡潔すぎて、ツールの動作や使用法に関する多くの疑問をClaudeに残しています。
Claudeの出力の制御
ツール使用の強制
場合によっては、Claudeがツールを使わずに回答できると判断した場合でも、ユーザーの質問に答えるために特定のツールを使用させたいことがあります。これは、tool_choice
フィールドでツールを指定することで実現できます:
tool_choiceパラメータを使用する場合、4つの選択肢があります:
auto
はClaudeが提供されたツールを呼び出すかどうかを決定できるようにします。これはtools
が提供されている場合のデフォルト値です。any
はClaudeに提供されたツールのいずれかを使用する必要があることを伝えますが、特定のツールを強制しません。tool
は特定のツールを常に使用するようClaudeに強制します。none
はClaudeがツールを使用することを防ぎます。これはtools
が提供されていない場合のデフォルト値です。
この図は各オプションの動作を示しています:
tool_choice
がany
またはtool
の場合、ツールを使用するようにアシスタントメッセージを事前に入力することに注意してください。これは、明示的に求められた場合でも、モデルがtool_use
コンテンツブロックの前に思考の連鎖text
コンテンツブロックを出力しないことを意味します。
私たちのテストでは、これによってパフォーマンスが低下することはないはずです。特定のツールを使用するよう要求しながらも思考の連鎖(特にOpusの場合)を維持したい場合は、tool_choice
に{"type": "auto"}
(デフォルト)を使用し、user
メッセージに明示的な指示を追加できます。例:What's the weather like in London? Use the get_weather tool in your response.
JSON出力
ツールは必ずしもクライアント関数である必要はありません — 提供されたスキーマに従うJSON出力をモデルに返させたい場合はいつでもツールを使用できます。例えば、特定のスキーマを持つrecord_summary
ツールを使用することができます。完全な動作例については、ツール使用の例を参照してください。
思考の連鎖
ツールを使用する際、Claudeはしばしば「思考の連鎖」、つまり問題を分解してどのツールを使用するかを決定するために使用するステップバイステップの推論を示します。Claude Opus 3モデルはtool_choice
がauto
に設定されている場合にこれを行います(これはデフォルト値です。ツール使用の強制を参照)、SonnetとHaikuはプロンプトによってこれを行うよう促すことができます。
例えば、「What’s the weather like in San Francisco right now, and what time is it there?」というプロンプトに対して、Claudeは次のように応答するかもしれません:
この思考の連鎖はClaudeの推論プロセスに洞察を与え、予期しない動作のデバッグに役立ちます。
Claude Sonnet 3モデルでは、思考の連鎖はデフォルトでは一般的ではありませんが、ユーザーメッセージやシステムプロンプトに"Before answering, explain your reasoning step-by-step in tags."
のような内容を追加することで、Claudeに推論を示すよう促すことができます。
<thinking>
タグはClaudeが思考の連鎖を示すために使用する一般的な規約ですが、正確な形式(このXMLタグの名前など)は時間とともに変化する可能性があることに注意することが重要です。コードは思考の連鎖を他のアシスタント生成テキストと同様に扱い、<thinking>
タグの存在や特定の書式に依存すべきではありません。
並列ツール使用
デフォルトでは、Claudeはユーザークエリに回答するために複数のツールを使用することがあります。以下の方法でこの動作を無効にできます:
- tool_choiceタイプが
auto
の場合にdisable_parallel_tool_use=true
を設定すると、Claudeが最大1つのツールを使用することを保証します - tool_choiceタイプが
any
またはtool
の場合にdisable_parallel_tool_use=true
を設定すると、Claudeが正確に1つのツールを使用することを保証します
Claude Sonnet 3.7での並列ツール使用
Claude Sonnet 3.7は、disable_parallel_tool_use
を設定していない場合でも、レスポンスで並列ツール呼び出しを行う可能性が低いかもしれません。この問題を回避するために、トークン効率の良いツール使用を有効にすることをお勧めします。これにより、Claudeが並列ツールを使用するよう促すのに役立ちます。このベータ機能はレイテンシを削減し、出力トークンを平均14%節約します。
トークン効率の良いツール使用ベータにオプトインしたくない場合は、「バッチツール」を導入することもできます。これは他のツールへの呼び出しを同時にラップするメタツールとして機能します。このツールが存在する場合、モデルはそれを使用して複数のツールを同時に並列で呼び出すことがわかっています。
この回避策の使用方法については、クックブックのこの例を参照してください。
tool_useとtool_resultコンテンツブロックの処理
Claudeの応答は、クライアントツールまたはサーバーツールを使用するかどうかによって異なります。
クライアントツールからの結果の処理
応答にはstop_reason
がtool_use
となり、以下を含む1つ以上のtool_use
コンテンツブロックが含まれます:
id
:この特定のツール使用ブロックの一意の識別子。これは後でツール結果を一致させるために使用されます。name
:使用されるツールの名前。input
:ツールに渡される入力を含むオブジェクトで、ツールのinput_schema
に準拠しています。
クライアントツールのツール使用レスポンスを受け取ったら、以下を行う必要があります:
tool_use
ブロックからname
、id
、input
を抽出します。- そのツール名に対応するコードベース内の実際のツールを実行し、ツールの
input
を渡します。 role
がuser
の新しいメッセージを送信して会話を続け、以下の情報を含むtool_result
タイプのcontent
ブロックを含めます:tool_use_id
:これが結果となるツール使用リクエストのid
。content
:ツールの結果。文字列(例:"content": "15 degrees"
)またはネストされたコンテンツブロックのリスト(例:"content": [{"type": "text", "text": "15 degrees"}]
)として指定できます。これらのコンテンツブロックはtext
またはimage
タイプを使用できます。is_error
(オプション):ツールの実行がエラーになった場合はtrue
に設定します。
ツール結果を受け取った後、Claudeはその情報を使用して元のユーザープロンプトへの応答の生成を続けます。
サーバーツールからの結果の処理
Claudeはツールを内部で実行し、追加のユーザー操作を必要とせずに結果を直接応答に組み込みます。
他のAPIとの違い
ツール使用を分離したり、tool
やfunction
のような特別な役割を使用する他のAPIとは異なり、AnthropicのAPIはツールをuser
とassistant
のメッセージ構造に直接統合します。
メッセージにはtext
、image
、tool_use
、tool_result
ブロックの配列が含まれます。user
メッセージにはクライアントコンテンツとtool_result
が含まれ、assistant
メッセージにはAI生成コンテンツとtool_use
が含まれます。
pause_turn
停止理由の処理
ウェブ検索などのサーバーツールを使用する場合、APIは長時間実行されるターンが一時停止されたことを示すpause_turn
停止理由を返すことがあります。
pause_turn
停止理由の処理方法は次のとおりです:
pause_turn
を処理する際:
- 会話を継続する:一時停止されたレスポンスをそのまま後続のリクエストに渡して、Claudeがターンを続行できるようにします
- 必要に応じて修正する:会話を中断または方向転換したい場合は、継続する前にコンテンツを任意で修正できます
- ツールの状態を保持する:機能を維持するために継続リクエストに同じツールを含めます
エラーのトラブルシューティング
Claudeでツールを使用する際に発生する可能性のあるエラーにはいくつかの種類があります: