Como implementar o uso de ferramentas

Aprenda a implementar o uso de ferramentas com Claude, incluindo definições de ferramentas, controle de saída e tratamento de erros.

Escolhendo um modelo

Geralmente, use Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (descontinuado) ou Claude Opus 3 (descontinuado) para ferramentas complexas e consultas ambíguas; eles lidam melhor com múltiplas ferramentas e buscam esclarecimentos quando necessário.

Use Claude Haiku 3.5 ou Claude Haiku 3 para ferramentas diretas, mas note que eles podem inferir parâmetros ausentes.

Se estiver usando Claude Sonnet 3.7 com uso de ferramentas e pensamento estendido, consulte nosso guia aqui para mais informações.

Especificando ferramentas do cliente

Ferramentas do cliente (tanto definidas pela Anthropic quanto pelo usuário) são especificadas no parâmetro de nível superior tools da solicitação da API. Cada definição de ferramenta inclui:

Parâmetro	Descrição
name	O nome da ferramenta. Deve corresponder à regex ^[a-zA-Z0-9_-]{1,64}$.
description	Uma descrição detalhada em texto simples do que a ferramenta faz, quando deve ser usada e como se comporta.
input_schema	Um objeto JSON Schema definindo os parâmetros esperados para a ferramenta.

Exemplo de definição de ferramenta simples

JSON

