モデルの選択
複雑なツールと曖昧なクエリには、最新のClaude Sonnet(4.5)またはClaude Opus(4.1)モデルの使用をお勧めします。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。 シンプルなツールにはClaude Haikuモデルを使用してください。ただし、不足しているパラメータを推測する可能性があることに注意してください。Claude でツール使用と拡張思考を使用する場合は、詳細についてはこちらのガイドを参照してください。
クライアントツールの指定
クライアントツール(Anthropic定義とユーザー定義の両方)は、APIリクエストのtoolsトップレベルパラメータで指定されます。各ツール定義には以下が含まれます:
| パラメータ | 説明 |
|---|---|
name | ツールの名前。正規表現^[a-zA-Z0-9_-]{1,64}$に一致する必要があります。 |
description | ツールが何をするか、いつ使用すべきか、どのように動作するかについての詳細なプレーンテキスト説明。 |
input_schema | ツールの予想されるパラメータを定義するJSON Schemaオブジェクト。 |
シンプルなツール定義の例
シンプルなツール定義の例
JSON
get_weatherという名前)は、必須のlocation文字列と、「celsius」または「fahrenheit」のいずれかである必須ではないunit文字列を含む入力オブジェクトを期待します。ツール使用システムプロンプト
toolsパラメータを使用してClaude APIを呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトが構築されます。構築されたプロンプトは、指定されたツールを使用するようにモデルに指示し、ツールが適切に動作するために必要なコンテキストを提供するように設計されています:
ツール定義のベストプラクティス
Claudeでツールを使用する際に最高のパフォーマンスを得るには、以下のガイドラインに従ってください:- 非常に詳細な説明を提供してください。 これはツールのパフォーマンスにおいて最も重要な要素です。説明には、以下を含むツールに関するすべての詳細を説明する必要があります:
- ツールが何をするか
- いつ使用すべきか(そしていつ使用すべきでないか)
- 各パラメータが何を意味し、ツールの動作にどのように影響するか
- ツール名が不明な場合、ツールが返さない情報など、重要な注意事項や制限事項。Claudeに提供できるコンテキストが多いほど、ツールをいつどのように使用するかを決定するのに役立ちます。ツール説明ごとに少なくとも3~4文を目指し、ツールが複雑な場合はそれ以上を目指してください。
- 説明を例より優先してください。 ツールの使用方法の例をその説明またはそれに付随するプロンプトに含めることができますが、これはツールの目的とパラメータの明確で包括的な説明を持つことほど重要ではありません。説明を完全に充実させた後にのみ例を追加してください。
良いツール説明の例
良いツール説明の例
JSON
不適切なツール説明の例
不適切なツール説明の例
JSON
tickerパラメータが何を意味するかを明確に説明しています。不適切な説明は短すぎて、ツールの動作と使用方法についてClaudeに多くの未解決の質問を残します。
ツールランナー(ベータ版)
ツールランナーは、Claudeでツールを実行するためのすぐに使用できるソリューションを提供します。ツール呼び出し、ツール結果、会話管理を手動で処理する代わりに、ツールランナーは自動的に以下を実行します:- Claudeがツールを呼び出すときにツールを実行する
- リクエスト/レスポンスサイクルを処理する
- 会話状態を管理する
- 型安全性と検証を提供する
ツールランナーは現在ベータ版であり、PythonおよびTypeScript SDKでのみ利用可能です。
基本的な使用方法
@beta_toolデコレータを使用してツールを定義し、client.beta.messages.tool_runner()を使用してそれらを実行します。非同期クライアントを使用している場合は、
@beta_toolを@beta_async_toolに置き換え、関数をasync defで定義してください。@beta_toolデコレータは関数の引数とdocstringを検査して、指定された関数のJSON スキーマ表現を抽出します。上記の例では、calculate_sumは以下に変換されます:SDK ツールランナーはベータ版です。このドキュメントの残りの部分は、手動ツール実装をカバーしています。
Claudeの出力の制御
ツール使用の強制
場合によっては、Claudeが特定のツールを使用してユーザーの質問に答えるようにしたいことがあります。これは、Claudeがツールを使用せずに答えを提供できると考えている場合でも同様です。これは、tool_choiceフィールドでツールを指定することで実行できます:
tool_choiceパラメータを使用する場合、4つの可能なオプションがあります:
autoを使用すると、Claudeは提供されたツールを呼び出すかどうかを決定できます。これはtoolsが提供されるときのデフォルト値です。anyは、Claudeが提供されたツールの1つを使用する必要があることを示していますが、特定のツールを強制しません。toolを使用すると、Claudeが常に特定のツールを使用するように強制できます。noneは、Claudeがツールを使用することを防ぎます。これはtoolsが提供されないときのデフォルト値です。
プロンプトキャッシングを使用する場合、
tool_choiceパラメータへの変更はキャッシュされたメッセージブロックを無効にします。ツール定義とシステムプロンプトはキャッシュされたままですが、メッセージコンテンツは再処理される必要があります。
tool_choiceがanyまたはtoolの場合、アシスタントメッセージをプリフィルして、ツールの使用を強制することに注意してください。これは、明示的に要求された場合でも、モデルがtool_useコンテンツブロックの前に自然言語応答または説明を発行しないことを意味します。
拡張思考をツール使用と一緒に使用する場合、
tool_choice: {"type": "any"}およびtool_choice: {"type": "tool", "name": "..."}はサポートされておらず、エラーが発生します。tool_choice: {"type": "auto"}(デフォルト)およびtool_choice: {"type": "none"}のみが拡張思考と互換性があります。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はしばしば実行している内容についてコメントしたり、ツールを呼び出す前にユーザーに自然に応答したりします。 例えば、プロンプト「サンフランシスコの現在の天気は何ですか、そしてそこの時刻は何ですか?」が与えられた場合、Claudeは以下のように応答する可能性があります:JSON
<examples>を提供することで、これを行うことができます。
Claudeが実行内容を説明する際にさまざまなフレーズとアプローチを使用する可能性があることに注意することが重要です。コードはこれらの応答を他のアシスタント生成テキストと同様に扱い、特定のフォーマット規則に依存しないようにしてください。
並列ツール使用
デフォルトでは、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 4モデル(Opus 4.1、Opus 4、Sonnet 4)の場合、システムプロンプトに以下を追加してください:さらに強力な並列ツール使用の場合(デフォルトが十分でない場合に推奨)、以下を使用してください:
ユーザーメッセージプロンプティング
ユーザーメッセージプロンプティング
特定のユーザーメッセージ内で並列ツール使用を促すこともできます:
Claude Sonnet 3.7での並列ツール使用Claude Sonnet 3.7は、
disable_parallel_tool_useを設定していない場合でも、応答で並列ツール呼び出しを行う可能性が低い場合があります。これを回避するには、トークン効率的なツール使用を有効にすることをお勧めします。これはClaudeが並列ツールを使用するように促すのに役立ちます。このベータ機能は、レイテンシも削減し、平均14%の出力トークンを節約します。トークン効率的なツール使用ベータにオプトインしない場合は、他のツールへの呼び出しを同時にラップできる「バッチツール」として機能するメタツールを導入することもできます。このツールが存在する場合、モデルはそれを使用して複数のツールを同時に並列で呼び出すことがわかっています。このワークアラウンドの使用方法については、クックブックのこの例を参照してください。ツール使用とツール結果コンテンツブロックの処理
ツールランナーでより簡単に: このセクションで説明されている手動ツール処理は、ツールランナーによって自動的に管理されます。ツール実行をカスタム制御する必要がある場合は、このセクションを使用してください。
クライアントツールからの結果の処理
応答はtool_useのstop_reasonと、以下を含む1つ以上のtool_useコンテンツブロックを持ちます:
id:この特定のツール使用ブロックの一意の識別子。これは後でツール結果と照合するために使用されます。name:使用されているツールの名前。input:ツールのinput_schemaに準拠するツールに渡される入力を含むオブジェクト。
`tool_use`コンテンツブロックを含むAPIレスポンスの例
`tool_use`コンテンツブロックを含むAPIレスポンスの例
JSON
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"}])、またはドキュメントブロックのリスト(例:"content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}])。これらのコンテンツブロックはtext、image、またはdocumentタイプを使用できます。is_error(オプション):ツール実行がエラーで発生した場合はtrueに設定します。
重要なフォーマット要件:これは正しいです:「tool_use ids were found without tool_result blocks immediately after」のようなエラーが表示される場合は、ツール結果が正しくフォーマットされていることを確認してください。
- ツール結果ブロックは、メッセージ履歴内の対応するツール使用ブロックの直後に続く必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間にメッセージを含めることはできません。
- ツール結果を含むユーザーメッセージでは、tool_resultブロックはコンテンツ配列の最初に来る必要があります。テキストはすべてのツール結果の後に来る必要があります。
成功したツール結果の例
成功したツール結果の例
JSON
画像を含むツール結果の例
画像を含むツール結果の例
JSON
空のツール結果の例
空のツール結果の例
JSON
ドキュメントを含むツール結果の例
ドキュメントを含むツール結果の例
JSON
サーバーツールからの結果の処理
Claudeはツールを内部で実行し、追加のユーザーインタラクションを必要とせずに結果を応答に直接組み込みます。他のAPIとの違いツール使用を分離するか、
toolまたはfunctionのような特別なロールを使用するAPIとは異なり、Claude 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停止理由の処理
Webサーチなどのサーバーツールを使用する場合、APIはpause_turn停止理由を返す可能性があり、APIが長時間実行されているターンを一時停止したことを示します。
pause_turn停止理由を処理する方法は以下の通りです:
pause_turnを処理する場合:
- 会話を続ける:一時停止された応答を後続のリクエストでそのまま渡して、Claudeがそのターンを続行できるようにします
- 必要に応じて変更:会話を中断またはリダイレクトしたい場合は、オプションで続行する前にコンテンツを変更できます
- ツール状態を保持:機能を維持するために、継続リクエストに同じツールを含めます
エラーのトラブルシューティング
組み込みエラーハンドリング: ツールランナーは、ほとんどの一般的なシナリオに対して自動エラーハンドリングを提供します。このセクションでは、高度なユースケースのための手動エラーハンドリングについて説明します。
ツール実行エラー
ツール実行エラー
ツール自体が実行中にエラーをスローする場合(例:天気データを取得する際のネットワークエラー)、Claudeはこのエラーをユーザーへの応答に組み込みます。例えば、「申し訳ありませんが、天気サービスAPIが利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」
contentと一緒に"is_error": trueでエラーメッセージを返すことができます:JSON
無効なツール名
無効なツール名
Claudeがツールの使用を試みるのが無効な場合(例:必須パラメータが不足している)、通常はClaudeがツールを正しく使用するための情報が不足していることを意味します。開発中の最善の方法は、ツール定義のツールリクエストが無効または不足しているパラメータがある場合、Claudeは修正を試みて2~3回再試行してからユーザーに謝罪します。
description値をより詳細にしてリクエストを再度試行することです。ただし、エラーを示すtool_resultで会話を続行することもでき、Claudeは不足している情報を入力してツールを再度使用しようとします:JSON
<search_quality_reflection>タグ
<search_quality_reflection>タグ
Claudeが<search_quality_reflection>タグで検索品質を反映するのを防ぐには、プロンプトに「Do not reflect on the quality of the returned search results in your response」を追加してください。
サーバーツールエラー
サーバーツールエラー
サーバーツールがエラーに遭遇した場合(例:Webサーチのネットワーク問題)、Claudeはこれらのエラーを透過的に処理し、ユーザーに代替応答または説明を提供しようとします。クライアントツールとは異なり、サーバーツールの
is_error結果を処理する必要はありません。Webサーチの場合、可能なエラーコードは以下を含みます:too_many_requests:レート制限を超過invalid_input:無効な検索クエリパラメータmax_uses_exceeded:最大Webサーチツール使用数を超過query_too_long:クエリが最大長を超過unavailable:内部エラーが発生
並列ツール呼び出しが機能していない
並列ツール呼び出しが機能していない
Claudeが予想される場合に並列ツール呼び出しを行っていない場合は、これらの一般的な問題を確認してください:1. 不正なツール結果フォーマット最も一般的な問題は、会話履歴でツール結果を不正にフォーマットすることです。これはClaudeに並列呼び出しを回避するように「教える」ものです。特に並列ツール使用の場合:その他のフォーマット規則については、上記の一般的なフォーマット要件を参照してください。2. 弱いプロンプティングデフォルトプロンプティングは十分でない場合があります。より強力な言語を使用してください:3. 並列ツール使用の測定並列ツール呼び出しが機能していることを確認するには:4. モデル固有の動作
- ❌ 間違い:各ツール結果に対して個別のユーザーメッセージを送信する
- ✅ 正しい:すべてのツール結果は単一のユーザーメッセージに含まれる必要があります
- Claude Opus 4.1、Opus 4、Sonnet 4:最小限のプロンプティングで並列ツール使用に優れています
- Claude Sonnet 3.7:より強力なプロンプティングまたはトークン効率的なツール使用が必要な場合があります
- Claude Haiku:明示的なプロンプティングなしで並列ツールを使用する可能性が低い