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パラメータには3つのオプションがあります:

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

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

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はプロンプトによってこれを行うことができます。

例えば、「サンフランシスコの現在の天気は?そこの時刻は?」というプロンプトに対して、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"}
}

​

価格設定

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

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

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

toolsを使用すると、ツール使用を可能にする特別なシステムプロンプトもモデルに自動的に含まれます。各モデルに必要なツール使用トークン数は以下の通りです(上記の追加トークンを除く):

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

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

​

次のステップ

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