如何實作工具使用

選擇模型

一般來說，對於複雜工具和模糊查詢，請使用 Claude Opus 4.1、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": "要回答這個問題，我將：1. 使用 get_weather 工具取得舊金山的當前天氣。2. 使用 get_time 工具取得 America/Los_Angeles 時區的當前時間，該時區涵蓋加利福尼亞州舊金山。"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

這種思考鏈提供了對 Claude 推理過程的洞察，可以幫助您調試意外行為。重要的是要注意，Claude 可能使用各種格式來表示其思考鏈。您的程式碼應該將思考鏈視為任何其他助手生成的文字，而不依賴特定的格式約定。

並行工具使用

預設情況下，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-1-20250805",
    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-1-20250805",
    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-1-20250805",
    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-1-20250805",
    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.1、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-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我需要使用 get_weather，使用者想要 SF，這可能是加利福尼亞州舊金山。"
    },
    {
      "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 度"）、嵌套內容區塊列表（例如 "content": [{"type": "text", "text": "15 度"}]）或文件區塊列表（例如 "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 度"}]）。這些內容區塊可以使用 text、image 或 document 類型。
- 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 後的文字
]}

如果您收到類似「在 tool_result 區塊緊跟之後發現 tool_use ids」的錯誤，請檢查您的工具結果格式是否正確。

成功工具結果的範例

包含圖像的工具結果範例

JSON

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

空工具結果的範例

包含文件的工具結果範例

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "天氣是"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 度"
          }
        }
      ]
    }
  ]
}

收到工具結果後，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-1-20250805",
            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.1、Opus 4 和 Sonnet 4：在最少提示下擅長並行工具使用
Claude Sonnet 3.7：可能需要更強的提示或代幣高效工具使用
Claude Haiku：沒有明確提示時不太可能使用並行工具

第一步

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

如何實作工具使用

選擇模型

指定客戶端工具

工具使用系統提示

工具定義的最佳實務

控制 Claude 的輸出

強制工具使用

JSON 輸出

思考鏈

並行工具使用

最大化並行工具使用

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

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

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

處理 `max_tokens` 停止原因

處理 `pause_turn` 停止原因

疑難排解錯誤

第一步

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

​選擇模型

​指定客戶端工具

​工具使用系統提示

​工具定義的最佳實務

​控制 Claude 的輸出

​強制工具使用

​JSON 輸出

​思考鏈

​並行工具使用

​最大化並行工具使用

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

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

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

​處理 max_tokens 停止原因

​處理 pause_turn 停止原因

​疑難排解錯誤

選擇模型

指定客戶端工具

工具使用系統提示

工具定義的最佳實務

控制 Claude 的輸出

強制工具使用

JSON 輸出

思考鏈

並行工具使用

最大化並行工具使用

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

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

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

處理 `max_tokens` 停止原因

處理 `pause_turn` 停止原因

疑難排解錯誤