如何實現工具使用

選擇模型

一般來說，對於複雜工具和模糊查詢，請使用 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 物件。

簡單工具定義範例

JSON
{
  "name": "get_weather",
  "description": "獲取指定位置的當前天氣",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市和州，例如 San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "溫度單位，'celsius' 或 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

這個名為 get_weather 的工具期望一個輸入物件，包含必需的 location 字串和可選的 unit 字串，該字串必須是 “celsius” 或 “fahrenheit”。

工具使用系統提示

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

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

工具定義的最佳實踐

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

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

良好工具描述的範例

JSON
{
  "name": "get_stock_price",
  "description": "檢索給定股票代碼的當前股價。股票代碼必須是在 NYSE 或 NASDAQ 等主要美國證券交易所公開交易公司的有效代碼。該工具將返回以美元為單位的最新交易價格。當用戶詢問特定股票的當前或最新價格時應使用此工具。它不會提供有關股票或公司的任何其他資訊。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "股票代碼，例如 AAPL 代表 Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

糟糕工具描述的範例

JSON
{
  "name": "get_stock_price",
  "description": "獲取股票代碼的股價。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

良好的描述清楚地解釋了工具的功能、使用時機、返回的數據以及 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 設為 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 可能會回應：

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 類型為 any 或 tool 時設定 disable_parallel_tool_use=true，這確保 Claude 恰好使用一個工具

完整的並行工具使用範例

以下是一個完整的範例，展示如何在訊息歷史中正確格式化並行工具調用：

import anthropic

client = anthropic.Anthropic()

# 定義工具
tools = [
    {
        "name": "get_weather",
        "description": "獲取指定位置的當前天氣",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市和州，例如 San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "獲取指定時區的當前時間",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "時區，例如 America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# 初始請求
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "舊金山和紐約的天氣如何，那裡現在是什麼時間？"
        }
    ]
)

# Claude 的並行工具調用回應
print("Claude 想要使用工具：", response.stop_reason == "tool_use")
print("工具調用數量：", len([c for c in response.content if c.type == "tool_use"]))

# 使用工具結果構建對話
messages = [
    {
        "role": "user",
        "content": "舊金山和紐約的天氣如何，那裡現在是什麼時間？"
    },
    {
        "role": "assistant",
        "content": response.content  # 包含多個 tool_use 區塊
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # 必須與 tool_use 的 ID 匹配
                "content": "舊金山：68°F，部分多雲"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "紐約：45°F，晴朗"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "舊金山時間：下午 2:30 PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "紐約時間：下午 5:30 EST"
            }
        ]
    }
]

# 獲取最終回應
final_response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

包含並行工具調用的助手訊息看起來像這樣：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我將檢查舊金山和紐約市的天氣和時間。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

並行工具的完整測試腳本

以下是一個完整的可運行腳本，用於測試和驗證並行工具調用是否正常工作：

#!/usr/bin/env python3
"""測試腳本以驗證 Anthropic API 的並行工具調用"""

import os
from anthropic import Anthropic

# 初始化客戶端
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# 定義工具
tools = [
    {
        "name": "get_weather",
        "description": "獲取指定位置的當前天氣",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市和州，例如 San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "獲取指定時區的當前時間",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "時區，例如 America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# 使用並行工具調用測試對話
messages = [
    {
        "role": "user",
        "content": "舊金山和紐約的天氣如何，那裡現在是什麼時間？"
    }
]

# 發出初始請求
print("請求並行工具調用...")
response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# 檢查並行工具調用
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude 進行了 {len(tool_uses)} 次工具調用")

if len(tool_uses) > 1:
    print("✓ 檢測到並行工具調用！")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ 未檢測到並行工具調用")

# 模擬工具執行並正確格式化結果
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "舊金山：68°F，部分多雲"
        else:
            result = "紐約：45°F，晴朗"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "下午 2:30 PST"
        else:
            result = "下午 5:30 EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# 使用工具結果繼續對話
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # 所有結果在一條訊息中！
])

# 獲取最終回應
print("\n獲取最終回應...")
final_response = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude 的回應：\n{final_response.content[0].text}")

# 驗證格式
print("\n--- 驗證 ---")
print(f"✓ 工具結果在單個用戶訊息中發送：{len(tool_results)} 個結果")
print("✓ 內容陣列中工具結果前沒有文本")
print("✓ 對話格式正確，適合未來的並行工具使用")

此腳本演示了：

如何正確格式化並行工具調用和結果
如何驗證正在進行並行調用
鼓勵未來並行工具使用的正確訊息結構
要避免的常見錯誤（如工具結果前的文本）

運行此腳本以測試您的實現並確保 Claude 有效地進行並行工具調用。

最大化並行工具使用

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

並行工具使用的系統提示

對於 Claude 4 模型（Opus 4 和 Sonnet 4），將此添加到您的系統提示中：

為了最大效率，每當您需要執行多個獨立操作時，請同時調用所有相關工具，而不是順序調用。

對於更強的並行工具使用（如果預設不足，建議使用），請使用：

<use_parallel_tool_calls>
為了最大效率，每當您執行多個獨立操作時，請同時調用所有相關工具，而不是順序調用。盡可能優先並行調用工具。例如，讀取 3 個檔案時，並行運行 3 個工具調用以同時將所有 3 個檔案讀入上下文。運行多個只讀命令如 `ls` 或 `list_dir` 時，始終並行運行所有命令。寧可最大化並行工具調用，也不要順序運行太多工具。
</use_parallel_tool_calls>

