ツール使用（関数呼び出し）

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

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

​

ツール使用の仕組み

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

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

​

ツール使用の実装方法

​

モデルの選択

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

単純なツールには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": "指定された銘柄コードの現在の株価を取得します。銘柄コードはNYSEやNASDAQなどの主要な米国証券取引所に上場している公開企業の有効な銘柄である必要があります。このツールは最新の取引価格をUSDで返します。特定の株式の現在または最新の価格についてユーザーが質問した場合に使用する必要があります。株式や企業に関するその他の情報は提供しません。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "株式の銘柄コード（例：Apple Inc.の場合はAAPL）"
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "銘柄の株価を取得します。",
  "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>この質問に答えるために：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が提供されたツールの1つを使用することを決定した場合、APIレスポンスでstop_reasonがtool_useとなり、以下を含む1つ以上のtool_useコンテンツブロックが返されます：

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weatherを使用する必要があり、ユーザーはSFを希望していますが、これはおそらく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度"）またはネストされたコンテンツブロックのリスト（例："content": [{"type": "text", "text": "15度"}]）として。これらのコンテンツブロックはtextまたはimageタイプを使用できます。
   • is_error（オプション）：ツールの実行がエラーになった場合はtrueに設定します。

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15度"},
        {
          "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: 天気サービスAPIが利用できません（HTTP 500）",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "エラー：必須の'location'パラメータが不足しています",
      "is_error": true
    }
  ]
}

​

ツール使用の例

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weather関数を呼び出す必要があり、ユーザーはSFを希望していますが、これはおそらく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-5-sonnet-20241022",
  "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を使用する場合、ツール使用を可能にする特別なシステムプロンプトもモデルに自動的に含まれます。各モデルに必要なツール使用トークン数は以下のとおりです（上記の追加トークンを除く）：

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

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

​

次のステップ

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