ツール使用(関数呼び出し)

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

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

​

ツール使用の仕組み

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

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

​

ツール使用の実装方法

​

モデルの選択

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

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

​

ツールの指定

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

{
  "name": "get_weather",
  "description": "指定された場所の現在の天気を取得する",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "市と州、例: San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度の単位、'celsius'または'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

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

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

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

​

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

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

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

{
  "name": "get_stock_price",
  "description": "指定された銘柄コードの現在の株価を取得します。銘柄コードはNYSEやNASDAQなどの主要な米国証券取引所に上場している公開企業の有効な銘柄である必要があります。このツールは最新の取引価格をUSDで返します。特定の株式の現在または最新の価格についてユーザーが質問した場合に使用する必要があります。株式や企業に関するその他の情報は提供しません。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "株式の銘柄コード、例: AAPLはApple Inc.を表す"
      }
    },
    "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メッセージに明示的な指示を追加できます。例: ロンドンの天気はどうですか？回答にget_weatherツールを使用してください。

​

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が提供されたツールのいずれかを使用することを決定すると、stop_reasonがtool_useのレスポンスと、以下を含む1つ以上のtool_useコンテンツブロックをAPIレスポンスで返します:

• 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": "to

olu_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メトリクスの一部として入力トークン数と出力トークン数の両方を出力します。

​

次のステップ

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