{
  "name": "get_weather",
  "description": "Obter o clima atual em um local específico",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "A cidade e estado, ex. São Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "A unidade de temperatura, 'celsius' ou 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Esta ferramenta, chamada get_weather, espera um objeto de entrada com uma string location obrigatória e uma string unit opcional que deve ser “celsius” ou “fahrenheit”.

Prompt do sistema para uso de ferramentas

Quando você chama a API da Anthropic com o parâmetro tools, construímos um prompt de sistema especial a partir das definições de ferramentas, configuração de ferramentas e qualquer prompt de sistema especificado pelo usuário. O prompt construído é projetado para instruir o modelo a usar a(s) ferramenta(s) especificada(s) e fornecer o contexto necessário para que a ferramenta opere adequadamente:

Neste ambiente você tem acesso a um conjunto de ferramentas que pode usar para responder à pergunta do usuário.
{{ INSTRUÇÕES DE FORMATAÇÃO }}
Parâmetros de string e escalares devem ser especificados como estão, enquanto listas e objetos devem usar formato JSON. Note que espaços para valores de string não são removidos. A saída não é esperada ser XML válido e é analisada com expressões regulares.
Aqui estão as funções disponíveis em formato JSONSchema:
{{ DEFINIÇÕES DE FERRAMENTAS EM JSON SCHEMA }}
{{ PROMPT DO SISTEMA DO USUÁRIO }}
{{ CONFIGURAÇÃO DE FERRAMENTAS }}

Melhores práticas para definições de ferramentas

Para obter o melhor desempenho do Claude ao usar ferramentas, siga estas diretrizes:

• Forneça descrições extremamente detalhadas. Este é de longe o fator mais importante no desempenho das ferramentas. Suas descrições devem explicar todos os detalhes sobre a ferramenta, incluindo:
  • O que a ferramenta faz
  • Quando deve ser usada (e quando não deve)
  • O que cada parâmetro significa e como afeta o comportamento da ferramenta
  • Quaisquer ressalvas ou limitações importantes, como que informações a ferramenta não retorna se o nome da ferramenta não for claro. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Mire em pelo menos 3-4 frases por descrição de ferramenta, mais se a ferramenta for complexa.
• Priorize descrições sobre exemplos. Embora você possa incluir exemplos de como usar uma ferramenta em sua descrição ou no prompt que a acompanha, isso é menos importante do que ter uma explicação clara e abrangente do propósito e parâmetros da ferramenta. Adicione exemplos apenas depois de ter desenvolvido completamente a descrição.

Exemplo de uma boa descrição de ferramenta

JSON

{
  "name": "get_stock_price",
  "description": "Recupera o preço atual da ação para um símbolo ticker específico. O símbolo ticker deve ser um símbolo válido para uma empresa de capital aberto em uma grande bolsa de valores dos EUA como NYSE ou NASDAQ. A ferramenta retornará o preço da última negociação em USD. Deve ser usada quando o usuário perguntar sobre o preço atual ou mais recente de uma ação específica. Não fornecerá nenhuma outra informação sobre a ação ou empresa.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "O símbolo ticker da ação, ex. AAPL para Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Exemplo de descrição de ferramenta ruim

JSON

{
  "name": "get_stock_price",
  "description": "Obtém o preço da ação para um ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

A boa descrição explica claramente o que a ferramenta faz, quando usá-la, que dados retorna e o que o parâmetro ticker significa. A descrição ruim é muito breve e deixa Claude com muitas questões abertas sobre o comportamento e uso da ferramenta.

Controlando a saída do Claude

Forçando o uso de ferramentas

Em alguns casos, você pode querer que Claude use uma ferramenta específica para responder à pergunta do usuário, mesmo que Claude pense que pode fornecer uma resposta sem usar uma ferramenta. Você pode fazer isso especificando a ferramenta no campo tool_choice assim:

tool_choice = {"type": "tool", "name": "get_weather"}

Ao trabalhar com o parâmetro tool_choice, temos quatro opções possíveis:

• auto permite que Claude decida se deve chamar qualquer ferramenta fornecida ou não. Este é o valor padrão quando tools são fornecidas.
• any diz ao Claude que ele deve usar uma das ferramentas fornecidas, mas não força uma ferramenta específica.
• tool nos permite forçar Claude a sempre usar uma ferramenta específica.
• none impede Claude de usar qualquer ferramenta. Este é o valor padrão quando nenhuma tools são fornecidas.

Ao usar cache de prompt, mudanças no parâmetro tool_choice invalidarão blocos de mensagem em cache. Definições de ferramentas e prompts de sistema permanecem em cache, mas o conteúdo da mensagem deve ser reprocessado.

Este diagrama ilustra como cada opção funciona:

Note que quando você tem tool_choice como any ou tool, nós preencheremos previamente a mensagem do assistente para forçar o uso de uma ferramenta. Isso significa que os modelos não emitirão um bloco de conteúdo text de cadeia de pensamento antes dos blocos de conteúdo tool_use, mesmo se explicitamente solicitado a fazê-lo.

Ao usar pensamento estendido com uso de ferramentas, tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} não são suportados e resultarão em erro. Apenas tool_choice: {"type": "auto"} (o padrão) e tool_choice: {"type": "none"} são compatíveis com pensamento estendido.

Nossos testes mostraram que isso não deve reduzir o desempenho. Se você gostaria de manter a cadeia de pensamento (particularmente com Opus) enquanto ainda solicita que o modelo use uma ferramenta específica, você pode usar {"type": "auto"} para tool_choice (o padrão) e adicionar instruções explícitas em uma mensagem user. Por exemplo: Como está o clima em Londres? Use a ferramenta get_weather em sua resposta.

Saída JSON

Ferramentas não precisam necessariamente ser funções do cliente — você pode usar ferramentas sempre que quiser que o modelo retorne saída JSON que segue um esquema fornecido. Por exemplo, você pode usar uma ferramenta record_summary com um esquema específico. Veja Uso de ferramentas com Claude para um exemplo completo funcionando.

Cadeia de pensamento

Ao usar ferramentas, Claude frequentemente mostrará sua “cadeia de pensamento”, ou seja, o raciocínio passo a passo que usa para quebrar o problema e decidir quais ferramentas usar. O modelo Claude Opus 3 (descontinuado) fará isso se tool_choice estiver definido como auto (este é o valor padrão, veja Forçando o uso de ferramentas), e Sonnet e Haiku podem ser induzidos a fazê-lo.

Por exemplo, dado o prompt “Como está o clima em São Francisco agora, e que horas são lá?”, Claude pode responder com:

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Para responder a esta pergunta, eu vou: 1. Usar a ferramenta get_weather para obter o clima atual em São Francisco. 2. Usar a ferramenta get_time para obter a hora atual no fuso horário America/Los_Angeles, que cobre São Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "São Francisco, CA"}
    }
  ]
}

