工具使用(函數呼叫)

如果工具本身在執行過程中拋出錯誤(例如,在獲取天氣數據時出現網絡錯誤),您可以在 content 中返回錯誤消息,並設置 "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

然後 Claude 會將這個錯誤納入其對用戶的回應中,例如 “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”

如果由於達到 max_tokens 限制而導致 Claude 的回應被截斷,並且截斷的回應包含不完整的工具使用塊,您需要使用更高的 max_tokens 值重試請求以獲取完整的工具使用。

如果 Claude 嘗試使用的工具無效(例如缺少必需的參數),這通常意味著 Claude 沒有足夠的信息來正確使用該工具。在開發過程中,您最好的選擇是嘗試在工具定義中使用更詳細的 description 值重新發送請求。

然而,您也可以繼續對話,發送一個表示錯誤的 tool_result,Claude 將嘗試再次使用該工具,並填寫缺失的信息:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

如果工具請求無效或缺少參數,Claude 將嘗試修正 2-3 次,然後向用戶道歉。

為了防止 Claude 使用 <search_quality_reflection> 標籤反思搜索質量,請在您的提示中添加 “Do not reflect on the quality of the returned search results in your response”。

Claude 將返回類似以下的響應:

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9", 
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

然後您需要使用提供的輸入執行 get_weather 函數,並在新的 user 消息中返回結果:

這將打印 Claude 的最終回應,其中包含天氣數據:

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

您可以在單個請求中向 Claude 提供多個工具供選擇。以下是一個同時包含 get_weather 和 get_time 工具的示例,以及一個詢問兩者的用戶查詢。

在這種情況下,Claude 很可能會嘗試一次使用兩個單獨的工具 — get_weather 然後是 get_time — 以完全回答用戶的問題。然而,如果它們不相互依賴,它偶爾也會一次輸出兩個 tool_use 塊。您需要執行每個工具並在單個 user 消息中的單獨 tool_result 塊中返回它們的結果。

如果用戶的提示中沒有包含足夠的信息來填充工具的所有必需參數,Claude 3 Opus 更有可能認識到缺少參數並詢問。Claude 3 Sonnet 可能會詢問,特別是在被提示在輸出工具請求之前思考時。但它也可能會盡力推斷一個合理的值。

例如,使用上面的 get_weather 工具,如果您問 Claude “What’s the weather?” 而沒有指定位置,Claude,特別是 Claude 3 Sonnet,可能會對工具輸入進行猜測:

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

這種行為並不能保證,特別是對於更模糊的提示和不如 Claude 3 Opus 智能的模型。如果 Claude 3 Opus 沒有足夠的上下文來填充必需的參數,它更有可能回應一個澄清問題,而不是進行工具調用。

某些任務可能需要按順序調用多個工具,使用一個工具的輸出作為另一個工具的輸入。在這種情況下,Claude 將一次調用一個工具。如果被提示一次調用所有工具,Claude 可能會猜測下游工具的參數,如果它們依賴於上游工具的結果。

以下是使用 get_location 工具獲取用戶位置,然後將該位置傳遞給 get_weather 工具的示例:

在這種情況下,Claude 會首先調用 get_location 工具來獲取用戶的位置。在您在 tool_result 中返回位置後,Claude 會使用該位置調用 get_weather 以獲得最終答案。

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

這個例子展示了 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 在進行工具調用之前更好地評估用戶查詢,可以使用以下提示:

思維鏈提示

Answer the user's request using relevant tools (if they are available). Before calling a tool, do some analysis within \<thinking>\</thinking> tags. First, think about which of the provided tools is the relevant tool to answer the user's request. Second, go through each of the required parameters of the relevant tool and determine if the user has directly provided or given enough information to infer a value. When deciding if the parameter can be inferred, carefully consider all the context to see if it supports a specific value. If all of the required parameters are present or can be reasonably inferred, close the thinking tag and proceed with the tool call. BUT, if one of the values for a required parameter is missing, DO NOT invoke the function (not even with fillers for the missing params) and instead, ask the user to provide the missing parameters. DO NOT ask for more information on optional parameters if it is not provided.

您可以使用工具讓 Claude 生成遵循模式的 JSON 輸出,即使您沒有打算將該輸出通過工具或函數運行。

以這種方式使用工具時:

• 您通常希望提供單個工具
• 您應該設置 tool_choice (參見強制使用工具)以指示模型明確使用該工具
• 請記住,模型將把 input 傳遞給工具,所以工具的名稱和描述應該從模型的角度來看。

以下使用 record_summary 工具按特定格式描述圖像。