並列ツール使用

このページは並列ツール呼び出しについて説明しています。Claudeが1ターンで複数のツールを呼び出す場合、並列性を保つためにメッセージ履歴をフォーマットする方法、および並列性を無効にする方法について説明しています。単一呼び出しフローについては、ツール呼び出しの処理を参照してください。

デフォルトでは、Claudeはユーザークエリに答えるために複数のツールを使用する場合があります。この動作は以下の方法で無効にできます。

tool_choiceタイプがautoの場合、disable_parallel_tool_use=trueを設定すると、Claudeは最大1つのツールを使用します
tool_choiceタイプがanyまたはtoolの場合、disable_parallel_tool_use=trueを設定すると、Claudeは正確に1つのツールを使用します

実装例

Tool Runnerでより簡単に: 以下の例は手動の並列ツール処理を示しています。ほとんどのユースケースでは、Tool Runnerが並列ツール実行を自動的に処理し、コードがはるかに少なくなります。

並列ツール呼び出しが正しく機能していることをテストして検証するための完全で実行可能なスクリプトは次のとおりです。

# Define tools
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"],
        },
    },
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools
)

# Check for parallel tool calls
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")

# Simulate tool execution and format results correctly
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}
    )

# Continue conversation with tool results
messages.extend(
    [
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results},  # All results in one message!
    ]
)

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-4-7", max_tokens=1024, messages=messages, tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
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が並列ツール呼び出しを効果的に行っていることを確認してください。

並列ツール使用の最大化

Claude 4モデルはデフォルトで優れた並列ツール使用機能を備えていますが、対象を絞ったプロンプティングを使用すると、すべてのモデルで並列ツール実行の可能性を高めることができます。

トラブルシューティング

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. 弱いプロンプティング

デフォルトのプロンプティングは十分でない場合があります。上記の並列ツール使用の最大化セクションからより強力なシステムプロンプトを使用してください。

3. 並列ツール使用の測定

並列ツール呼び出しが機能していることを確認するには：

# Calculate average tools per tool-calling message
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) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working

次のステップ

単一ツール呼び出しフローとtool_resultフォーマットルールについては、ツール呼び出しの処理を参照してください。
並列実行を自動的に処理するSDK抽象化については、Tool Runnerを参照してください。
完全なツール使用ワークフローについては、ツールの定義を参照してください。

実装例

並列ツール使用の最大化

並列ツール使用のためのシステムプロンプト

ユーザーメッセージプロンプティング

トラブルシューティング

次のステップ