Esta cadeia de pensamento dá insights sobre o processo de raciocínio do Claude e pode ajudar você a depurar comportamentos inesperados.

É importante notar que Claude pode usar vários formatos para denotar sua cadeia de pensamento. Seu código deve tratar a cadeia de pensamento como qualquer outro texto gerado pelo assistente, e não depender de convenções de formatação específicas.

Uso paralelo de ferramentas

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

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

Exemplo completo de uso paralelo de ferramentas

Aqui está um exemplo completo mostrando como formatar adequadamente chamadas de ferramentas paralelas no histórico de mensagens:

Python

import anthropic

client = anthropic.Anthropic()

# Definir ferramentas
tools = [
    {
        "name": "get_weather",
        "description": "Obter o clima atual em um local específico",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "A cidade e estado, ex. São Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obter a hora atual em um fuso horário específico",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "O fuso horário, ex. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Solicitação inicial
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "Como está o clima em SF e NYC, e que horas são lá?"
        }
    ]
)

# Resposta do Claude com chamadas de ferramentas paralelas
print("Claude quer usar ferramentas:", response.stop_reason == "tool_use")
print("Número de chamadas de ferramentas:", len([c for c in response.content if c.type == "tool_use"]))

# Construir a conversa com resultados das ferramentas
messages = [
    {
        "role": "user",
        "content": "Como está o clima em SF e NYC, e que horas são lá?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contém múltiplos blocos tool_use
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Deve corresponder ao ID do tool_use
                "content": "São Francisco: 20°C, parcialmente nublado"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "Nova York: 7°C, céu limpo"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "Horário de São Francisco: 14:30 PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "Horário de Nova York: 17:30 EST"
            }
        ]
    }
]

# Obter resposta final
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

A mensagem do assistente com chamadas de ferramentas paralelas ficaria assim:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Vou verificar o clima e a hora para São Francisco e Nova York."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "São Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "Nova York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

Script de teste completo para ferramentas paralelas

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

Python

#!/usr/bin/env python3
"""Script de teste para verificar chamadas de ferramentas paralelas com a API da Anthropic"""

import os
from anthropic import Anthropic

