ここでは、さまざまなツール使用のパターンとテクニックを示すいくつかのコード例を紹介します。簡潔にするために、ツールはシンプルなものを使用し、最高のパフォーマンスを確保するためにツールの説明は理想的なものよりも短くしています。詳細については、ツールの指定を参照してください。

単一のツール

この例では、get_weatherツールを使用した基本的な単一ツールの状況を示しています。

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "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"]
        }
    }],
    "messages": [{"role": "user", "content": "サンフランシスコの天気はどうですか?"}]
}'

Claudeは次のような応答を返します:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>get_weather関数を呼び出す必要があり、ユーザーはSFを求めています。これはおそらくサンフランシスコ、カリフォルニア州のことでしょう。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9", 
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

次に、提供された入力でget_weather関数を実行し、新しいuserメッセージで結果を返す必要があります:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "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"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "サンフランシスコの天気はどうですか?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>get_weatherを使う必要があり、ユーザーはSFを求めています。これはおそらくサンフランシスコ、カリフォルニア州のことでしょう。</thinking>"
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15度"
                }
            ]
        }
    ]
}'

これにより、天気データを組み込んだClaudeの最終的な応答が出力されます:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "サンフランシスコの現在の天気は摂氏15度(華氏59度)です。湾岸の街では涼しい日になっています!"
    }
  ]
}

情報の不足

ユーザーのプロンプトにツールの必須パラメータをすべて満たすのに十分な情報が含まれていない場合、Claude 3 Opusはパラメータが不足していることを認識し、それを尋ねる可能性が高くなります。Claude 3 Sonnetは、特にツールリクエストを出力する前に考えるように促された場合、尋ねることがあります。しかし、妥当な値を推測しようとすることもあります。

例えば、上記のget_weatherツールを使用して、場所を指定せずにClaudeに「天気はどうですか?」と尋ねると、特にClaude 3 Sonnetは、ツールの入力を推測することがあります:

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

この動作は、特にあいまいなプロンプトやClaude 3 Opusほど知的ではないモデルでは保証されません。Claude 3 Opusに必要なパラメータを入力するのに十分なコンテキストがない場合、ツールを呼び出すのではなく、明確な質問で応答する可能性が高くなります。


複数のツール

1つのリクエストで、Claudeに複数のツールから選択させることができます。ここでは、get_weatherget_timeの両方のツールを使用し、両方を尋ねるユーザークエリの例を示します。

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "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"]
        }
    },
    {
        "name": "get_time",
        "description": "指定されたタイムゾーンの現在時刻を取得する",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "IANAタイムゾーン名、例: America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "ニューヨークの現在の天気はどうですか? また、そこの時間は何時ですか?"
    }]
}'

この場合、Claudeはユーザーの質問に完全に答えるために、get_weatherget_timeの2つの別々のツールを一度に1つずつ使用しようとする可能性が高いです。ただし、特にツールが互いに依存していない場合は、2つのtool_useブロックを一度に出力することもあります。各ツールを実行し、単一のuserメッセージ内の別々のtool_resultブロックでそれらの結果を返す必要があります。


連続したツール

一部のタスクでは、あるツールの出力を別のツールの入力として使用するなど、複数のツールを順番に呼び出す必要がある場合があります。そのような場合、Claudeは一度に1つのツールを呼び出します。一度にすべてのツールを呼び出すように指示された場合、Claudeは、上流のツールの結果に依存している下流のツールのパラメータを推測する可能性があります。

ここでは、get_locationツールを使用してユーザーの位置情報を取得し、その位置情報をget_weatherツールに渡す例を示します:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "IPアドレスに基づいて現在のユーザーの位置情報を取得する。このツールにはパラメータや引数はありません。",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "私のいる場所の天気はどうですか?"
    }]
}'

この場合、Claudeは最初にget_locationツールを呼び出してユーザーの位置情報を取得します。tool_resultで位置情報を返した後、Claudeはその位置情報を使用してget_weatherを呼び出し、最終的な答えを取得します。

完全な会話は次のようになります:

