工具使用範例

以下是一些程式碼範例，示範各種工具使用模式和技巧。為了簡潔起見，這些工具是簡單的工具，工具描述也比理想情況下要短，以確保最佳效能。請參閱指定工具以獲得更多資訊。

單一工具

此範例展示了一個基本的單一工具情況，使用 get_weather 工具。

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --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，可能是 San Francisco, CA。</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 "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，可能是 San Francisco, CA。</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，特別是 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 沒有足夠的上下文來填充必需的參數，它更有可能回應一個澄清問題，而不是進行工具調用。

多個工具

您可以在單個請求中為 Claude 提供多個工具供其選擇。以下是一個同時使用 get_weather 和 get_time 工具的範例，以及一個詢問兩者的用戶查詢。

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --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_weather 然後是 get_time — 以完全回答用戶的問題。然而，它有時也會一次輸出兩個 tool_use 區塊，特別是如果它們彼此不相依。您需要執行每個工具，並在單個 user 訊息中的單獨 tool_result 區塊中返回它們的結果。

順序工具

某些任務可能需要按順序調用多個工具，使用一個工具的輸出作為另一個工具的輸入。在這種情況下，Claude 將一次調用一個工具。如果提示一次調用所有工具，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 "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 來獲取最終答案。

完整的對話可能如下所示：

角色	內容
用戶	我所在地的天氣如何？
助手	<thinking>要回答這個問題，我首先需要使用 get_location 工具確定用戶的位置。然後我可以將該位置傳遞給 get_weather 工具，找到那裡的當前天氣。</thinking>[get_location 的工具使用]
用戶	[get_location 的工具結果，帶有匹配的 ID 和 San Francisco, CA 的結果]
助手	[get_weather 的工具使用，帶有以下輸入]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
用戶	[get_weather 的工具結果，帶有匹配的 ID 和 “59°F (15°C)，大部分多雲” 的結果]
助手	根據您目前在 San Francisco, CA 的位置，現在的天氣是 59°F (15°C)，大部分多雲。這是城市中相當涼爽和陰天的一天。如果您要出門，可能需要帶一件輕薄的外套。

此範例展示了 Claude 如何將多個工具調用串聯在一起，以回答需要從不同來源收集資料的問題。關鍵步驟是：

Claude 首先意識到它需要用戶的位置來回答天氣問題，所以它調用 get_location 工具。
用戶（即客戶端程式碼）執行實際的 get_location 函數，並在 tool_result 區塊中返回結果 “San Francisco, CA”。
現在已知位置，Claude 繼續調用 get_weather 工具，將 “San Francisco, CA” 作為 location 參數傳遞（以及一個猜測的 unit 參數，因為 unit 不是必需參數）。
用戶再次使用提供的引數執行實際的 get_weather 函數，並在另一個 tool_result 區塊中返回天氣資料。
最後，Claude 將天氣資料納入自然語言回應，以回答原始問題。

思路鏈工具使用

預設情況下，Claude 3 Opus 會在回答工具使用查詢之前進行思考，以最佳方式確定是否需要工具、使用哪個工具以及適當的參數。Claude 3 Sonnet 和 Claude 3 Haiku 會盡可能多地嘗試使用工具，更有可能調用不必要的工具或推斷缺失的參數。要提示 Sonnet 或 Haiku 在進行工具調用之前更好地評估用戶查詢，可以使用以下提示：

思路鏈提示

使用相關工具（如果有）回答用戶的請求。在調用工具之前，在 \<thinking>\</thinking> 標籤內進行一些分析。首先，考慮提供的工具中哪一個是回答用戶請求的相關工具。其次，檢查相關工具的每個必需參數，確定用戶是否直接提供或給出足夠的資訊來推斷值。在決定是否可以推斷參數時，仔細考慮所有上下文，看它是否支持特定值。如果所有必需參數都存在或可以合理推斷，關閉思考標籤並繼續進行工具調用。但是，如果缺少必需參數的值之一，請不要調用函數（即使使用缺失參數的填充值），而是要求用戶提供缺失的參數。如果未提供可選參數的更多資訊，請不要詢問。

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" \
     --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": "圖像中的關鍵顏色。限制在四種以下。"
                },
                "description": {
                    "type": "string",
                    "description": "圖像描述。最多一到兩句話。"
                },
                "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": "描述這張圖片。"}
        ]}
    ]
}'

開始使用

Capabilities

Performance enhancement

生產指南

工具使用範例

單一工具

缺少資訊

多個工具

順序工具

思路鏈工具使用

JSON 模式

開始使用

Capabilities

Performance enhancement

生產指南

​單一工具

​缺少資訊

​多個工具

​順序工具

​思路鏈工具使用

​JSON 模式

單一工具

缺少資訊

多個工具

順序工具

思路鏈工具使用

JSON 模式