# Inicializar cliente
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Definir ferramentas
tools = [
    {
        "name": "get_weather",
        "description": "Obter o clima atual em um local específico",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "A cidade e estado, ex. São Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obter a hora atual em um fuso horário específico",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "O fuso horário, ex. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Conversa de teste com chamadas de ferramentas paralelas
messages = [
    {
        "role": "user",
        "content": "Como está o clima em SF e NYC, e que horas são lá?"
    }
]

# Fazer solicitação inicial
print("Solicitando chamadas de ferramentas paralelas...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Verificar chamadas de ferramentas paralelas
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude fez {len(tool_uses)} chamadas de ferramentas")

if len(tool_uses) > 1:
    print("✓ Chamadas de ferramentas paralelas detectadas!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ Nenhuma chamada de ferramenta paralela detectada")

# Simular execução de ferramentas e formatar resultados corretamente
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "São Francisco" in str(tool_use.input):
            result = "São Francisco: 20°C, parcialmente nublado"
        else:
            result = "Nova York: 7°C, céu limpo"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "14:30 PST"
        else:
            result = "17:30 EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continuar conversa com resultados das ferramentas
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # Todos os resultados em uma mensagem!
])

# Obter resposta final
print("\nObtendo resposta final...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nResposta do Claude:\n{final_response.content[0].text}")

# Verificar formatação
print("\n--- Verificação ---")
print(f"✓ Resultados das ferramentas enviados em mensagem única do usuário: {len(tool_results)} resultados")
print("✓ Nenhum texto antes dos resultados das ferramentas no array de conteúdo")
print("✓ Conversa formatada corretamente para uso futuro de ferramentas paralelas")

Este script demonstra:

• Como formatar adequadamente chamadas e resultados de ferramentas paralelas
• Como verificar se chamadas paralelas estão sendo feitas
• A estrutura correta de mensagem 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 esteja fazendo chamadas de ferramentas paralelas efetivamente.

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:

Prompts de sistema para uso paralelo de ferramentas

Para modelos Claude 4 (Opus 4.1, Opus 4 e Sonnet 4), adicione isso ao seu prompt de sistema:

Para máxima eficiência, sempre que você precisar realizar múltiplas operações independentes, invoque todas as ferramentas relevantes simultaneamente em vez de sequencialmente.

Para uso ainda mais forte de ferramentas paralelas (recomendado se o padrão não for suficiente), use:

<use_parallel_tool_calls>
Para máxima eficiência, sempre que você realizar múltiplas operações independentes, invoque todas as ferramentas relevantes simultaneamente em vez de sequencialmente. Priorize chamar ferramentas em paralelo sempre que possível. Por exemplo, ao ler 3 arquivos, execute 3 chamadas de ferramentas em paralelo para ler todos os 3 arquivos no contexto ao mesmo tempo. Ao executar múltiplos comandos somente leitura como `ls` ou `list_dir`, sempre execute todos os comandos em paralelo. Erre do lado de maximizar chamadas de ferramentas paralelas em vez de executar muitas ferramentas sequencialmente.
</use_parallel_tool_calls>

Prompting de mensagem do usuário

Você também pode incentivar o uso paralelo de ferramentas dentro de mensagens específicas do usuário:

# Em vez de:
"Como está o clima em Paris? Também verifique Londres."

# Use:
"Verifique o clima em Paris e Londres simultaneamente."

# Ou seja explícito:
"Por favor, use chamadas de ferramentas paralelas para obter o clima para Paris, Londres e Tóquio ao mesmo tempo."

Uso paralelo de ferramentas com Claude Sonnet 3.7

Claude Sonnet 3.7 pode ser menos provável de fazer chamadas de ferramentas paralelas em uma resposta, mesmo quando você não definiu disable_parallel_tool_use. Para contornar isso, recomendamos habilitar uso eficiente de ferramentas em tokens, que ajuda a incentivar Claude a usar ferramentas paralelas. Este recurso beta também reduz latência e economiza uma média de 14% em tokens de saída.

Se você preferir não optar pelo beta de uso eficiente de ferramentas em tokens, você também pode introduzir uma “ferramenta em lote” que pode atuar como uma meta-ferramenta para envolver invocações para outras ferramentas simultaneamente. Descobrimos que se esta ferramenta estiver presente, o modelo a usará para chamar simultaneamente múltiplas ferramentas em paralelo para você.

Veja este exemplo em nosso cookbook para como usar esta solução alternativa.

Tratando blocos de conteúdo de uso de ferramentas e resultado de ferramentas

A resposta do Claude difere com base em se ele usa uma ferramenta do cliente ou do servidor.

Tratando resultados de ferramentas do cliente

A resposta terá um stop_reason de tool_use e um ou mais blocos de conteúdo tool_use que incluem:

• id: Um identificador único para este bloco específico de uso de ferramenta. Isso será usado para corresponder aos resultados da ferramenta mais tarde.
• name: O nome da ferramenta sendo usada.
• input: Um objeto contendo a entrada sendo passada para a ferramenta, em conformidade com o input_schema da ferramenta.

Exemplo de resposta da API com um bloco de conteúdo `tool_use`

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Preciso usar o get_weather, e o usuário quer SF, que provavelmente é São Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "São Francisco, CA", "unit": "celsius"}
    }
  ]
}

Quando você recebe uma resposta de uso de ferramenta para uma ferramenta do cliente, você deve:

