Claude 能夠與外部客戶端工具和函數互動,讓您可以為 Claude 配備自己的自定義工具來執行更廣泛的任務。

通過我們新的全面性工具使用課程學習掌握使用 Claude 進行工具使用所需的一切知識!請繼續使用此表單分享您的想法和建議。

以下是使用 Messages API 向 Claude 提供工具的示例:


工具使用的工作原理

通過以下步驟將外部工具與 Claude 整合:

1

向 Claude 提供工具和用戶提示

  • 在 API 請求中定義具有名稱、描述和輸入模式的工具。
  • 包含可能需要這些工具的用戶提示,例如”舊金山的天氣如何?”
2

Claude 決定使用工具

  • Claude 評估是否有任何工具可以幫助回答用戶的查詢。
  • 如果是,Claude 構建一個格式正確的工具使用請求。
  • API 響應的 stop_reasontool_use,表示 Claude 的意圖。
3

提取工具輸入、運行代碼並返回結果

  • 在您的端,從 Claude 的請求中提取工具名稱和輸入。
  • 在客戶端執行實際的工具代碼。
  • 繼續對話,發送一條包含 tool_result 內容塊的新 user 消息。
4

Claude 使用工具結果制定回應

  • Claude 分析工具結果,為原始用戶提示製作最終回應。

注意:步驟 3 和 4 是可選的。對於某些工作流程,Claude 的工具使用請求(步驟 2)可能就是您所需要的全部,無需將結果發送回 Claude。

所有工具都由用戶提供

需要注意的是,Claude 沒有訪問任何內置的服務器端工具。所有工具都必須由您(用戶)在每個 API 請求中明確提供。這使您可以完全控制和靈活地決定 Claude 可以使用的工具。


如何實現工具使用

選擇模型

通常,對於複雜的工具和模糊的查詢,使用 Claude 3 Opus;它能更好地處理多個工具,並在需要時尋求澄清。

對於簡單的工具使用 Haiku,但請注意它可能會推斷缺失的參數。

指定工具

工具在 API 請求的頂層 tools 參數中指定。每個工具定義包括:

參數描述
name工具的名稱。必須匹配正則表達式 ^[a-zA-Z0-9_-]{1,64}$
description詳細的純文本描述,說明工具的功能、何時應該使用以及其行為方式。
input_schema一個 JSON Schema 對象,定義工具的預期參數。

工具定義的最佳實踐

要在使用工具時獲得 Claude 的最佳性能,請遵循以下指南:

  • 提供極其詳細的描述。 這是影響工具性能的最重要因素。您的描述應該解釋工具的每個細節,包括:
    • 工具的功能
    • 何時應該使用(以及何時不應該使用)
    • 每個參數的含義及其如何影響工具的行為
    • 任何重要的注意事項或限制,例如如果工具名稱不清楚,該工具不返回哪些信息。您能為 Claude 提供的關於工具的上下文越多,它就越能更好地決定何時以及如何使用它們。每個工具描述至少應該有 3-4 句話,如果工具複雜,則需要更多。
  • 優先考慮描述而非示例。 雖然您可以在工具的描述或附帶的提示中包含如何使用工具的示例,但這不如對工具的目的和參數有清晰全面的解釋重要。只有在充分闡述描述後才添加示例。

良好的描述清楚地解釋了工具的功能、何時使用、返回什麼數據以及 ticker 參數的含義。糟糕的描述過於簡短,讓 Claude 對工具的行為和用法產生了許多疑問。

控制 Claude 的輸出

強制使用工具

在某些情況下,您可能希望 Claude 使用特定的工具來回答用戶的問題,即使 Claude 認為它可以在不使用工具的情況下提供答案。您可以通過在 tool_choice 字段中指定工具來實現這一點,如下所示:

tool_choice = {"type": "tool", "name": "get_weather"}

在使用 tool_choice 參數時,我們有三種可能的選項:

  • auto 允許 Claude 決定是否調用任何提供的工具。這是默認值。
  • any 告訴 Claude 它必須使用提供的工具之一,但不強制使用特定工具。
  • tool 允許我們強制 Claude 始終使用特定工具。

這張圖說明了每個選項的工作原理:

請注意,當您將 tool_choice 設置為 anytool 時,我們會預填助手消息以強制使用工具。這意味著即使明確要求,模型也不會在 tool_use 內容塊之前發出鏈式思考的 text 內容塊。

我們的測試表明,這不應該降低性能。如果您希望保持鏈式思考(特別是使用 Opus)的同時仍要求模型使用特定工具,您可以將 tool_choice 設置為 {"type": "auto"} (默認值),並在 user 消息中添加明確的指示。例如:What's the weather like in London? Use the get_weather tool in your response.

JSON 輸出

工具不一定需要是客戶端函數 — 只要您希望模型返回遵循提供的模式的 JSON 輸出,就可以使用工具。例如,您可以使用具有特定模式的 record_summary 工具。請參閱工具使用示例以獲取完整的工作示例。

思維鏈

在使用工具時,Claude 通常會展示其”思維鏈”,即用於分解問題和決定使用哪些工具的逐步推理。如果 tool_choice 設置為 auto (這是默認值,請參閱強制使用工具),Claude 3 Opus 模型會這樣做,而 Sonnet 和 Haiku 可以被提示這樣做。

例如,給定提示 “What’s the weather like in San Francisco right now, and what time is it there?“,Claude 可能會回應:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

這種思維鏈讓我們洞察 Claude 的推理過程,可以幫助您調試意外行為。

對於 Claude 3 Sonnet 模型,默認情況下思維鏈不太常見,但您可以通過在用戶消息或系統提示中添加類似 "Before answering, explain your reasoning step-by-step in tags." 的內容來提示 Claude 展示其推理過程。

重要的是要注意,雖然 <thinking> 標籤是 Claude 用來表示其思維鏈的常見約定,但確切的格式(例如這個 XML 標籤的名稱)可能會隨時間而改變。您的代碼應該將思維鏈視為任何其他助手生成的文本,而不應依賴 <thinking> 標籤的存在或特定格式。

處理工具使用和工具結果內容塊

當 Claude 決定使用您提供的工具之一時,它會返回一個 stop_reasontool_use 的響應,並在 API 響應中包含一個或多個 tool_use 內容塊,其中包括:

  • id: 這個特定工具使用塊的唯一標識符。這將用於稍後匹配工具結果。
  • name: 正在使用的工具的名稱。
  • input: 一個包含傳遞給工具的輸入的對象,符合工具的 input_schema

當您收到工具使用響應時,您應該:

  1. tool_use 塊中提取 nameidinput
  2. 在您的代碼庫中運行與該工具名稱對應的實際工具,傳入工具 input
  3. [可選] 通過發送一條新的 roleuser 的消息繼續對話,並包含一個 content 塊,其中包含 tool_result 類型和以下信息:
    • tool_use_id: 這是結果對應的工具使用請求的 id
    • content: 工具的結果,可以是字符串(例如 "content": "15 degrees")或嵌套內容塊的列表(例如 "content": [{"type": "text", "text": "15 degrees"}])。這些內容塊可以使用 textimage 類型。
    • is_error (可選): 如果工具執行導致錯誤,則設置為 true

在收到工具結果後,Claude 將使用該信息繼續生成對原始用戶提示的回應。

與其他 API 的區別

與將工具使用分開或使用特殊角色如 toolfunction 的 API 不同,Anthropic 的 API 將工具直接整合到 userassistant 消息結構中。

消息包含 textimagetool_usetool_result 塊的數組。user 消息包括客戶端內容和 tool_result,而 assistant 消息包含 AI 生成的內容和 tool_use

錯誤排除

在使用 Claude 的工具時,可能會出現幾種不同類型的錯誤:


工具使用示例

以下是一些代碼示例,展示了各種工具使用模式和技巧。為了簡潔起見,這些工具都是簡單的工具,工具描述也比理想情況下短,以確保最佳性能。


定價

工具使用請求的定價與任何其他 Claude API 請求相同,基於發送給模型的總輸入令牌數(包括 tools 參數中的令牌)和生成的輸出令牌數。

工具使用帶來的額外令牌來自:

  • API 請求中的 tools 參數(工具名稱、描述和模式)
  • API 請求和響應中的 tool_use 內容塊
  • API 請求中的 tool_result 內容塊

當您使用 tools 時,我們還會自動為模型包含一個特殊的系統提示,以啟用工具使用。每個模型所需的工具使用令牌數量如下所列(不包括上面列出的額外令牌):

模型工具選擇工具使用系統提示令牌數
Claude 3.5 Sonnetauto
any, tool
294 個令牌
261 個令牌
Claude 3 Opusauto
any, tool
530 個令牌
281 個令牌
Claude 3 Sonnetauto
any, tool
159 個令牌
235 個令牌
Claude 3 Haikuauto
any, tool
264 個令牌
340 個令牌

這些令牌數會加到您的正常輸入和輸出令牌中,以計算請求的總成本。請參考我們的模型概覽表以獲取當前每個模型的價格。

當您發送工具使用提示時,就像任何其他 API 請求一樣,響應將輸出輸入和輸出令牌數作為報告的 usage 指標的一部分。


下一步

探索我們的工具使用代碼示例存儲庫,這些示例可以直接實施: