ツール使用(関数呼び出し)
Claudeは外部のクライアントサイドツールや関数と連携することができ、より幅広いタスクを実行するために独自のカスタムツールをClaudeに装備することができます。
以下は、Messages APIを使用してClaudeにツールを提供する例です:
ツール使用の仕組み
以下の手順でClaudeと外部ツールを統合します:
Claudeにツールとユーザープロンプトを提供
- APIリクエストでツールの名前、説明、入力スキーマを定義します。
- ツールを必要とする可能性のあるユーザープロンプトを含めます(例:「サンフランシスコの天気は?」)。
Claudeがツールの使用を決定
- Claudeはユーザーのクエリに対してツールが役立つかどうかを評価します。
- もしそうなら、Claudeは適切にフォーマットされたツール使用リクエストを構築します。
- APIレスポンスの
stop_reason
がtool_use
となり、Claudeの意図を示します。
ツール入力を抽出し、コードを実行して結果を返す
- クライアント側でClaudeのリクエストからツール名と入力を抽出します。
- 実際のツールコードをクライアントサイドで実行します。
tool_result
コンテンツブロックを含む新しいuser
メッセージで会話を継続します。
Claudeがツールの結果を使用してレスポンスを作成
- Claudeはツールの結果を分析して、元のユーザープロンプトへの最終的な応答を作成します。
注意: ステップ3と4はオプションです。一部のワークフローでは、Claudeのツール使用リクエスト(ステップ2)だけで十分で、結果をClaudeに送り返す必要はない場合があります。
ツールはユーザーが提供
重要な点として、Claudeにはビルトインのサーバーサイドツールへのアクセス権がありません。すべてのツールは、各APIリクエストでユーザーであるあなたが明示的に提供する必要があります。これにより、Claudeが使用できるツールを完全にコントロールし、柔軟性を持たせることができます。
コンピュータ使用(ベータ)機能は例外です - これはAnthropicが提供し、ユーザーであるあなたが実装するツールを導入します。
ツール使用の実装方法
モデルの選択
一般的に、複雑なツールや曖昧なクエリにはClaude 3.5 SonnetまたはClaude 3 Opusを使用します。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。
単純なツールにはClaude 3.5 HaikuまたはClaude 3 Haikuを使用しますが、不足しているパラメータを推測する可能性があることに注意してください。
ツールの指定
ツールはAPIリクエストのtools
トップレベルパラメータで指定します。各ツール定義には以下が含まれます:
パラメータ | 説明 |
---|---|
name | ツールの名前。正規表現^[a-zA-Z0-9_-]{1,64}$ に一致する必要があります。 |
description | ツールの機能、使用時期、動作に関する詳細なプレーンテキストの説明。 |
input_schema | ツールに必要なパラメータを定義するJSONスキーマオブジェクト。 |
ツール使用システムプロンプト
tools
パラメータを指定してAnthropic APIを呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトを構築します。構築されたプロンプトは、モデルに指定されたツールの使用を指示し、ツールが適切に動作するために必要なコンテキストを提供するように設計されています:
ツール定義のベストプラクティス
ツールを使用する際にClaudeから最高のパフォーマンスを引き出すために、以下のガイドラインに従ってください:
- 非常に詳細な説明を提供する。 これはツールのパフォーマンスにおいて最も重要な要素です。説明には以下のすべての詳細を含める必要があります:
- ツールの機能
- 使用すべき時期(および使用すべきでない時期)
- 各パラメータの意味とツールの動作への影響
- ツール名が不明確な場合、ツールが返さない情報など、重要な注意点や制限事項。ツールに関するコンテキストをClaudeに多く提供するほど、ツールをいつどのように使用するかをより適切に判断できます。ツールの説明は最低でも3-4文、複雑なツールの場合はそれ以上を目指してください。
- 例よりも説明を優先する。 ツールの説明や付随するプロンプトにツールの使用例を含めることはできますが、これはツールの目的とパラメータについての明確で包括的な説明を持つことほど重要ではありません。説明を十分に練り上げた後にのみ例を追加してください。
良い説明は、ツールの機能、使用時期、返すデータ、およびticker
パラメータの意味を明確に説明しています。悪い説明は簡潔すぎて、ツールの動作と使用方法に関する多くの疑問をClaudeに残しています。
Claudeの出力の制御
ツール使用の強制
場合によっては、Claudeがツールを使用せずに回答できると考えていても、ユーザーの質問に答えるために特定のツールを使用させたい場合があります。これはtool_choice
フィールドでツールを指定することで実現できます:
tool_choiceパラメータを使用する場合、3つのオプションがあります:
auto
はClaudeに提供されたツールを呼び出すかどうかを決定させます。これがデフォルト値です。any
はClaudeに提供されたツールのいずれかを使用する必要があることを伝えますが、特定のツールを強制しません。tool
は特定のツールを常に使用するようClaudeに強制します。
この図は各オプションの動作を示しています:
tool_choice
をany
またはtool
に設定すると、ツールを使用するようにアシスタントメッセージが事前に入力されることに注意してください。これは、明示的に要求された場合でも、モデルはtool_use
コンテンツブロックの前に思考の連鎖text
コンテンツブロックを出力しないことを意味します。
私たちのテストでは、これによってパフォーマンスが低下することはないことが示されています。特定のツールの使用を要求しながら思考の連鎖を維持したい場合(特にOpusの場合)、tool_choice
に{"type": "auto"}
(デフォルト)を使用し、user
メッセージに明示的な指示を追加できます。例: ロンドンの天気はどうですか?回答にget_weatherツールを使用してください。
JSON出力
ツールは必ずしもクライアントサイドの関数である必要はありません - 提供されたスキーマに従うJSON出力をモデルに返させたい場合はいつでもツールを使用できます。例えば、特定のスキーマを持つrecord_summary
ツールを使用できます。完全な動作例についてはツール使用の例を参照してください。
思考の連鎖
ツールを使用する際、Claudeはしばしば「思考の連鎖」、つまり問題を分解してどのツールを使用するかを決定するために使用するステップバイステップの推論を示します。Claude 3 Opusモデルはtool_choice
がauto
に設定されている場合にこれを行い(これはデフォルト値です。ツール使用の強制を参照)、SonnetとHaikuはプロンプトによってこれを行うことができます。
例えば、「サンフランシスコの現在の天気はどうですか?そこの時間は何時ですか?」というプロンプトに対して、Claudeは以下のように応答する可能性があります:
この思考の連鎖は、Claudeの推論プロセスについての洞察を提供し、予期しない動作のデバッグに役立ちます。
Claude 3 Sonnetモデルでは、デフォルトでは思考の連鎖は一般的ではありませんが、ユーザーメッセージやシステムプロンプトに「回答する前に、タグ内でステップバイステップで推論を説明してください。」のような内容を追加することで、Claudeに推論を示すようプロンプトを与えることができます。
<thinking>
タグはClaudeが思考の連鎖を示すために使用する一般的な規則ですが、正確な形式(このXMLタグの名前など)は時間とともに変更される可能性があることに注意することが重要です。コードは思考の連鎖を他のアシスタント生成テキストと同様に扱い、<thinking>
タグの存在や特定の形式に依存すべきではありません。
並列ツール使用の無効化
デフォルトでは、Claudeはユーザーのクエリに答えるために複数のツールを使用する場合があります。tool_choice
フィールドでdisable_parallel_tool_use=true
を設定することで、この動作を無効にできます。
tool_choice
タイプがauto
の場合、Claudeが使用するツールは最大1つになりますtool_choice
タイプがany
またはtool
の場合、Claudeが使用するツールは正確に1つになります
ツール使用とツール結果コンテンツブロックの処理
Claudeが提供されたツールのいずれかを使用することを決定すると、stop_reason
がtool_use
のレスポンスと、以下を含む1つ以上のtool_use
コンテンツブロックをAPIレスポンスで返します:
id
: この特定のツール使用ブロックの一意の識別子。これは後でツール結果を照合するために使用されます。name
: 使用されているツールの名前。input
: ツールのinput_schema
に準拠した、ツールに渡される入力を含むオブジェクト。
ツール使用レスポンスを受け取ったら、以下を行う必要があります:
tool_use
ブロックからname
、id
、input
を抽出します。- そのツール名に対応するコードベース内の実際のツールを実行し、ツールの
input
を渡します。 - [オプション]
role
がuser
で、以下の情報を含むtool_result
タイプのcontent
ブロックを持つ新しいメッセージを送信して会話を継続します:tool_use_id
: これが結果となるツール使用リクエストのid
。content
: ツールの結果。文字列(例:"content": "15度"
)またはネストされたコンテンツブロックのリスト(例:"content": [{"type": "text", "text": "15度"}]
)として。これらのコンテンツブロックはtext
またはimage
タイプを使用できます。is_error
(オプション): ツールの実行がエラーになった場合はtrue
に設定します。
ツール結果を受け取った後、Claudeはその情報を使用して元のユーザープロンプトへの応答の生成を継続します。
他のAPIとの違い
ツール使用を分離したり、tool
やfunction
のような特別な役割を使用する他のAPIとは異なり、AnthropicのAPIはツールをuser
とassistant
のメッセージ構造に直接統合します。
メッセージにはtext
、image
、tool_use
、tool_result
ブロックの配列が含まれます。user
メッセージにはクライアントサイドのコンテンツとtool_result
が含まれ、assistant
メッセージにはAI生成コンテンツとtool_use
が含まれます。
エラーのトラブルシューティング
Claudeでツールを使用する際に発生する可能性のあるエラーには、いくつかの種類があります:
ツール使用の例
以下は、さまざまなツール使用パターンとテクニックを示すコード例です。簡潔にするため、ツールは単純なツールで、最適なパフォーマンスを確保するために理想的な長さよりも短いツールの説明になっています。
価格設定
ツール使用リクエストは、モデルに送信される入力トークンの総数(tools
パラメータを含む)と生成される出力トークンの数に基づいて、他のClaude APIリクエストと同じように価格が設定されます。
ツール使用による追加トークンは以下から発生します:
- APIリクエストの
tools
パラメータ(ツール名、説明、スキーマ) - APIリクエストとレスポンスの
tool_use
コンテンツブロック - APIリクエストの
tool_result
コンテンツブロック
tools
を使用すると、ツール使用を可能にする特別なシステムプロンプトもモデルに自動的に含まれます。各モデルに必要なツール使用トークン数は以下のとおりです(上記の追加トークンを除く):
モデル | ツールの選択 | ツール使用システムプロンプトのトークン数 |
---|---|---|
Claude 3.5 Sonnet (Oct) | auto any , tool | 346トークン 313トークン |
Claude 3 Opus | auto any , tool | 530トークン 281トークン |
Claude 3 Sonnet | auto any , tool | 159トークン 235トークン |
Claude 3 Haiku | auto any , tool | 264トークン 340トークン |
Claude 3.5 Sonnet (June) | auto any , tool | 294トークン 261トークン |
これらのトークン数は、通常の入力トークンと出力トークンに追加され、リクエストの総コストを計算します。現在のモデルごとの価格については、モデル概要表を参照してください。
ツール使用プロンプトを送信すると、他のAPIリクエストと同様に、レスポンスは報告されるusage
メトリクスの一部として入力トークン数と出力トークン数の両方を出力します。
次のステップ
クックブックで実装可能なツール使用コード例のリポジトリを探索してください:
Was this page helpful?