1. Extrair o name, id e input do bloco tool_use.
2. Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta, passando o input da ferramenta.
3. Continuar a conversa enviando uma nova mensagem com o role de user, e um bloco content contendo o tipo tool_result e as seguintes informações:
   • tool_use_id: O id da solicitação de uso de ferramenta para a qual este é um resultado.
   • content: O resultado da ferramenta, como uma string (ex. "content": "15 graus"), uma lista de blocos de conteúdo aninhados (ex. "content": [{"type": "text", "text": "15 graus"}]), ou uma lista de blocos de documento (ex. "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 graus"}]). Estes blocos de conteúdo podem usar os tipos text, image ou document.
   • is_error (opcional): Defina como true se a execução da ferramenta resultou em erro.

Requisitos importantes de formatação:

• Blocos de resultado de ferramenta devem seguir imediatamente seus blocos de uso de ferramenta correspondentes no histórico de mensagens. Você não pode incluir nenhuma mensagem entre a mensagem de uso de ferramenta do assistente e a mensagem de resultado de ferramenta do usuário.
• Na mensagem do usuário contendo resultados de ferramentas, os blocos tool_result devem vir PRIMEIRO no array de conteúdo. Qualquer texto deve vir DEPOIS de todos os resultados de ferramentas.

Por exemplo, isso causará um erro 400:

{"role": "user", "content": [
  {"type": "text", "text": "Aqui estão os resultados:"},  // ❌ Texto antes de tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Isso está correto:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "O que devo fazer a seguir?"}  // ✅ Texto depois de tool_result
]}

Se você receber um erro como “tool_use ids foram encontrados sem blocos tool_result imediatamente após”, verifique se seus resultados de ferramentas estão formatados corretamente.

Exemplo de resultado de ferramenta bem-sucedido

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 graus"
    }
  ]
}

Exemplo de resultado de ferramenta com imagens

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 graus"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Exemplo de resultado de ferramenta vazio

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

Exemplo de resultado de ferramenta com documentos

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "O clima está"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 graus"
          }
        }
      ]
    }
  ]
}

Após receber o resultado da ferramenta, Claude usará essa informação para continuar gerando uma resposta ao prompt original do usuário.

Tratando resultados de ferramentas do servidor

Claude executa a ferramenta internamente e incorpora os resultados diretamente em sua resposta sem exigir interação adicional do usuário.

Diferenças de outras APIs

Ao contrário de APIs que separam o uso de ferramentas ou usam papéis especiais como tool ou function, a API da Anthropic integra ferramentas diretamente na estrutura de mensagens user e assistant.

Mensagens contêm arrays de blocos text, image, tool_use e tool_result. Mensagens user incluem conteúdo do cliente e tool_result, enquanto mensagens assistant contêm conteúdo gerado por IA e tool_use.

Tratando o motivo de parada max_tokens

Se a resposta do Claude for cortada devido ao limite max_tokens, e a resposta truncada contém um bloco de uso de ferramenta incompleto, você precisará tentar novamente a solicitação com um valor max_tokens mais alto para obter o uso completo da ferramenta.

Python

# Verificar se a resposta foi truncada durante o uso da ferramenta
if response.stop_reason == "max_tokens":
    # Verificar se o último bloco de conteúdo é um tool_use incompleto
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Enviar a solicitação com max_tokens mais alto
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # Limite aumentado
            messages=messages,
            tools=tools
        )

Tratando o motivo de parada pause_turn

Ao usar ferramentas do servidor como busca na web, a API pode retornar um motivo de parada pause_turn, indicando que a API pausou um turno de longa duração.

Aqui está como tratar o motivo de parada pause_turn:

Python

import anthropic

client = anthropic.Anthropic()

