選擇模型
我們建議對複雜工具和模糊查詢使用最新的 Claude Sonnet (4.5) 或 Claude Opus (4.1) 模型;它們能更好地處理多個工具並在需要時尋求澄清。 對於直接的工具使用 Claude Haiku 模型,但請注意它們可能會推斷缺失的參數。如果使用 Claude 進行工具使用和擴展思考,請參考我們的指南 此處 以獲取更多信息。
指定客戶端工具
客戶端工具(包括 Anthropic 定義的和用戶定義的)在 API 請求的tools 頂級參數中指定。每個工具定義包括:
| 參數 | 描述 |
|---|---|
name | 工具的名稱。必須符合正則表達式 ^[a-zA-Z0-9_-]{1,64}$。 |
description | 工具功能、何時應使用以及其行為方式的詳細純文本描述。 |
input_schema | 定義工具預期參數的 JSON Schema 對象。 |
簡單工具定義示例
簡單工具定義示例
JSON
get_weather,期望輸入對象包含必需的 location 字符串和可選的 unit 字符串,該字符串必須是「celsius」或「fahrenheit」之一。工具使用系統提示
當您使用tools 參數調用 Claude API 時,我們從工具定義、工具配置和任何用戶指定的系統提示構建特殊系統提示。構建的提示旨在指示模型使用指定的工具並為工具正確運行提供必要的上下文:
工具定義的最佳實踐
為了從使用工具的 Claude 中獲得最佳性能,請遵循以下指南:- 提供極其詳細的描述。 這是迄今為止影響工具性能的最重要因素。您的描述應解釋有關工具的每個細節,包括:
- 工具的功能
- 何時應使用它(以及何時不應使用)
- 每個參數的含義以及它如何影響工具的行為
- 任何重要的注意事項或限制,例如如果工具名稱不清楚,工具不會返回什麼信息。您能為 Claude 提供的有關工具的上下文越多,它在決定何時以及如何使用它們時就會越好。每個工具描述至少應有 3-4 句話,如果工具複雜則更多。
- 優先考慮描述而不是示例。 雖然您可以在工具描述或附帶提示中包含如何使用工具的示例,但這不如清晰全面的工具目的和參數說明重要。只有在完全充實描述後才添加示例。
良好工具描述示例
良好工具描述示例
JSON
工具描述不佳示例
工具描述不佳示例
JSON
ticker 參數的含義。不佳的描述過於簡潔,讓 Claude 對工具的行為和使用方式有許多疑問。
工具運行器(測試版)
工具運行器為使用 Claude 執行工具提供了開箱即用的解決方案。工具運行器不是手動處理工具調用、工具結果和對話管理,而是自動:- 在 Claude 調用工具時執行工具
- 處理請求/響應週期
- 管理對話狀態
- 提供類型安全性和驗證
工具運行器目前處於測試版,僅在 Python 和 TypeScript SDK 中可用。
基本用法
使用 裝飾的函數必須返回內容區塊或內容區塊數組,包括文本、圖像或文檔區塊。這允許工具返回豐富的多模態響應。返回的字符串將轉換為文本內容區塊。
如果您想向 Claude 返回結構化 JSON 對象,請在返回前將其編碼為 JSON 字符串。數字、布爾值或其他非字符串基元也必須轉換為字符串。
@beta_tool 裝飾器定義工具,並使用 client.beta.messages.tool_runner() 執行它們。如果您使用異步客戶端,請將
@beta_tool 替換為 @beta_async_tool 並使用 async def 定義函數。@beta_tool 裝飾器將檢查函數參數和文檔字符串,以提取給定函數的 json 模式表示,在上面的示例中 calculate_sum 將轉換為:SDK 工具運行器處於測試版。本文檔的其餘部分涵蓋手動工具實現。
控制 Claude 的輸出
強制工具使用
在某些情況下,您可能希望 Claude 使用特定工具來回答用戶的問題,即使 Claude 認為它可以在不使用工具的情況下提供答案。您可以通過在tool_choice 字段中指定工具來執行此操作,如下所示:
auto允許 Claude 決定是否調用任何提供的工具。這是提供tools時的默認值。any告訴 Claude 它必須使用提供的工具之一,但不強制特定工具。tool允許我們強制 Claude 始終使用特定工具。none防止 Claude 使用任何工具。這是未提供tools時的默認值。
使用 提示緩存 時,對
tool_choice 參數的更改將使緩存的消息區塊失效。工具定義和系統提示保持緩存,但消息內容必須重新處理。
tool_choice 為 any 或 tool 時,我們將預填充助手消息以強制使用工具。這意味著模型不會在 tool_use 內容區塊之前發出自然語言響應或解釋,即使被明確要求這樣做。
使用 擴展思考 與工具使用時,不支持
tool_choice: {"type": "any"} 和 tool_choice: {"type": "tool", "name": "..."} 並將導致錯誤。只有 tool_choice: {"type": "auto"} (默認值)和 tool_choice: {"type": "none"} 與擴展思考兼容。tool_choice 使用 {"type": "auto"} (默認值),並在 user 消息中添加明確的指示。例如:倫敦的天氣如何?在您的回應中使用 get_weather 工具。
JSON 輸出
工具不一定需要是客戶端函數 — 您可以在任何時候想要模型返回遵循提供的模式的 JSON 輸出時使用工具。例如,您可能使用具有特定模式的record_summary 工具。有關完整的工作示例,請參閱 使用 Claude 的工具使用。
使用工具的模型響應
使用工具時,Claude 通常會評論它正在做什麼或在調用工具之前自然地回應用戶。 例如,給定提示「舊金山現在的天氣如何,那裡現在幾點?」,Claude 可能會回應:JSON
<examples> 來指導這些響應的風格和內容。
重要的是要注意,Claude 在解釋其行為時可能使用各種措辭和方法。您的代碼應將這些響應視為任何其他助手生成的文本,並且不應依賴特定的格式約定。
並行工具使用
默認情況下,Claude 可能使用多個工具來回答用戶查詢。您可以通過以下方式禁用此行為:- 當 tool_choice 類型為
auto時設置disable_parallel_tool_use=true,這確保 Claude 最多使用 一個 工具 - 當 tool_choice 類型為
any或tool時設置disable_parallel_tool_use=true,這確保 Claude 使用 恰好一個 工具
完整的並行工具使用示例
完整的並行工具使用示例
使用工具運行器更簡單:下面的示例展示了手動並行工具處理。對於大多數用例,工具運行器 自動處理並行工具執行,代碼少得多。
並行工具的完整測試腳本
並行工具的完整測試腳本
以下是一個完整的、可運行的腳本,用於測試和驗證並行工具調用是否正常工作:此腳本演示了:
- 如何正確格式化並行工具調用和結果
- 如何驗證正在進行並行調用
- 鼓勵未來並行工具使用的正確消息結構
- 要避免的常見錯誤(如工具結果之前的文本)
最大化並行工具使用
雖然 Claude 4 模型默認具有出色的並行工具使用功能,但您可以通過有針對性的提示在所有模型中增加並行工具執行的可能性:並行工具使用的系統提示
並行工具使用的系統提示
對於 Claude 4 模型(Opus 4.1、Opus 4 和 Sonnet 4),將以下內容添加到您的系統提示:為了獲得更強的並行工具使用(如果默認值不夠,建議使用),請使用:
用戶消息提示
用戶消息提示
您也可以在特定用戶消息中鼓勵並行工具使用:
處理工具使用和工具結果內容區塊
使用工具運行器更簡單:本節中描述的手動工具處理由 工具運行器 自動管理。當您需要對工具執行進行自定義控制時,請使用本節。
處理來自客戶端工具的結果
響應將具有tool_use 的 stop_reason 和一個或多個 tool_use 內容區塊,包括:
id:此特定工具使用區塊的唯一標識符。這將用於稍後匹配工具結果。name:正在使用的工具的名稱。input:包含傳遞給工具的輸入的對象,符合工具的input_schema。
具有 `tool_use` 內容區塊的示例 API 響應
具有 `tool_use` 內容區塊的示例 API 響應
JSON
- 從
tool_use區塊中提取name、id和input。 - 在您的代碼庫中運行與該工具名稱對應的實際工具,傳入工具
input。 - 通過發送角色為
user的新消息和包含tool_result類型的content區塊來繼續對話,以及以下信息:tool_use_id:這是結果的工具使用請求的id。content:工具的結果,作為字符串(例如"content": "15 degrees")、嵌套內容區塊的列表(例如"content": [{"type": "text", "text": "15 degrees"}])或文檔區塊的列表(例如"content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}])。這些內容區塊可以使用text、image或document類型。is_error(可選):如果工具執行導致錯誤,設置為true。
重要的格式要求:這是正確的:如果您收到類似「tool_use ids were found without tool_result blocks immediately after」的錯誤,請檢查您的工具結果格式是否正確。
- 工具結果區塊必須立即跟在消息歷史中的相應工具使用區塊之後。您不能在助手的工具使用消息和用戶的工具結果消息之間包含任何消息。
- 在包含工具結果的用戶消息中,tool_result 區塊必須首先出現在內容數組中。任何文本必須在所有工具結果之後。
成功的工具結果示例
成功的工具結果示例
JSON
帶有圖像的工具結果示例
帶有圖像的工具結果示例
JSON
空工具結果示例
空工具結果示例
JSON
帶有文檔的工具結果示例
帶有文檔的工具結果示例
JSON
處理來自服務器工具的結果
Claude 在內部執行工具並將結果直接合併到其響應中,無需額外的用戶交互。與其他 API 的區別與分離工具使用或使用特殊角色(如
tool 或 function)的 API 不同,Claude 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 將隨後將此錯誤合併到對用戶的響應中,例如「抱歉,我無法檢索當前天氣,因為天氣服務 API 不可用。請稍後重試。」
content 中返回錯誤消息以及 "is_error": true:JSON
無效的工具名稱
無效的工具名稱
如果 Claude 嘗試使用的工具無效(例如缺少必需的參數),通常意味著 Claude 沒有足夠的信息來正確使用該工具。在開發期間,最好的辦法是使用工具定義中更詳細的 如果工具請求無效或缺少參數,Claude 將在向用戶道歉之前重試 2-3 次進行更正。
description 值重試請求。但是,您也可以使用指示錯誤的 tool_result 繼續對話,Claude 將嘗試使用填入缺失信息的工具:JSON
<search_quality_reflection> 標籤
<search_quality_reflection> 標籤
為了防止 Claude 使用 <search_quality_reflection> 標籤反思搜索質量,請在您的提示中添加「Do not reflect on the quality of the returned search results in your response」。
服務器工具錯誤
服務器工具錯誤
當服務器工具遇到錯誤時(例如網絡搜索的網絡問題),Claude 將透明地處理這些錯誤並嘗試向用戶提供替代響應或解釋。與客戶端工具不同,您不需要為服務器工具處理
is_error 結果。對於網絡搜索,可能的錯誤代碼包括:too_many_requests:超過速率限制invalid_input:無效的搜索查詢參數max_uses_exceeded:超過最大網絡搜索工具使用次數query_too_long:查詢超過最大長度unavailable:發生內部錯誤
並行工具調用不起作用
並行工具調用不起作用
如果 Claude 在預期時不進行並行工具調用,請檢查這些常見問題:1. 工具結果格式不正確最常見的問題是在對話歷史中不正確地格式化工具結果。這「教導」Claude 避免並行調用。特別是對於並行工具使用:有關其他格式規則,請參閱上面的 常規格式要求。2. 提示不夠強默認提示可能不夠。使用更強的語言:3. 測量並行工具使用要驗證並行工具調用是否正常工作:4. 模型特定行為
- ❌ 錯誤:為每個工具結果發送單獨的用戶消息
- ✅ 正確:所有工具結果必須在單個用戶消息中
- Claude Opus 4.1、Opus 4 和 Sonnet 4:在最少提示的情況下擅長並行工具使用
- Claude Sonnet 3.7:可能需要更強的提示或 令牌高效工具使用
- Claude Haiku:在沒有明確提示的情況下不太可能使用並行工具