Параллельное использование инструментов

РазработкаИнструменты

Параллельное использование инструментов

Включение и форматирование параллельных вызовов инструментов с рекомендациями по истории сообщений и устранением неполадок.

На этой странице рассматриваются параллельные вызовы инструментов: когда Claude вызывает несколько инструментов за один ход, как форматировать историю сообщений, чтобы параллелизм продолжал работать, и как его отключить. Для потока с одним вызовом см. Обработка вызовов инструментов.

По умолчанию Claude может использовать несколько инструментов для ответа на запрос пользователя. Вы можете отключить это поведение следующим образом:

Установив disable_parallel_tool_use=true когда тип tool_choice равен auto, что гарантирует, что Claude использует максимум один инструмент
Установив disable_parallel_tool_use=true когда тип tool_choice равен any или tool, что гарантирует, что Claude использует ровно один инструмент

Рабочий пример

Проще с 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.
Для полного рабочего процесса использования инструментов, см. Определение инструментов.

Was this page helpful?

РазработкаИнструменты

Параллельное использование инструментов

Установив disable_parallel_tool_use=true когда тип tool_choice равен auto, что гарантирует, что Claude использует максимум один инструмент
Установив disable_parallel_tool_use=true когда тип tool_choice равен any или tool, что гарантирует, что Claude использует ровно один инструмент

Рабочий пример

# 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")

Этот скрипт демонстрирует:

Как правильно форматировать параллельные вызовы инструментов и результаты
Как проверить, что параллельные вызовы выполняются
Правильную структуру сообщений, которая способствует будущему параллельному использованию инструментов
Распространённые ошибки, которых следует избегать (например, текст перед результатами инструментов)

Максимизация параллельного использования инструментов

Устранение неполадок

1. Неправильное форматирование результатов инструментов

Специально для параллельного использования инструментов:

❌ Неправильно: Отправка отдельных пользовательских сообщений для каждого результата инструмента
✅ Правильно: Все результаты инструментов должны быть в одном пользовательском сообщении

// ❌ Это снижает параллельное использование инструментов
[
  {"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.
Для полного рабочего процесса использования инструментов, см. Определение инструментов.

Was this page helpful?

Рабочий пример

Максимизация параллельного использования инструментов

Системные подсказки для параллельного использования инструментов

Промптирование пользовательского сообщения

Устранение неполадок

Следующие шаги

Рабочий пример

Максимизация параллельного использования инструментов

Системные подсказки для параллельного использования инструментов

Промптирование пользовательского сообщения

Устранение неполадок

Следующие шаги