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 可以使用的工具。

電腦使用(測試版)功能是一個例外 - 它引入了由 Anthropic 提供但由您(用戶)實現的工具。


如何實現工具使用

選擇模型

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

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

指定工具

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

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

工具使用系統提示

當您使用 tools 參數呼叫 Anthropic API 時,我們會從工具定義、工具配置和任何用戶指定的系統提示構建一個特殊的系統提示。構建的提示旨在指導模型使用指定的工具並提供工具正常運作所需的必要上下文:

在這個環境中,您可以使用一組工具來回答用戶的問題。
{{ 格式說明 }}
字串和標量參數應按原樣指定,而列表和物件應使用 JSON 格式。請注意,字串值的空格不會被去除。輸出不需要是有效的 XML,而是使用正則表達式解析。
以下是 JSONSchema 格式的可用函數:
{{ JSON SCHEMA 格式的工具定義 }}
{{ 用戶系統提示 }}
{{ 工具配置 }}

工具定義的最佳實踐

要在使用工具時獲得最佳性能,請遵循以下準則:

  • 提供極其詳細的描述。 這是影響工具性能最重要的因素。您的描述應該解釋工具的每個細節,包括:
    • 工具的功能
    • 何時應該使用(以及何時不應該使用)
    • 每個參數的含義及其如何影響工具的行為
    • 任何重要的注意事項或限制,例如如果工具名稱不清楚,工具不會返回什麼信息。您能為 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 訊息中添加明確的指示。例如:倫敦的天氣如何?在您的回應中使用 get_weather 工具。

JSON 輸出

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

思維鏈

在使用工具時,Claude 通常會顯示其「思維鏈」,即它用來分解問題並決定使用哪些工具的逐步推理。如果 tool_choice 設置為 auto(這是預設值,請參閱強制使用工具),Claude 3 Opus 模型會這樣做,而 Sonnet 和 Haiku 可以通過提示來實現這一點。

例如,對於提示「舊金山現在的天氣如何,那裡現在是幾點?」,Claude 可能會回應:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>要回答這個問題,我將:1. 使用 get_weather 工具獲取舊金山的當前天氣。2. 使用 get_time 工具獲取 America/Los_Angeles 時區(覆蓋加州舊金山)的當前時間。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

這個思維鏈讓我們了解 Claude 的推理過程,並可以幫助您調試意外行為。

對於 Claude 3 Sonnet 模型,思維鏈在預設情況下較少出現,但您可以通過在用戶訊息或系統提示中添加類似「在回答之前,請在標籤中逐步解釋您的推理。」的內容來提示 Claude 顯示其推理。

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

禁用並行工具使用

預設情況下,Claude 可能會使用多個工具來回答用戶查詢。您可以通過在 tool_choice 字段中設置 disable_parallel_tool_use=true 來禁用此行為。

  • tool_choice 類型為 auto 時,這確保 Claude 最多使用一個工具
  • tool_choice 類型為 anytool 時,這確保 Claude 恰好使用一個工具

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

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

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

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

  1. tool_use 區塊中提取 nameidinput
  2. 在您的代碼庫中運行與該工具名稱對應的實際工具,傳入工具 input
  3. [可選] 通過發送一個 roleuser 的新訊息繼續對話,並包含一個包含以下信息的 tool_result 類型的 content 區塊:
    • tool_use_id:這是結果對應的工具使用請求的 id
    • content:工具的結果,可以是字串(例如 "content": "15 度")或嵌套內容區塊的列表(例如 "content": [{"type": "text", "text": "15 度"}])。這些內容區塊可以使用 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 Sonnet (Oct)auto
any, tool
346 令牌
313 令牌
Claude 3 Opusauto
any, tool
530 令牌
281 令牌
Claude 3 Sonnetauto
any, tool
159 令牌
235 令牌
Claude 3 Haikuauto
any, tool
264 令牌
340 令牌
Claude 3.5 Sonnet (June)auto
any, tool
294 令牌
261 令牌

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

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


下一步

探索我們存儲庫中現成可實現的工具使用代碼示例:

Was this page helpful?