選擇模型

一般來說,對於複雜工具和模糊查詢,請使用 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 時,我們會從工具定義、工具配置和任何用戶指定的系統提示構建一個特殊的系統提示。構建的提示旨在指導模型使用指定的工具並為工具正常運行提供必要的上下文:

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

工具定義的最佳實踐

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

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

良好的描述清楚地解釋了工具的功能、使用時機、返回的數據以及 ticker 參數的含義。糟糕的描述過於簡短,讓 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 參數的更改將使快取的訊息區塊失效。工具定義和系統提示保持快取,但訊息內容必須重新處理。

此圖表說明了每個選項的工作原理:

請注意,當您將 tool_choice 設為 anytool 時,我們會預填助手訊息以強制使用工具。這意味著模型不會在 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 可能會回應:

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 Sonnet 3 模型,思維鏈預設較少見,但您可以通過在用戶訊息或系統提示中添加類似「在回答之前,請在標籤中逐步解釋您的推理。」來提示 Claude 顯示其推理。

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

並行工具使用

預設情況下,Claude 可能使用多個工具來回答用戶查詢。您可以通過以下方式禁用此行為:

  • 當 tool_choice 類型為 auto 時設定 disable_parallel_tool_use=true,這確保 Claude 最多使用一個工具
  • 當 tool_choice 類型為 anytool 時設定 disable_parallel_tool_use=true,這確保 Claude 恰好使用一個工具

最大化並行工具使用

雖然 Claude 4 模型預設具有出色的並行工具使用能力,但您可以通過有針對性的提示在所有模型中增加並行工具執行的可能性:

Claude Sonnet 3.7 的並行工具使用

Claude Sonnet 3.7 可能不太可能在回應中進行並行工具調用,即使您沒有設定 disable_parallel_tool_use。為了解決這個問題,我們建議啟用代幣高效工具使用,這有助於鼓勵 Claude 使用並行工具。此測試功能還可以減少延遲並平均節省 14% 的輸出代幣。

如果您不想選擇代幣高效工具使用測試版,您也可以引入一個「批次工具」,它可以作為元工具來同時包裝對其他工具的調用。我們發現如果存在此工具,模型將使用它來為您同時並行調用多個工具。

請參閱我們食譜中的此範例以了解如何使用此解決方法。

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

Claude 的回應根據它使用客戶端還是伺服器工具而有所不同。

處理客戶端工具的結果

回應將有 tool_usestop_reason 和一個或多個 tool_use 內容區塊,包括:

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

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

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

重要的格式要求

  • 工具結果區塊必須在訊息歷史中緊跟其對應的工具使用區塊。您不能在助手的工具使用訊息和用戶的工具結果訊息之間包含任何訊息。
  • 在包含工具結果的用戶訊息中,tool_result 區塊必須在內容陣列中排在第一位。任何文本都必須在所有工具結果之後。

例如,這將導致 400 錯誤:

{"role": "user", "content": [
  {"type": "text", "text": "以下是結果:"},  // ❌ tool_result 前的文本
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

這是正確的:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "我接下來應該做什麼?"}  // ✅ tool_result 後的文本
]}

如果您收到類似「在工具使用 id 後立即找不到工具結果區塊」的錯誤,請檢查您的工具結果格式是否正確。

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

處理伺服器工具的結果

Claude 在內部執行工具並將結果直接納入其回應中,無需額外的用戶互動。

與其他 API 的差異

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

訊息包含 textimagetool_usetool_result 區塊的陣列。user 訊息包括客戶端內容和 tool_result,而 assistant 訊息包含 AI 生成的內容和 tool_use

處理 max_tokens 停止原因

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

# 檢查回應是否在工具使用期間被截斷
if response.stop_reason == "max_tokens":
    # 檢查最後一個內容區塊是否是不完整的 tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # 使用更高的 max_tokens 發送請求
        response = client.messages.create(
            model="claude-opus-4-20250514",
            max_tokens=4096,  # 增加限制
            messages=messages,
            tools=tools
        )

處理 pause_turn 停止原因

使用網路搜尋等伺服器工具時,API 可能返回 pause_turn 停止原因,表示 API 已暫停長時間運行的回合。

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

import anthropic

client = anthropic.Anthropic()

# 使用網路搜尋的初始請求
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "搜尋 2025 年量子計算突破的綜合資訊"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# 檢查回應是否有 pause_turn 停止原因
if response.stop_reason == "pause_turn":
    # 使用暫停的內容繼續對話
    messages = [
        {"role": "user", "content": "搜尋 2025 年量子計算突破的綜合資訊"},
        {"role": "assistant", "content": response.content}
    ]
    
    # 發送繼續請求
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

處理 pause_turn 時:

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

錯誤疑難排解

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