Uso paralelo de ferramentas

Esta página aborda chamadas de ferramentas paralelas: quando Claude chama múltiplas ferramentas em um turno, como formatar o histórico de mensagens para que o paralelismo continue funcionando e como desabilitá-lo. Para o fluxo de chamada única, consulte Lidar com chamadas de ferramentas.

Por padrão, Claude pode usar múltiplas ferramentas para responder a uma consulta do usuário. Você pode desabilitar esse comportamento por:

Definindo disable_parallel_tool_use=true quando o tipo de tool_choice é auto, o que garante que Claude use no máximo uma ferramenta
Definindo disable_parallel_tool_use=true quando o tipo de tool_choice é any ou tool, o que garante que Claude use exatamente uma ferramenta

Exemplo prático

Mais simples com Tool Runner: O exemplo abaixo mostra o tratamento manual de ferramentas paralelas. Para a maioria dos casos de uso, Tool Runner lida automaticamente com a execução paralela de ferramentas com muito menos código.

Aqui está um script completo e executável para testar e verificar se as chamadas de ferramentas paralelas estão funcionando corretamente:

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

Este script demonstra:

Como formatar corretamente chamadas de ferramentas paralelas e resultados
Como verificar que chamadas paralelas estão sendo feitas
A estrutura de mensagem correta que incentiva o uso futuro de ferramentas paralelas
Erros comuns a evitar (como texto antes dos resultados das ferramentas)

Execute este script para testar sua implementação e garantir que Claude está fazendo chamadas de ferramentas paralelas de forma eficaz.

Maximizando o uso paralelo de ferramentas

Embora os modelos Claude 4 tenham excelentes capacidades de uso paralelo de ferramentas por padrão, você pode aumentar a probabilidade de execução paralela de ferramentas em todos os modelos com prompting direcionado:

Resolução de problemas

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

1. Formatação incorreta de resultados de ferramentas

O problema mais comum é formatar incorretamente os resultados das ferramentas no histórico de conversas. Isso "ensina" Claude a evitar chamadas paralelas.

Especificamente para uso paralelo de ferramentas:

❌ Errado: Enviar mensagens de usuário separadas para cada resultado de ferramenta
✅ Correto: Todos os resultados de ferramentas devem estar em uma única mensagem de usuário

// ❌ Isto reduz o uso paralelo de ferramentas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Mensagem separada
]

// ✅ Isto mantém o uso paralelo de ferramentas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Mensagem única
]

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

2. Prompting fraco

O prompting padrão pode não ser suficiente. Use o prompt de sistema mais forte da seção Maximizando o uso paralelo de ferramentas acima.

3. Medindo o uso paralelo de ferramentas

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

# 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

Próximos passos

Para o fluxo de chamada única de ferramenta e regras de formatação de tool_result, consulte Lidar com chamadas de ferramentas.
Para a abstração do SDK que lida com execução paralela automaticamente, consulte Tool Runner.
Para o fluxo de trabalho completo de uso de ferramentas, consulte Definir ferramentas.

Exemplo prático

Maximizando o uso paralelo de ferramentas

Prompts de sistema para uso paralelo de ferramentas

Prompting de mensagem do usuário

Resolução de problemas

Próximos passos