平行工具使用

啟用、格式化和停用平行工具呼叫，並提供訊息歷史指引與疑難排解。

預設情況下，Claude 可能會在單一回應中呼叫多個工具。本頁涵蓋如何執行這些呼叫、如何格式化訊息歷史以讓平行處理持續運作，以及在需要時如何停用平行工具使用。關於單一呼叫流程，請參閱處理工具呼叫。

執行語意

當 Claude 呼叫工具時，回應的 stop_reason 為 tool_use，並且可以在單一助手回合中包含多個 tool_use 區塊。如何執行這些呼叫由您決定。API 不規定執行順序：您可以並行執行這些呼叫（Promise.all、asyncio.gather）、按照它們出現的順序依序執行，或以任何適合您工具的組合方式執行。

根據您的工具功能選擇策略。獨立的唯讀操作通常可以安全地平行執行以降低延遲。具有副作用、共享狀態或順序要求的工具可能更適合依序執行。

無論您使用哪種策略，都要為每個 tool_use 區塊回傳一個 tool_result，並全部放在下一個使用者訊息中。使用 tool_use_id 將每個結果與其呼叫配對，並將每個 tool_result 區塊放在該訊息中任何文字內容之前。請參閱處理工具呼叫以了解完整的格式化規則。如果您選擇不執行特定呼叫（例如，因為您依序執行批次而較早的呼叫失敗了），仍然要為它回傳一個帶有 is_error: true 和簡短說明的 tool_result。

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "Not executed: the preceding write_file call failed."
}

測試平行工具呼叫

以下腳本會發送一個應該觸發平行工具呼叫的請求，驗證回應中包含這些呼叫，並格式化工具結果以讓平行處理持續運作。在您的環境中設定 ANTHROPIC_API_KEY 後執行它：

client = Anthropic()

# 定義工具
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York",
                }
            },
            "required": ["timezone"],
        },
    },
]

# 測試包含平行工具呼叫的對話
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# 發出初始請求
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-5", max_tokens=1024, messages=messages, tools=tools
)

# 檢查平行工具呼叫
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# 模擬工具執行並正確格式化結果
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM 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},  # All results in one message!
    ]
)

# 取得最終回應
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-5", max_tokens=1024, messages=messages, tools=tools
)

final_text = next(
    block.text for block in final_response.content if block.type == "text"
)
print(f"\nClaude's response:\n{final_text}")

# 驗證格式
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")

最後的摘要行重申了讓平行處理持續運作的兩個格式化規則：每個工具結果都在單一使用者訊息中回傳，且該訊息中沒有任何文字內容出現在工具結果之前。

最大化平行工具使用

Claude 4 及更新的模型在請求可受益於多個工具時，預設會進行平行工具呼叫。對於所有模型，您可以透過有針對性的提示來增加平行工具呼叫的可能性：

停用平行工具使用

平行工具使用預設為開啟。若要關閉它，請在 tool_choice 物件內設定 disable_parallel_tool_use: true。它不是頂層的請求參數。其效果取決於 tool_choice 的類型。

最多一個工具呼叫

當 tool_choice 類型為 auto（預設值）時，設定 disable_parallel_tool_use: true 表示 Claude 每次回應最多呼叫一個工具。Claude 仍然可以在不呼叫任何工具的情況下以純文字回答。標示的行是與標準工具使用請求唯一的差異：

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=[
        {
            "role": "user",
            "content": "What is the weather in San Francisco and New York?",
        }
    ],
)
print(response.content)

恰好一個工具呼叫

當 tool_choice 類型為 any 或 tool 時，設定 disable_parallel_tool_use: true 表示 Claude 恰好呼叫一個工具。以下範例使用 any。相同的欄位也適用於 tool：

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    tool_choice={"type": "any", "disable_parallel_tool_use": True},
    messages=[
        {
            "role": "user",
            "content": "What is the weather in San Francisco and New York?",
        }
    ],
)
print(response.content)

疑難排解

如果 Claude 沒有在預期時進行平行工具呼叫，請檢查以下常見問題：

1. 不正確的工具結果格式

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

特別針對平行工具使用：

錯誤： 每個工具結果使用單獨的使用者訊息
正確： 所有工具結果一起放在單一使用者訊息中

// Wrong: separate user messages reduce parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]

// Correct: one user message with all results maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]

請參閱處理工具呼叫以了解其他格式化規則。

2. 提示力度不足

預設的提示可能不夠充分。請使用最大化平行工具使用中更強力的系統提示。

3. 測量平行工具使用情況

若要驗證平行工具呼叫是否正常運作：

messages = []  # Message objects returned by client.messages.create across your run

