Claudeのツール使用

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

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

​

ツール使用の仕組み

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

注：ステップ3と4はオプションです。一部のワークフローでは、Claudeのツール使用リクエスト（ステップ2）だけで十分で、結果をClaudeに送り返す必要がない場合があります。

​

ツール使用の実装方法

​

モデルの選択

一般的に、複雑なツールや曖昧なクエリにはClaude 3.7 Sonnet、Claude 3.5 SonnetまたはClaude 3 Opusを使用します。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。

単純なツールにはClaude 3.5 HaikuまたはClaude 3 Haikuを使用しますが、不足しているパラメータを推測する可能性があることに注意してください。

​

ツールの指定

ツールはAPIリクエストのtoolsトップレベルパラメータで指定します。各ツール定義には以下が含まれます：

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

ツール使用システムプロンプト

toolsパラメータを指定してAnthropic APIを呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトを構築します。構築されたプロンプトは、モデルに指定されたツールの使用を指示し、ツールが適切に動作するために必要なコンテキストを提供するように設計されています：

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

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

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

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

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

​

Claudeの出力の制御

​

ツール使用の強制

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

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

tool_choiceパラメータには4つのオプションがあります：

• autoはClaudeに提供されたツールを呼び出すかどうかを決定させます。これはtoolsが提供された場合のデフォルト値です。
• anyはClaudeに提供されたツールのいずれかを使用することを強制しますが、特定のツールを強制しません。
• toolは特定のツールを常に使用することを強制します。
• noneはツールの使用を防ぎます。これは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 3 Opusモデルはtool_choiceがautoに設定されている場合にこれを行い（これはデフォルト値です、ツール使用の強制を参照）、SonnetとHaikuはプロンプトによってこれを行うことができます。

例えば、「What’s the weather like in San Francisco right now, and what time is it there?」というプロンプトに対して、Claudeは以下のように応答する可能性があります：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

この思考の連鎖は、Claudeの推論プロセスに洞察を与え、予期しない動作のデバッグに役立ちます。

Claude 3 Sonnetモデルでは、デフォルトでは思考の連鎖は一般的ではありませんが、ユーザーメッセージやシステムプロンプトに"Before answering, explain your reasoning step-by-step in tags."のような内容を追加することで、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に準拠します。

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to use the get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

ツール結果を受け取った後、Claudeはその情報を使用して元の

ユーザープロンプトへの応答を生成し続けます。

​

エラーのトラブルシューティング

Claudeでツールを使用する際には、いくつかの異なるタイプのエラーが発生する可能性があります：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

​

ツール使用の例

以下は、さまざまなツール使用パターンとテクニックを示すコード例です。簡潔にするため、ツールは単純なツールで、最適なパフォーマンスを確保するために理想的な長さよりも短いツールの説明になっています。

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "サンフランシスコの現在の気温は15度セルシウス（59度ファーレンハイト）です。ベイエリアは涼しい一日です！"
    }
  ]
}

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

​

価格設定

ツール使用リクエストは、モデルに送信される入力トークンの総数（toolsパラメータを含む）と生成される出力トークンの数に基づいて、他のClaude APIリクエストと同じように価格が設定されます。

ツール使用による追加トークンは以下から発生します：

• APIリクエストのtoolsパラメータ（ツール名、説明、スキーマ）
• APIリクエストとレスポンスのtool_useコンテンツブロック
• APIリクエストのtool_resultコンテンツブロック

toolsを使用する場合、ツール使用を可能にする特別なシステムプロンプトもモデルに自動的に含まれます。各モデルに必要なツール使用トークン数を以下に示します（上記の追加トークンは除く）。表は少なくとも1つのツールが提供されることを前提としています。toolsが提供されていない場合、noneのツール選択は0の追加システムプロンプトトークンを使用します。

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

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

​

次のステップ

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