Claudeは外部のクライアントサイドツールや関数と連携することができ、より幅広いタスクを実行するために独自のカスタムツールをClaudeに装備することができます。

新しい包括的なツール使用コースを通じて、Claudeでのツール使用をマスターするために必要なすべてを学びましょう!引き続き、このフォームを使用してアイデアや提案を共有してください。

以下は、Messages APIを使用してClaudeにツールを提供する例です:


ツール使用の仕組み

以下の手順でClaudeと外部ツールを統合します:

1

Claudeにツールとユーザープロンプトを提供

  • APIリクエストでツールの名前、説明、入力スキーマを定義します。
  • ツールを必要とする可能性のあるユーザープロンプトを含めます(例:「サンフランシスコの天気は?」)。
2

Claudeがツールの使用を決定

  • Claudeはユーザーのクエリに対してツールが役立つかどうかを評価します。
  • もしそうなら、Claudeは適切にフォーマットされたツール使用リクエストを構築します。
  • APIレスポンスのstop_reasontool_useとなり、Claudeの意図を示します。
3

ツール入力を抽出し、コードを実行して結果を返す

  • クライアント側でClaudeのリクエストからツール名と入力を抽出します。
  • 実際のツールコードをクライアントサイドで実行します。
  • tool_resultコンテンツブロックを含む新しいuserメッセージで会話を継続します。
4

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を呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトを構築します。構築されたプロンプトは、モデルに指定されたツールの使用を指示し、ツールが適切に動作するために必要なコンテキストを提供するように設計されています:

このEnvironmentでは、ユーザーの質問に答えるために使用できる一連のツールにアクセスできます。
{{ フォーマット指示 }}
文字列とスカラーパラメータはそのまま指定し、リストとオブジェクトはJSON形式を使用します。文字列値のスペースは削除されないことに注意してください。出力は有効なXMLである必要はなく、正規表現で解析されます。
以下はJSONSchema形式で利用可能な関数です:
{{ JSONスキーマ形式のツール定義 }}
{{ ユーザーシステムプロンプト }}
{{ ツール設定 }}

ツール定義のベストプラクティス

ツールを使用する際にClaudeから最高のパフォーマンスを引き出すために、以下のガイドラインに従ってください:

  • 非常に詳細な説明を提供する。 これはツールのパフォーマンスにおいて最も重要な要素です。説明には以下のすべての詳細を含める必要があります:
    • ツールの機能
    • 使用すべき時期(および使用すべきでない時期)
    • 各パラメータの意味とツールの動作への影響
    • ツール名が不明確な場合、ツールが返さない情報など、重要な注意点や制限事項。ツールに関するコンテキストをClaudeに多く提供するほど、ツールをいつどのように使用するかをより適切に判断できます。ツールの説明は最低でも3-4文、複雑なツールの場合はそれ以上を目指してください。
  • 例よりも説明を優先する。 ツールの説明や付随するプロンプトにツールの使用例を含めることはできますが、これはツールの目的とパラメータについての明確で包括的な説明を持つことほど重要ではありません。説明を十分に練り上げた後にのみ例を追加してください。

良い説明は、ツールの機能、使用時期、返すデータ、およびtickerパラメータの意味を明確に説明しています。悪い説明は簡潔すぎて、ツールの動作と使用方法に関する多くの疑問をClaudeに残しています。

Claudeの出力の制御

ツール使用の強制

場合によっては、Claudeがツールを使用せずに回答できると考えていても、ユーザーの質問に答えるために特定のツールを使用させたい場合があります。これはtool_choiceフィールドでツールを指定することで実現できます:

tool_choice = {"type": "tool", "name": "get_weather"}

tool_choiceパラメータを使用する場合、3つのオプションがあります:

  • autoはClaudeに提供されたツールを呼び出すかどうかを決定させます。これがデフォルト値です。
  • anyはClaudeに提供されたツールのいずれかを使用する必要があることを伝えますが、特定のツールを強制しません。
  • toolは特定のツールを常に使用するようClaudeに強制します。

この図は各オプションの動作を示しています:

tool_choiceanyまたはtoolに設定すると、ツールを使用するようにアシスタントメッセージが事前に入力されることに注意してください。これは、明示的に要求された場合でも、モデルはtool_useコンテンツブロックの前に思考の連鎖textコンテンツブロックを出力しないことを意味します。

私たちのテストでは、これによってパフォーマンスが低下することはないことが示されています。特定のツールの使用を要求しながら思考の連鎖を維持したい場合(特にOpusの場合)、tool_choice{"type": "auto"}(デフォルト)を使用し、userメッセージに明示的な指示を追加できます。例: ロンドンの天気はどうですか?回答にget_weatherツールを使用してください。

JSON出力

ツールは必ずしもクライアントサイドの関数である必要はありません - 提供されたスキーマに従うJSON出力をモデルに返させたい場合はいつでもツールを使用できます。例えば、特定のスキーマを持つrecord_summaryツールを使用できます。完全な動作例についてはツール使用の例を参照してください。

思考の連鎖

ツールを使用する際、Claudeはしばしば「思考の連鎖」、つまり問題を分解してどのツールを使用するかを決定するために使用するステップバイステップの推論を示します。Claude 3 Opusモデルはtool_choiceautoに設定されている場合にこれを行い(これはデフォルト値です。ツール使用の強制を参照)、SonnetとHaikuはプロンプトによってこれを行うことができます。

例えば、「サンフランシスコの現在の天気はどうですか?そこの時間は何時ですか?」というプロンプトに対して、Claudeは以下のように応答する可能性があります:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>この質問に答えるために: 1. get_weatherツールを使用してサンフランシスコの現在の天気を取得します。2. get_timeツールを使用してサンフランシスコ(CA)を含むAmerica/Los_Angelesタイムゾーンの現在の時刻を取得します。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

この思考の連鎖は、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_reasontool_useのレスポンスと、以下を含む1つ以上のtool_useコンテンツブロックをAPIレスポンスで返します:

  • id: この特定のツール使用ブロックの一意の識別子。これは後でツール結果を照合するために使用されます。
  • name: 使用されているツールの名前。
  • input: ツールのinput_schemaに準拠した、ツールに渡される入力を含むオブジェクト。

ツール使用レスポンスを受け取ったら、以下を行う必要があります:

  1. tool_useブロックからnameidinputを抽出します。
  2. そのツール名に対応するコードベース内の実際のツールを実行し、ツールのinputを渡します。
  3. [オプション]roleuserで、以下の情報を含むtool_resultタイプのcontentブロックを持つ新しいメッセージを送信して会話を継続します:
    • tool_use_id: これが結果となるツール使用リクエストのid
    • content: ツールの結果。文字列(例: "content": "15度")またはネストされたコンテンツブロックのリスト(例: "content": [{"type": "text", "text": "15度"}])として。これらのコンテンツブロックはtextまたはimageタイプを使用できます。
    • is_error(オプション): ツールの実行がエラーになった場合はtrueに設定します。

ツール結果を受け取った後、Claudeはその情報を使用して元のユーザープロンプトへの応答の生成を継続します。

他のAPIとの違い

ツール使用を分離したり、toolfunctionのような特別な役割を使用する他のAPIとは異なり、AnthropicのAPIはツールをuserassistantのメッセージ構造に直接統合します。

メッセージにはtextimagetool_usetool_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 Opusauto
any, tool
530トークン
281トークン
Claude 3 Sonnetauto
any, tool
159トークン
235トークン
Claude 3 Haikuauto
any, tool
264トークン
340トークン
Claude 3.5 Sonnet (June)auto
any, tool
294トークン
261トークン

これらのトークン数は、通常の入力トークンと出力トークンに追加され、リクエストの総コストを計算します。現在のモデルごとの価格については、モデル概要表を参照してください。

ツール使用プロンプトを送信すると、他のAPIリクエストと同様に、レスポンスは報告されるusageメトリクスの一部として入力トークン数と出力トークン数の両方を出力します。


次のステップ

クックブックで実装可能なツール使用コード例のリポジトリを探索してください: