ツール使用の実装方法
Claudeでツール使用を実装する方法について学びます。
モデルの選択
一般的に、複雑なツールや曖昧なクエリには 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
パラメータの変更はキャッシュされたメッセージブロックを無効にします。ツール定義とシステムプロンプトはキャッシュされたままですが、メッセージコンテンツは再処理される必要があります。
この図は各オプションがどのように機能するかを示しています:
tool_choice
が any
または tool
の場合、ツールの使用を強制するためにアシスタントメッセージを事前入力することに注意してください。これは、明示的に求められても、モデルが tool_use
コンテンツブロックの前に思考の連鎖 text
コンテンツブロックを出力しないことを意味します。
ツール使用で拡張思考を使用する場合、tool_choice: {"type": "any"}
と tool_choice: {"type": "tool", "name": "..."}
はサポートされておらず、エラーが発生します。拡張思考と互換性があるのは tool_choice: {"type": "auto"}
(デフォルト)と tool_choice: {"type": "none"}
のみです。
私たちのテストでは、これがパフォーマンスを低下させることはないことが示されています。(特にOpusで)思考の連鎖を維持しながら、モデルに特定のツールの使用を要求したい場合は、tool_choice
に {"type": "auto"}
(デフォルト)を使用し、user
メッセージに明示的な指示を追加できます。例:ロンドンの天気はどうですか?回答でget_weatherツールを使用してください。
JSON出力
ツールは必ずしもクライアント関数である必要はありません — 提供されたスキーマに従うJSON出力をモデルに返させたい場合はいつでもツールを使用できます。例えば、特定のスキーマを持つ record_summary
ツールを使用する場合があります。完全な動作例については、ClaudeでのTool useを参照してください。
思考の連鎖
ツールを使用する際、Claudeはしばしば「思考の連鎖」、つまり問題を分解し、どのツールを使用するかを決定するために使用する段階的な推論を示します。Claude Opus 3 モデルは、tool_choice
が auto
に設定されている場合にこれを行います(これはデフォルト値です。ツール使用の強制を参照)。SonnetとHaikuはプロンプトでこれを行うよう促すことができます。
例えば、「今のサンフランシスコの天気はどうで、そこの時間は何時ですか?」というプロンプトに対して、Claudeは以下のように応答する場合があります:
この思考の連鎖は、Claudeの推論プロセスへの洞察を提供し、予期しない動作をデバッグするのに役立ちます。
Claude Sonnet 3 モデルでは、思考の連鎖はデフォルトではあまり一般的ではありませんが、ユーザーメッセージやシステムプロンプトに「答える前に、<thinking>
タグで段階的に推論を説明してください。」のような内容を追加することで、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 4 モデルはデフォルトで優れた並列ツール使用機能を持っていますが、すべてのモデルで対象を絞ったプロンプトを使用して並列ツール実行の可能性を高めることができます:
Claude Sonnet 3.7での並列ツール使用
Claude Sonnet 3.7は、disable_parallel_tool_use
を設定していない場合でも、応答で並列ツール呼び出しを実行する可能性が低い場合があります。これを回避するために、トークン効率的ツール使用を有効にすることをお勧めします。これにより、Claudeが並列ツールを使用することが促進されます。このベータ機能は、レイテンシを削減し、出力トークンを平均14%節約します。
トークン効率的ツール使用ベータにオプトインしたくない場合は、他のツールへの呼び出しを同時にラップするメタツールとして機能する「バッチツール」を導入することもできます。このツールが存在する場合、モデルはそれを使用して複数のツールを並列で同時に呼び出すことがわかります。
この回避策の使用方法については、クックブックのこの例を参照してください。
ツール使用とツール結果コンテンツブロックの処理
Claudeの応答は、クライアントツールまたはサーバーツールを使用するかによって異なります。
クライアントツールからの結果の処理
応答は tool_use
の stop_reason
を持ち、以下を含む1つ以上の tool_use
コンテンツブロックを持ちます:
id
: この特定のツール使用ブロックの一意の識別子。これは後でツール結果を照合するために使用されます。name
: 使用されているツールの名前。input
: ツールのinput_schema
に準拠して、ツールに渡される入力を含むオブジェクト。
クライアントツールのツール使用応答を受信した場合、以下を行う必要があります:
tool_use
ブロックからname
、id
、input
を抽出します。- そのツール名に対応するコードベース内の実際のツールを実行し、ツール
input
を渡します。 user
のrole
と、tool_result
タイプと以下の情報を含むcontent
ブロックを持つ新しいメッセージを送信して会話を続行します:tool_use_id
: これが結果となるツール使用リクエストのid
。content
: ツールの結果を文字列として(例:"content": "15度"
)またはネストされたコンテンツブロックのリストとして(例:"content": [{"type": "text", "text": "15度"}]
)。これらのコンテンツブロックはtext
またはimage
タイプを使用できます。is_error
(オプション): ツール実行がエラーになった場合はtrue
に設定します。
重要なフォーマット要件:
- ツール結果ブロックは、メッセージ履歴内で対応するツール使用ブロックの直後に続く必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間にメッセージを含めることはできません。
- ツール結果を含むユーザーメッセージでは、tool_resultブロックがコンテンツ配列の最初に来る必要があります。テキストはすべてのツール結果の後に来る必要があります。
例えば、これは400エラーを引き起こします:
これは正しいです:
「tool_use idsがtool_resultブロックの直後に見つからない」のようなエラーを受信した場合は、ツール結果が正しくフォーマットされていることを確認してください。
ツール結果を受信した後、Claudeはその情報を使用して元のユーザープロンプトへの応答の生成を続行します。
サーバーツールからの結果の処理
Claudeはツールを内部で実行し、追加のユーザーインタラクションを必要とせずに結果を直接応答に組み込みます。
他のAPIとの違い
ツール使用を分離したり、tool
や function
などの特別な役割を使用する他のAPIとは異なり、AnthropicのAPIはツールを user
と assistant
のメッセージ構造に直接統合します。
メッセージには text
、image
、tool_use
、tool_result
ブロックの配列が含まれます。user
メッセージにはクライアントコンテンツと tool_result
が含まれ、assistant
メッセージにはAI生成コンテンツと tool_use
が含まれます。
max_tokens
停止理由の処理
Claudeの応答が max_tokens
制限に達したために切り捨てられ、切り捨てられた応答に不完全なツール使用ブロックが含まれている場合、完全なツール使用を取得するために、より高い max_tokens
値でリクエストを再試行する必要があります。
pause_turn
停止理由の処理
ウェブ検索などのサーバーツールを使用する場合、APIは pause_turn
停止理由を返すことがあり、これはAPIが長時間実行されるターンを一時停止したことを示します。
pause_turn
停止理由を処理する方法は以下の通りです:
pause_turn
を処理する際:
- 会話を続行する: 一時停止された応答をそのまま後続のリクエストに渡して、Claudeがターンを続行できるようにします
- 必要に応じて修正する: 会話を中断またはリダイレクトしたい場合は、続行前にコンテンツをオプションで修正できます
- ツール状態を保持する: 機能を維持するために、継続リクエストに同じツールを含めます
エラーのトラブルシューティング
Claudeでツールを使用する際に発生する可能性のあるエラーにはいくつかの種類があります: