Loading...
    • Construir
    • Admin
    • Modelos e preços
    • SDKs do cliente
    • Referência da API
    Search...
    ⌘K
    Log in
    Uso paralelo de ferramentas
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Construir/Ferramentas

    Uso paralelo de ferramentas

    Ative e formate chamadas de ferramentas paralelas, com orientação de histórico de mensagens e resolução de problemas.

    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.

    Was this page helpful?

    • Exemplo prático
    • Maximizando o uso paralelo de ferramentas
    • Resolução de problemas
    • Próximos passos