如何實現工具使用

選擇模型

我們建議對複雜工具和模糊查詢使用最新的 Claude Sonnet (4.5) 或 Claude Opus (4.1) 模型；它們能更好地處理多個工具並在需要時尋求澄清。

對於直接的工具，使用 Claude Haiku 模型，但請注意它們可能會推斷缺失的參數。

指定客戶端工具

客戶端工具（包括 Anthropic 定義的和用戶定義的）在 API 請求的 tools 頂級參數中指定。每個工具定義包括：

工具使用系統提示

當您使用 tools 參數調用 Claude API 時，我們從工具定義、工具配置和任何用戶指定的系統提示構建特殊系統提示。構建的提示旨在指示模型使用指定的工具並為工具提供必要的上下文以正確運行：

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

工具定義的最佳實踐

為了從 Claude 使用工具中獲得最佳性能，請遵循以下指南：

• 提供極其詳細的描述。 這是工具性能中最重要的因素。您的描述應解釋有關工具的每個細節，包括：
  • 工具的功能
  • 何時應使用它（以及何時不應使用）
  • 每個參數的含義以及它如何影響工具的行為
  • 任何重要的注意事項或限制，例如如果工具名稱不清楚，工具不返回的信息。您為 Claude 提供的關於工具的上下文越多，它在決定何時以及如何使用它們時就會越好。每個工具描述至少應有 3-4 句話，如果工具複雜則更多。
• 優先考慮描述，但對複雜工具考慮使用 input_examples。 清晰的描述最重要，但對於具有複雜輸入、嵌套對象或格式敏感參數的工具，您可以使用 input_examples 字段（測試版）提供模式驗證的示例。詳見 提供工具使用示例。

良好的描述清楚地解釋了工具的功能、何時使用、返回的數據以及 ticker 參數的含義。不佳的描述過於簡潔，給 Claude 留下了許多關於工具行為和使用的開放性問題。

提供工具使用示例

您可以提供具體的有效工具輸入示例，幫助 Claude 更有效地理解如何使用您的工具。這對於具有嵌套對象、可選參數或格式敏感輸入的複雜工具特別有用。

基本使用

將可選的 input_examples 字段添加到您的工具定義中，其中包含示例輸入對象的數組。每個示例必須根據工具的 input_schema 有效：

示例包含在提示中，與您的工具模式一起，向 Claude 展示格式良好的工具調用的具體模式。這幫助 Claude 理解何時包含可選參數、使用什麼格式以及如何構建複雜輸入。

要求和限制

• 模式驗證 - 每個示例必須根據工具的 input_schema 有效。無效示例返回 400 錯誤
• 不支持服務器端工具 - 只有用戶定義的工具可以有輸入示例
• 令牌成本 - 示例增加提示令牌：簡單示例約 20-50 個令牌，複雜嵌套對象約 100-200 個令牌

工具執行器（測試版）

工具執行器為使用 Claude 執行工具提供了開箱即用的解決方案。工具執行器不是手動處理工具調用、工具結果和對話管理，而是自動：

• 在 Claude 調用工具時執行工具
• 處理請求/響應週期
• 管理對話狀態
• 提供類型安全和驗證

我們建議您在大多數工具使用實現中使用工具執行器。

控制 Claude 的輸出

強制工具使用

在某些情況下，您可能希望 Claude 使用特定工具來回答用戶的問題，即使 Claude 認為它可以在不使用工具的情況下提供答案。您可以通過在 tool_choice 字段中指定工具來執行此操作，如下所示：

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

使用 tool_choice 參數時，我們有四個可能的選項：

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

此圖表說明了每個選項的工作方式：

請注意，當您將 tool_choice 設置為 any 或 tool 時，我們將預填充助手消息以強制使用工具。這意味著模型不會在 tool_use 內容塊之前發出自然語言響應或解釋，即使明確要求這樣做。

我們的測試表明這不應該降低性能。如果您希望模型在仍然請求模型使用特定工具的同時提供自然語言上下文或解釋，您可以使用 {"type": "auto"} 作為 tool_choice （默認）並在 user 消息中添加明確的指示。例如：What's the weather like in London? Use the get_weather tool in your response.

JSON 輸出

工具不一定需要是客戶端函數 — 您可以在任何時候使用工具，當您希望模型返回遵循提供的模式的 JSON 輸出時。例如，您可能使用具有特定模式的 record_summary 工具。詳見 使用 Claude 進行工具使用 以獲取完整的工作示例。

使用工具的模型響應

使用工具時，Claude 通常會在調用工具之前評論它正在做什麼或自然地響應用戶。

例如，給定提示 "What's the weather like in San Francisco right now, and what time is it there?"，Claude 可能會響應：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

這種自然的響應風格幫助用戶理解 Claude 正在做什麼並創建更對話式的交互。您可以通過您的系統提示和在提示中提供 <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 的回應根據它是否使用客戶端或伺服器工具而有所不同。

處理來自客戶端工具的結果

回應將具有 tool_use 的 stop_reason 和一個或多個 tool_use 內容區塊，其中包括：

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

當您收到客戶端工具的工具使用回應時，您應該：

1. 從 tool_use 區塊中提取 name、id 和 input。
2. 在您的程式碼庫中執行與該工具名稱對應的實際工具，傳入工具 input。
3. 透過傳送角色為 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"}]）。這些內容區塊可以使用 、 或 類型。

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

收到工具結果後，Claude 將使用該資訊繼續產生對原始使用者提示的回應。

處理來自伺服器工具的結果

Claude 在內部執行工具，並將結果直接合併到其回應中，無需額外的使用者互動。

處理 max_tokens 停止原因

如果 Claude 的回應因達到 max_tokens 限制而被截斷，且截斷的回應包含不完整的工具使用區塊，您需要使用更高的 max_tokens 值重試請求以取得完整的工具使用。

處理 pause_turn 停止原因

使用伺服器工具（如網路搜尋）時，API 可能會傳回 pause_turn 停止原因，表示 API 已暫停長時間執行的回合。

以下是如何處理 pause_turn 停止原因：

處理 pause_turn 時：

• 繼續對話：在後續請求中按原樣傳回暫停的回應，讓 Claude 繼續其回合
• 視需要修改：如果您想中斷或重定向對話，您可以選擇在繼續之前修改內容
• 保留工具狀態：在繼續請求中包含相同的工具以維持功能

疑難排解錯誤

使用 Claude 的工具時可能會發生幾種不同類型的錯誤：