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

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

Messages APIを使ってClaudeにツールを提供する方法の例を以下に示します。

​

ツール使用の仕組み

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

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

​

ツール使用の実装方法

​

モデルの選択

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

単純なツールには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"]
  }
}

​

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

ツールを使用する際に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がツールを使用せずに回答できると考えている場合でも、ユーザーの質問に答えるために特定のツールを使用するよう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が提供したツールのいずれかを使用することを決定すると、stop_reasonがtool_useで、APIレスポンスに以下を含む1つ以上のtool_useコンテンツブロックを含む応答が返されます。

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weatherを使用する必要があり、ユーザーはSFを求めています。これはおそらくサンフランシスコ(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-20240620",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weather関数を呼び出す必要があり、ユーザーはSFを求めています。これはおそらくサンフランシスコ(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-20240620",
  "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メトリクスの一部として出力されます。

​

次のステップ

クックブックで、すぐに実装できるツール使用のコード例のリポジトリを探索してください。