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

單一工具

此範例展示了一個基本的單一工具情況,使用 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 函數,用戶想要舊金山的天氣,舊金山很可能是指加州的 San Francisco。</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,用戶想要舊金山的天氣,舊金山很可能是指加州的 San Francisco。</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_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_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 "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 來獲取最終答案。

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

角色內容
用戶我所在地的天氣如何?
助手<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),多雲” 的結果]
助手根據您目前在加州舊金山的位置,現在的天氣是華氏 59 度(攝氏 15 度),多雲。這是一個相當涼爽和多雲的日子。如果您要出門,可能需要帶一件輕薄的外套。

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

  1. Claude 首先意識到它需要用戶的位置來回答天氣問題,所以它調用了 get_location 工具。
  2. 用戶(即客戶端程式碼)執行實際的 get_location 函數,並在 tool_result 區塊中返回結果 “San Francisco, CA”。
  3. 現在已知位置,Claude 繼續調用 get_weather 工具,將 “San Francisco, CA” 作為 location 參數傳遞(以及一個猜測的 unit 參數,因為 unit 不是必需參數)。
  4. 用戶再次使用提供的參數執行實際的 get_weather 函數,並在另一個 tool_result 區塊中返回天氣資料。
  5. 最後,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" \
     --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": "圖像中的關鍵顏色。限制在四種以下。"
                },
                "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": "描述這張圖片。"}
        ]}
    ]
}'