如何實現工具使用
學習如何在 Claude 中實現工具使用功能,包括選擇模型、指定工具、控制輸出和處理錯誤。
選擇模型
一般來說,對於複雜工具和模糊查詢,請使用 Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5 或 Claude Opus 3;它們能更好地處理多個工具,並在需要時尋求澄清。
對於簡單的工具,請使用 Claude Haiku 3.5 或 Claude Haiku 3,但請注意它們可能會推斷缺失的參數。
如果使用 Claude Sonnet 3.7 進行工具使用和擴展思考,請參考我們的指南這裡以獲取更多資訊。
指定客戶端工具
客戶端工具(包括 Anthropic 定義的和用戶定義的)在 API 請求的 tools
頂級參數中指定。每個工具定義包括:
參數 | 描述 |
---|---|
name | 工具的名稱。必須符合正則表達式 ^[a-zA-Z0-9_-]{1,64}$ 。 |
description | 工具功能、使用時機和行為的詳細純文本描述。 |
input_schema | 定義工具預期參數的 JSON Schema 物件。 |
工具使用系統提示
當您使用 tools
參數調用 Anthropic API 時,我們會從工具定義、工具配置和任何用戶指定的系統提示構建一個特殊的系統提示。構建的提示旨在指導模型使用指定的工具並為工具正常運行提供必要的上下文:
工具定義的最佳實踐
為了在使用工具時獲得 Claude 的最佳性能,請遵循以下準則:
- 提供極其詳細的描述。 這是影響工具性能的最重要因素。您的描述應該解釋工具的每個細節,包括:
- 工具的功能
- 何時應該使用(以及何時不應該使用)
- 每個參數的含義以及它如何影響工具的行為
- 任何重要的注意事項或限制,例如如果工具名稱不清楚,工具不會返回什麼資訊。您能為 Claude 提供的關於工具的上下文越多,它在決定何時以及如何使用工具方面就會表現得越好。每個工具描述至少要 3-4 句話,如果工具複雜則需要更多。
- 優先考慮描述而非範例。 雖然您可以在工具描述或附帶提示中包含如何使用工具的範例,但這不如清楚全面地解釋工具的目的和參數重要。只有在完全充實描述後才添加範例。
良好的描述清楚地解釋了工具的功能、使用時機、返回的數據以及 ticker
參數的含義。糟糕的描述過於簡短,讓 Claude 對工具的行為和使用方式有很多疑問。
控制 Claude 的輸出
強制工具使用
在某些情況下,您可能希望 Claude 使用特定工具來回答用戶的問題,即使 Claude 認為它可以在不使用工具的情況下提供答案。您可以通過在 tool_choice
欄位中指定工具來實現:
使用 tool_choice 參數時,我們有四個可能的選項:
auto
允許 Claude 決定是否調用任何提供的工具。這是提供tools
時的預設值。any
告訴 Claude 必須使用提供的工具之一,但不強制使用特定工具。tool
允許我們強制 Claude 始終使用特定工具。none
阻止 Claude 使用任何工具。這是未提供tools
時的預設值。
使用提示快取時,對 tool_choice
參數的更改將使快取的訊息區塊失效。工具定義和系統提示保持快取,但訊息內容必須重新處理。
此圖表說明了每個選項的工作原理:
請注意,當您將 tool_choice
設為 any
或 tool
時,我們會預填助手訊息以強制使用工具。這意味著模型不會在 tool_use
內容區塊之前發出思維鏈 text
內容區塊,即使明確要求這樣做。
使用擴展思考與工具使用時,不支援 tool_choice: {"type": "any"}
和 tool_choice: {"type": "tool", "name": "..."}
並會導致錯誤。只有 tool_choice: {"type": "auto"}
(預設值)和 tool_choice: {"type": "none"}
與擴展思考相容。
我們的測試表明這不應該降低性能。如果您希望保持思維鏈(特別是對於 Opus)同時仍要求模型使用特定工具,您可以對 tool_choice
使用 {"type": "auto"}
(預設值)並在 user
訊息中添加明確指示。例如:倫敦的天氣如何?在您的回應中使用 get_weather 工具。
JSON 輸出
工具不一定需要是客戶端函數——您可以在任何希望模型返回遵循提供架構的 JSON 輸出時使用工具。例如,您可能使用具有特定架構的 record_summary
工具。請參閱使用 Claude 的工具使用以獲取完整的工作範例。
思維鏈
使用工具時,Claude 通常會顯示其「思維鏈」,即它用來分解問題並決定使用哪些工具的逐步推理。如果 tool_choice
設為 auto
(這是預設值,請參閱強制工具使用),Claude Opus 3 模型會這樣做,而 Sonnet 和 Haiku 可以通過提示來做到這一點。
例如,給定提示「舊金山現在的天氣如何,那裡現在是什麼時間?」,Claude 可能會回應:
這種思維鏈提供了對 Claude 推理過程的洞察,可以幫助您調試意外行為。
對於 Claude Sonnet 3 模型,思維鏈預設較少見,但您可以通過在用戶訊息或系統提示中添加類似「在回答之前,請在標籤中逐步解釋您的推理。」來提示 Claude 顯示其推理。
重要的是要注意,雖然 <thinking>
標籤是 Claude 用來表示其思維鏈的常見慣例,但確切的格式(例如此 XML 標籤的名稱)可能會隨時間變化。您的程式碼應該將思維鏈視為任何其他助手生成的文本,而不應依賴 <thinking>
標籤的存在或特定格式。
並行工具使用
預設情況下,Claude 可能使用多個工具來回答用戶查詢。您可以通過以下方式禁用此行為:
- 當 tool_choice 類型為
auto
時設定disable_parallel_tool_use=true
,這確保 Claude 最多使用一個工具 - 當 tool_choice 類型為
any
或tool
時設定disable_parallel_tool_use=true
,這確保 Claude 恰好使用一個工具
最大化並行工具使用
雖然 Claude 4 模型預設具有出色的並行工具使用能力,但您可以通過有針對性的提示在所有模型中增加並行工具執行的可能性:
處理工具使用和工具結果內容區塊
Claude 的回應根據它使用客戶端還是伺服器工具而有所不同。
處理客戶端工具的結果
回應將有 tool_use
的 stop_reason
和一個或多個 tool_use
內容區塊,包括:
id
:此特定工具使用區塊的唯一識別符。這將用於稍後匹配工具結果。name
:正在使用的工具名稱。input
:包含傳遞給工具的輸入的物件,符合工具的input_schema
。
當您收到客戶端工具的工具使用回應時,您應該:
- 從
tool_use
區塊中提取name
、id
和input
。 - 在您的程式碼庫中運行與該工具名稱對應的實際工具,傳入工具
input
。 - 通過發送一條新訊息繼續對話,該訊息的
role
為user
,content
區塊包含tool_result
類型和以下資訊:tool_use_id
:這是工具使用請求結果的id
。content
:工具的結果,作為字串(例如"content": "15 degrees"
)或嵌套內容區塊列表(例如"content": [{"type": "text", "text": "15 degrees"}]
)。這些內容區塊可以使用text
或image
類型。is_error
(可選):如果工具執行導致錯誤,則設為true
。
重要的格式要求:
- 工具結果區塊必須在訊息歷史中緊跟其對應的工具使用區塊。您不能在助手的工具使用訊息和用戶的工具結果訊息之間包含任何訊息。
- 在包含工具結果的用戶訊息中,tool_result 區塊必須在內容陣列中排在第一位。任何文本都必須在所有工具結果之後。
例如,這將導致 400 錯誤:
這是正確的:
如果您收到類似「在工具使用 id 後立即找不到工具結果區塊」的錯誤,請檢查您的工具結果格式是否正確。
收到工具結果後,Claude 將使用該資訊繼續生成對原始用戶提示的回應。
處理伺服器工具的結果
Claude 在內部執行工具並將結果直接納入其回應中,無需額外的用戶互動。
與其他 API 的差異
與分離工具使用或使用特殊角色如 tool
或 function
的 API 不同,Anthropic 的 API 將工具直接整合到 user
和 assistant
訊息結構中。
訊息包含 text
、image
、tool_use
和 tool_result
區塊的陣列。user
訊息包括客戶端內容和 tool_result
,而 assistant
訊息包含 AI 生成的內容和 tool_use
。
處理 max_tokens
停止原因
如果 Claude 的回應因達到 max_tokens
限制而被截斷,並且截斷的回應包含不完整的工具使用區塊,您需要使用更高的 max_tokens
值重試請求以獲得完整的工具使用。
處理 pause_turn
停止原因
使用網路搜尋等伺服器工具時,API 可能返回 pause_turn
停止原因,表示 API 已暫停長時間運行的回合。
以下是如何處理 pause_turn
停止原因:
處理 pause_turn
時:
- 繼續對話:在後續請求中按原樣傳回暫停的回應,讓 Claude 繼續其回合
- 如需要可修改:如果您想中斷或重定向對話,可以選擇在繼續之前修改內容
- 保持工具狀態:在繼續請求中包含相同的工具以維持功能
錯誤疑難排解
使用 Claude 的工具時可能會發生幾種不同類型的錯誤: