Uso de ferramentas em paralelo

Por padrão, Claude pode chamar várias ferramentas em uma única resposta. Esta página aborda como executar essas chamadas, como formatar o histórico de mensagens para que o paralelismo continue funcionando e como desabilitar o "parallel tool use" (uso de ferramentas em paralelo) quando você precisar. Para o fluxo de chamada única, consulte Lidar com chamadas de ferramentas.

Semântica de execução

Quando Claude chama ferramentas, a resposta tem um stop_reason de tool_use e pode conter vários blocos tool_use em um único turno do assistente. Como você executa essas chamadas é uma decisão sua. A API não prescreve uma ordem de execução: você pode executar as chamadas de forma concorrente (Promise.all, asyncio.gather), sequencialmente na ordem em que aparecem ou em qualquer combinação que se adeque às suas ferramentas.

Escolha a estratégia com base no que suas ferramentas fazem. Operações independentes e somente leitura geralmente são seguras para executar em paralelo, com menor "latency" (latência). Ferramentas com efeitos colaterais, estado compartilhado ou requisitos de ordenação podem ser melhor executadas sequencialmente.

Qualquer que seja a estratégia usada, retorne um tool_result para cada bloco tool_use, todos juntos na próxima mensagem do usuário. Associe cada resultado à sua chamada com tool_use_id e coloque todos os blocos tool_result antes de qualquer conteúdo de texto nessa mensagem. Consulte Lidar com chamadas de ferramentas para as regras completas de formatação. Se você optar por não executar uma chamada específica (por exemplo, porque executou o lote sequencialmente e uma chamada anterior falhou), ainda assim retorne um tool_result para ela com is_error: true e uma breve explicação.

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

A ferramenta de uso de computador e a ferramenta de uso de navegador são mais rigorosas. Quando Claude retorna várias chamadas de suas ferramentas membro em um único turno (uma ação em lote), execute-as sequencialmente na ordem em que aparecem e pare na primeira falha; cada ferramenta define o texto exato a ser retornado para as chamadas que você pular.

Testar chamadas de ferramentas em paralelo

O script a seguir envia uma requisição que deve acionar chamadas de ferramentas em paralelo, verifica se a resposta as contém e formata os resultados das ferramentas para que o paralelismo continue funcionando. Execute-o com ANTHROPIC_API_KEY definida no seu ambiente:

client = Anthropic()

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

# Testa a conversa com chamadas de ferramentas paralelas
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?",
    }
]

# Faz a requisição inicial
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-5-5", max_tokens=1024, messages=messages, tools=tools
)

# Verifica se há chamadas de ferramentas paralelas
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")

# Simula a execução das ferramentas e formata os resultados corretamente
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}
    )

# Continua a conversa com os resultados das ferramentas
messages.extend(
    [
        {"role": "assistant", "content": response.content},
        {"role": "user", "content": tool_results},  # All results in one message!
    ]
)

# Obtém a resposta final
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-5-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}")

# Verifica a formatação
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")

As linhas de resumo no final reafirmam as duas regras de formatação que mantêm o paralelismo funcionando: todos os resultados de ferramentas retornam em uma única mensagem do usuário, e nenhum conteúdo de texto aparece antes dos resultados de ferramentas nessa mensagem.

Maximizando o uso de ferramentas em paralelo

Os modelos Claude 4 e posteriores fazem chamadas de ferramentas em paralelo por padrão quando uma requisição se beneficia de várias ferramentas. Para todos os modelos, você pode aumentar a probabilidade de chamadas de ferramentas em paralelo com prompts direcionados:

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."

Desabilitar o uso de ferramentas em paralelo

O uso de ferramentas em paralelo está ativado por padrão. Para desativá-lo, defina disable_parallel_tool_use: true dentro do objeto tool_choice. Não é um parâmetro de requisição de nível superior. O efeito depende do tipo de tool_choice.

No máximo uma chamada de ferramenta

Quando o tipo de tool_choice é auto (o padrão), definir disable_parallel_tool_use: true significa que Claude chama no máximo uma ferramenta por resposta. Claude ainda pode responder em texto simples sem chamar nenhuma ferramenta. As linhas destacadas são a única alteração em relação a uma requisição padrão de uso de ferramentas:

client = Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

Exatamente uma chamada de ferramenta

Quando o tipo de tool_choice é any ou tool, definir disable_parallel_tool_use: true significa que Claude chama exatamente uma ferramenta. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 não suportam esses tipos de tool_choice (consulte Forçar o uso de ferramentas). O exemplo a seguir usa any. O mesmo campo funciona com 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)

Solução de problemas

Se Claude não estiver fazendo chamadas de ferramentas em paralelo quando esperado, verifique estes problemas comuns:

1. Formatação incorreta dos resultados de ferramentas

O problema mais comum é formatar os resultados de ferramentas incorretamente no histórico da conversa. Isso "ensina" Claude a evitar chamadas em paralelo.

Especificamente para o uso de ferramentas em paralelo:

• Errado: uma mensagem do usuário separada para cada resultado de ferramenta
• Correto: todos os resultados de ferramentas juntos em uma única mensagem do usuário

// 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
]

Consulte Lidar com chamadas de ferramentas para outras regras de formatação.

2. Prompts fracos

Os prompts padrão podem não ser suficientes. Use o prompt do sistema mais forte de Maximizando o uso de ferramentas em paralelo.

3. Medindo o uso de ferramentas em paralelo

Para verificar se as chamadas de ferramentas em paralelo estão funcionando:

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}")
# Deve ser > 1.0 se as chamadas paralelas estiverem funcionando

4. Chamadas em um lote parecem depender umas das outras

A ordem de execução é escolha sua. Se suas ferramentas têm dependências de ordenação, executar o lote sequencialmente e parar na primeira falha é uma estratégia válida (e a obrigatória para as ferramentas de uso de computador e uso de navegador): retorne is_error: true para qualquer chamada que você não executou. Se você executar em paralelo e uma chamada falhar porque seu pré-requisito não havia sido concluído, retorne is_error: true com a mensagem de erro natural. Claude reemitirá a chamada no próximo turno. Para reduzir o aparecimento conjunto de chamadas dependentes, adicione isto ao seu prompt do sistema: "Only batch tool calls that are independent of each other."

Próximos passos