用戶訊息提示

您也可以在特定用戶訊息中鼓勵並行工具使用：

# 而不是：
"巴黎的天氣如何？也檢查倫敦。"

# 使用：
"同時檢查巴黎和倫敦的天氣。"

# 或明確說明：
"請使用並行工具調用同時獲取巴黎、倫敦和東京的天氣。"

Claude Sonnet 3.7 的並行工具使用

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

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

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

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

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

處理客戶端工具的結果

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

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

包含 `tool_use` 內容區塊的 API 回應範例

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要使用 get_weather，用戶想要 SF，這很可能是加利福尼亞州舊金山。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

從 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 錯誤：

{"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 後立即找不到工具結果區塊」的錯誤，請檢查您的工具結果格式是否正確。

成功工具結果的範例

包含圖像的工具結果範例

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

空工具結果的範例

收到工具結果後，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 值重試請求以獲得完整的工具使用。

# 檢查回應是否在工具使用期間被截斷
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 的工具時可能會發生幾種不同類型的錯誤：

工具執行錯誤

如果工具本身在執行期間拋出錯誤（例如獲取天氣數據時的網路錯誤），您可以在 content 中返回錯誤訊息以及 "is_error": true：

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 天氣服務 API 不可用（HTTP 500）",
      "is_error": true
    }
  ]
}

Claude 然後會將此錯誤納入其對用戶的回應中，例如「很抱歉，我無法檢索當前天氣，因為天氣服務 API 不可用。請稍後再試。」

無效工具名稱

如果 Claude 嘗試使用的工具無效（例如缺少必需參數），這通常意味著沒有足夠的資訊讓 Claude 正確使用工具。在開發期間，您最好的選擇是在工具定義中使用更詳細的 description 值重試請求。

但是，您也可以使用指示錯誤的 tool_result 繼續對話，Claude 將嘗試在填入缺失資訊後再次使用工具：

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "錯誤：缺少必需的 'location' 參數",
      "is_error": true
    }
  ]
}

如果工具請求無效或缺少參數，Claude 將在向用戶道歉之前重試 2-3 次並進行更正。

<search_quality_reflection> 標籤

伺服器工具錯誤

並行工具調用不工作

如果 Claude 在預期時沒有進行並行工具調用，請檢查這些常見問題：

1. 工具結果格式不正確

最常見的問題是在對話歷史中格式化工具結果不正確。這會「教導」Claude 避免並行調用。

特別是對於並行工具使用：

❌ 錯誤：為每個工具結果發送單獨的用戶訊息
✅ 正確：所有工具結果必須在單個用戶訊息中

// ❌ 這會減少並行工具使用
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // 單獨的訊息
]

// ✅ 這會維持並行工具使用
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // 單個訊息
]

請參閱上面的一般格式要求以了解其他格式規則。

2. 提示較弱

預設提示可能不夠。使用更強的語言：

<use_parallel_tool_calls>
為了最大效率，每當您執行多個獨立操作時，
請同時調用所有相關工具，而不是順序調用。
盡可能優先並行調用工具。
</use_parallel_tool_calls>

3. 測量並行工具使用

要驗證並行工具調用是否工作：

# 計算每個工具調用訊息的平均工具數
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"每條訊息的平均工具數：{avg_tools_per_message}")
# 如果並行調用工作，應該 > 1.0

4. 模型特定行為

Claude Opus 4 和 Sonnet 4：在最少提示下擅長並行工具使用
Claude Sonnet 3.7：可能需要更強的提示或代幣高效工具使用
Claude Haiku：沒有明確提示不太可能使用並行工具

概述高效使用工具的 token 優化（測試版）

On this page

選擇模型
指定客戶端工具
工具使用系統提示
工具定義的最佳實踐
控制 Claude 的輸出
強制工具使用
JSON 輸出
思維鏈
並行工具使用
最大化並行工具使用
處理工具使用和工具結果內容區塊
處理客戶端工具的結果
處理伺服器工具的結果
處理 max_tokens 停止原因
處理 pause_turn 停止原因
錯誤疑難排解

入門步驟

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

如何實現工具使用

選擇模型

指定客戶端工具

工具使用系統提示

工具定義的最佳實踐

控制 Claude 的輸出

強制工具使用

JSON 輸出

思維鏈

並行工具使用

最大化並行工具使用

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

處理客戶端工具的結果

處理伺服器工具的結果

處理 `max_tokens` 停止原因

處理 `pause_turn` 停止原因

錯誤疑難排解

入門步驟

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

​選擇模型

​指定客戶端工具

​工具使用系統提示

​工具定義的最佳實踐

​控制 Claude 的輸出

​強制工具使用

​JSON 輸出

​思維鏈

​並行工具使用

​最大化並行工具使用

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

​處理客戶端工具的結果

​處理伺服器工具的結果

​處理 max_tokens 停止原因

​處理 pause_turn 停止原因

​錯誤疑難排解

選擇模型

指定客戶端工具

工具使用系統提示

工具定義的最佳實踐

控制 Claude 的輸出

強制工具使用

JSON 輸出

思維鏈

並行工具使用

最大化並行工具使用

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

處理客戶端工具的結果

處理伺服器工具的結果

處理 `max_tokens` 停止原因

處理 `pause_turn` 停止原因

錯誤疑難排解