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

По умолчанию Claude может вызывать несколько инструментов в одном ответе. На этой странице описано, как выполнять эти вызовы, как форматировать историю сообщений, чтобы параллелизм продолжал работать, и как отключить «parallel tool use» (параллельное использование инструментов), когда это необходимо. Описание процесса с одним вызовом см. в разделе Обработка вызовов инструментов.

Семантика выполнения

Когда Claude вызывает инструменты, ответ имеет stop_reason со значением tool_use и может содержать несколько блоков tool_use в одном ходе ассистента. Как выполнять эти вызовы — решаете вы. API не предписывает порядок выполнения: вы можете выполнять вызовы одновременно (Promise.all, asyncio.gather), последовательно в порядке их появления или в любой комбинации, подходящей для ваших инструментов.

Выбирайте стратегию в зависимости от того, что делают ваши инструменты. Независимые операции только для чтения обычно безопасно выполнять параллельно для снижения «latency» (задержки). Инструменты с побочными эффектами, общим состоянием или требованиями к порядку выполнения, возможно, лучше запускать последовательно.

Какую бы стратегию вы ни использовали, возвращайте по одному tool_result для каждого блока tool_use, все вместе в следующем сообщении пользователя. Сопоставляйте каждый результат с его вызовом с помощью tool_use_id и размещайте все блоки tool_result перед любым текстовым содержимым в этом сообщении. Полные правила форматирования см. в разделе Обработка вызовов инструментов. Если вы решили не выполнять конкретный вызов (например, потому что вы выполняли пакет последовательно и предыдущий вызов завершился ошибкой), всё равно верните для него tool_result с is_error: true и кратким пояснением.

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

Инструмент использования компьютера и инструмент использования браузера более строги. Когда Claude возвращает несколько вызовов их составных инструментов за один ход (пакетное действие), выполняйте их последовательно в порядке появления и останавливайтесь при первой ошибке; каждый инструмент определяет точный текст, который нужно вернуть для пропущенных вызовов.

Тестирование параллельных вызовов инструментов

Следующий скрипт отправляет запрос, который должен вызвать параллельные вызовы инструментов, проверяет, что ответ их содержит, и форматирует результаты инструментов так, чтобы параллелизм продолжал работать. Запустите его, установив 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 и более поздние по умолчанию выполняют параллельные вызовы инструментов, когда запрос выигрывает от использования нескольких инструментов. Для всех моделей вы можете повысить вероятность параллельных вызовов инструментов с помощью целенаправленных подсказок:

For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
</use_parallel_tool_calls>

Instead of:
"What's the weather in Paris? Also check London."

Use:
"Check the weather in Paris and London simultaneously."

Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."

Отключение параллельного использования инструментов

Параллельное использование инструментов включено по умолчанию. Чтобы отключить его, установите disable_parallel_tool_use: true внутри объекта tool_choice. Это не параметр запроса верхнего уровня. Эффект зависит от типа 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 вызывает ровно один инструмент. Claude Fable 5.1 и Claude Mythos 5.1 не поддерживают эти типы tool_choice (см. Принудительное использование инструментов). В следующем примере используется 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.»

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