RoleContent
User私のいる場所の天気はどうですか?
Assistant<thinking>これに答えるには、まずget_locationツールを使ってユーザーの位置情報を特定する必要があります。次に、その位置情報をget_weatherツールに渡して、そこの現在の天気を調べることができます。</thinking>[get_locationのツール使用]
User[get_locationのツール結果。IDが一致し、結果はサンフランシスコ、カリフォルニア州]
Assistant[次の入力でget_weatherのツール使用]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
User[get_weatherのツール結果。IDが一致し、結果は “59°F (15°C)、ほぼ曇り”]
Assistantサンフランシスコ、カリフォルニア州の現在の天気は、59°F (15°C)でほぼ曇りです。かなり涼しく曇った日になっています。外出する際は、薄手のジャケットを持参することをおすすめします。

この例は、Claudeが複数のツールを連鎖させて、異なるソースからデータを収集する必要がある質問に答える方法を示しています。主な手順は次のとおりです:

  1. Claudeは最初に、天気の質問に答えるにはユーザーの位置情報が必要だと気づき、get_locationツールを呼び出します。
  2. ユーザー(つまりクライアントコード)は、実際のget_location関数を実行し、tool_resultブロックで “San Francisco, CA” という結果を返します。
  3. 位置情報がわかったので、Claudeはget_weatherツールを呼び出し、locationパラメータとして “San Francisco, CA” を渡します(また、unitは必須パラメータではないため、推測したunitパラメータも渡します)。
  4. ユーザーは再び、提供された引数で実際のget_weather関数を実行し、別のtool_resultブロックで天気データを返します。
  5. 最後に、Claudeは天気データを自然言語の応答に組み込んで、元の質問に答えます。

思考連鎖ツールの使用

デフォルトでは、Claude 3 Opusは、ツールが必要かどうか、どのツールを使用するか、適切なパラメータは何かを最もよく判断するために、ツール使用クエリに答える前に考えるように促されます。Claude 3 SonnetとClaude 3 Haikuは、できるだけツールを使用するように促され、不要なツールを呼び出したり、欠落しているパラメータを推測したりする可能性が高くなります。SonnetやHaikuに、ツールを呼び出す前にユーザークエリをより適切に評価するように促すには、次のプロンプトを使用できます:

思考連鎖プロンプト

関連するツールを使用してユーザーのリクエストに答えてください(利用可能な場合)。ツールを呼び出す前に、\<thinking>\</thinking>タグ内で分析を行います。まず、提供されたツールのうち、ユーザーのリクエストに答えるのに関連するツールはどれかを考えます。次に、関連するツールの必須パラメータを1つずつ確認し、ユーザーが直接提供したか、値を推測するのに十分な情報を与えているかを判断します。パラメータを推測できるかどうかを決める際は、特定の値をサポートするすべてのコンテキストを慎重に検討してください。必須パラメータのすべての値が存在するか、合理的に推測できる場合は、thinkingタグを閉じて、ツールの呼び出しに進みます。ただし、必須パラメータの値の1つが欠落している場合は、関数を呼び出さず(欠落しているパラメータにフィラーを使用しても)、代わりにユーザーに欠落しているパラメータの提供を求めてください。オプションのパラメータが提供されていない場合は、詳細情報を求めないでください。


JSONモード

ツールを実行したり関数に渡したりする意図がなくても、ツールを使用してClaudeにスキーマに従ったJSONの出力を生成させることができます。

この方法でツールを使用する場合:

  • 通常は単一のツールを提供します
  • tool_choiceを設定して(詳細はツール使用の強制を参照)、モデルにそのツールを明示的に使用するように指示します
  • モデルはinputをツールに渡すため、ツールの名前と説明はモデルの視点からのものであることを忘れないでください

以下では、record_summaryツールを使用して、特定の形式に従って画像を説明しています。

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: tools-2024-05-16" \
     --data \
'{
    "model": "claude-3-sonnet-20240229",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "整形式JSONを使用して画像の要約を記録する。",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "赤の値 [0.0, 1.0]" },
"g": { "type": "number", "description": "緑の値 [0.0, 1.0]" },
"b": { "type": "number", "description": "青の値 [0.0, 1.0]" },
"name": { "type": "string", "description": "スネークケースの人間が読める色の名前、例: \"olive_green\" や \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "画像の主要な色。4色未満に制限してください。"
                },
                "description": {
                    "type": "string",
                    "description": "画像の説明。最大2文まで。"
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "写真の場合、撮影された年の推定値。画像がノンフィクションであると思われる場合にのみ設定してください。おおよその推定で構いません!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "この画像を説明してください。"}
        ]}
    ]
}'