tool_call_messages = [
    msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
    len([block for block in msg.content if block.type == "tool_use"])
    for msg in tool_call_messages
)
avg_tools_per_message = (
    total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# 若平行呼叫正常運作，應 > 1.0

4. 批次中的呼叫似乎彼此相依

執行順序由您決定。如果您的工具有順序相依性，依序執行批次並在第一次失敗時停止是一個有效的策略：對於任何您未執行的呼叫，回傳 is_error: true。如果您平行執行，而某個呼叫因為其前置條件尚未完成而失敗，請回傳帶有自然錯誤訊息的 is_error: true。Claude 會在下一回合重新發出該呼叫。若要減少相依的呼叫一起出現，請將以下內容加入您的系統提示：「Only batch tool calls that are independent of each other.」

後續步驟

Tool Runner（SDK）

使用 SDK 的 Tool Runner 抽象層自動處理代理迴圈、錯誤包裝和型別安全。

處理工具呼叫

解析 tool_use 區塊、格式化 tool_result 回應，並使用 is_error 處理錯誤。

定義工具

指定工具結構描述、撰寫有效的描述，並控制 Claude 何時呼叫您的工具。

Was this page helpful?

Messages工具

平行工具使用

啟用、格式化和停用平行工具呼叫，並提供訊息歷史指引與疑難排解。

執行語意

根據您的工具功能選擇策略。獨立的唯讀操作通常可以安全地平行執行以降低延遲。具有副作用、共享狀態或順序要求的工具可能更適合依序執行。

{
  "type": "tool_result",
  "tool_use_id": "toolu_02",
  "is_error": true,
  "content": "Not executed: the preceding write_file call failed."
}

測試平行工具呼叫

client = Anthropic()

# 定義工具
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York",
                }
            },
            "required": ["timezone"],
        },
    },
]

# 測試包含平行工具呼叫的對話
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# 發出初始請求
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-5", max_tokens=1024, messages=messages, tools=tools
)

# 檢查平行工具呼叫
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# 模擬工具執行並正確格式化結果
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM 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},  # All results in one message!
    ]
)

# 取得最終回應
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-5", max_tokens=1024, messages=messages, tools=tools
)

final_text = next(
    block.text for block in final_response.content if block.type == "text"
)
print(f"\nClaude's response:\n{final_text}")

# 驗證格式
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")

最大化平行工具使用

停用平行工具使用

最多一個工具呼叫

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=[
        {
            "role": "user",
            "content": "What is the weather in San Francisco and New York?",
        }
    ],
)
print(response.content)

恰好一個工具呼叫

當 tool_choice 類型為 any 或 tool 時，設定 disable_parallel_tool_use: true 表示 Claude 恰好呼叫一個工具。以下範例使用 any。相同的欄位也適用於 tool：

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    tool_choice={"type": "any", "disable_parallel_tool_use": True},
    messages=[
        {
            "role": "user",
            "content": "What is the weather in San Francisco and New York?",
        }
    ],
)
print(response.content)

疑難排解

如果 Claude 沒有在預期時進行平行工具呼叫，請檢查以下常見問題：

1. 不正確的工具結果格式

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

特別針對平行工具使用：

錯誤： 每個工具結果使用單獨的使用者訊息
正確： 所有工具結果一起放在單一使用者訊息中

// Wrong: separate user messages reduce parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]

// Correct: one user message with all results maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]

請參閱處理工具呼叫以了解其他格式化規則。

2. 提示力度不足

預設的提示可能不夠充分。請使用最大化平行工具使用中更強力的系統提示。

3. 測量平行工具使用情況

若要驗證平行工具呼叫是否正常運作：

messages = []  # Message objects returned by client.messages.create across your run

tool_call_messages = [
    msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
    len([block for block in msg.content if block.type == "tool_use"])
    for msg in tool_call_messages
)
avg_tools_per_message = (
    total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# 若平行呼叫正常運作，應 > 1.0

4. 批次中的呼叫似乎彼此相依

後續步驟

Tool Runner（SDK）

使用 SDK 的 Tool Runner 抽象層自動處理代理迴圈、錯誤包裝和型別安全。

處理工具呼叫

解析 tool_use 區塊、格式化 tool_result 回應，並使用 is_error 處理錯誤。

定義工具

指定工具結構描述、撰寫有效的描述，並控制 Claude 何時呼叫您的工具。

Was this page helpful?

執行語意

測試平行工具呼叫

最大化平行工具使用

用於平行工具使用的系統提示

使用者訊息提示

停用平行工具使用

最多一個工具呼叫

恰好一個工具呼叫

疑難排解

後續步驟

執行語意

測試平行工具呼叫

最大化平行工具使用

用於平行工具使用的系統提示

使用者訊息提示

停用平行工具使用

最多一個工具呼叫

恰好一個工具呼叫

疑難排解

後續步驟

執行語意

測試平行工具呼叫

最大化平行工具使用

停用平行工具使用

最多一個工具呼叫

恰好一個工具呼叫

疑難排解

後續步驟

執行語意

測試平行工具呼叫

最大化平行工具使用

停用平行工具使用

最多一個工具呼叫

恰好一個工具呼叫

疑難排解

後續步驟