# Solicitação inicial com busca na web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Busque informações abrangentes sobre avanços em computação quântica em 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Verificar se a resposta tem motivo de parada pause_turn
if response.stop_reason == "pause_turn":
    # Continuar a conversa com o conteúdo pausado
    messages = [
        {"role": "user", "content": "Busque informações abrangentes sobre avanços em computação quântica em 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Enviar a solicitação de continuação
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Ao tratar pause_turn:

• Continue a conversa: Passe a resposta pausada de volta como está em uma solicitação subsequente para deixar Claude continuar seu turno
• Modifique se necessário: Você pode opcionalmente modificar o conteúdo antes de continuar se quiser interromper ou redirecionar a conversa
• Preserve o estado da ferramenta: Inclua as mesmas ferramentas na solicitação de continuação para manter a funcionalidade

Solucionando erros

Existem alguns tipos diferentes de erros que podem ocorrer ao usar ferramentas com Claude:

Erro de execução de ferramenta

Se a própria ferramenta gerar um erro durante a execução (ex. um erro de rede ao buscar dados meteorológicos), você pode retornar a mensagem de erro no content junto com "is_error": true:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: a API  do serviço meteorológico não está disponível (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude então incorporará este erro em sua resposta ao usuário, ex. “Desculpe, não consegui recuperar o clima atual porque a API do serviço meteorológico não está disponível. Tente novamente mais tarde.”

Nome de ferramenta inválido

Se a tentativa de uso de ferramenta do Claude for inválida (ex. parâmetros obrigatórios ausentes), geralmente significa que não havia informações suficientes para Claude usar a ferramenta corretamente. Sua melhor aposta durante o desenvolvimento é tentar a solicitação novamente com valores description mais detalhados em suas definições de ferramenta.

No entanto, você também pode continuar a conversa com um tool_result que indica o erro, e Claude tentará usar a ferramenta novamente com as informações ausentes preenchidas:

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Parâmetro obrigatório 'location' ausente",
      "is_error": true
    }
  ]
}

Se uma solicitação de ferramenta for inválida ou estiver faltando parâmetros, Claude tentará novamente 2-3 vezes com correções antes de se desculpar com o usuário.

Tags <search_quality_reflection>

Para impedir que Claude reflita sobre a qualidade da busca com tags <search_quality_reflection>, adicione “Não reflita sobre a qualidade dos resultados de busca retornados em sua resposta” ao seu prompt.

Erros de ferramentas do servidor

Quando ferramentas do servidor encontram erros (ex. problemas de rede com Busca na Web), Claude tratará transparentemente esses erros e tentará fornecer uma resposta alternativa ou explicação ao usuário. Ao contrário das ferramentas do cliente, você não precisa tratar resultados is_error para ferramentas do servidor.

Para busca na web especificamente, códigos de erro possíveis incluem:

• too_many_requests: Limite de taxa excedido
• invalid_input: Parâmetro de consulta de busca inválido
• max_uses_exceeded: Máximo de usos da ferramenta de busca na web excedido
• query_too_long: Consulta excede o comprimento máximo
• unavailable: Ocorreu um erro interno

Chamadas de ferramentas paralelas não funcionando

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

1. Formatação incorreta de resultado de ferramenta

O problema mais comum é formatar incorretamente os resultados das ferramentas no histórico da conversa. Isso “ensina” Claude a evitar chamadas paralelas.

Especificamente para uso paralelo de ferramentas:

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

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

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

Veja os requisitos gerais de formatação acima para outras regras de formatação.

2. Prompting fraco

O prompting padrão pode não ser suficiente. Use linguagem mais forte:

<use_parallel_tool_calls>
Para máxima eficiência, sempre que você realizar múltiplas operações independentes, 
invoque todas as ferramentas relevantes simultaneamente em vez de sequencialmente. 
Priorize chamar ferramentas em paralelo sempre que possível.
</use_parallel_tool_calls>

3. Medindo o uso paralelo de ferramentas

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

# Calcular média de ferramentas por mensagem de chamada de ferramenta
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)
print(f"Média de ferramentas por mensagem: {avg_tools_per_message}")
# Deve ser > 1.0 se chamadas paralelas estiverem funcionando

4. Comportamento específico do modelo

• Claude Opus 4.1, Opus 4 e Sonnet 4: Excelentes no uso paralelo de ferramentas com prompting mínimo
• Claude Sonnet 3.7: Pode precisar de prompting mais forte ou uso eficiente de ferramentas em tokens
• Claude Haiku: Menos provável de usar ferramentas paralelas sem prompting explícito