Como implementar o uso de ferramentas

​

Escolhendo um modelo

Geralmente, use Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 ou Claude Opus 3 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 observe que eles podem inferir parâmetros ausentes.

​

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:

​

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 deve ser XML válido e é analisada com expressões regulares.
Aqui estão as funções disponíveis no 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 advertências 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. Procure 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.

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 é fornecida.

Este diagrama ilustra como cada opção funciona:

Note que quando você tem tool_choice como any ou tool, 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.

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 tempo 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 funcional completo.

​

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 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 tempo em São Francisco agora, e que horas são lá?”, Claude pode responder com:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Para responder a esta pergunta, 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.</thinking>"
    },
    {
      "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.

Com o modelo Claude Sonnet 3, a cadeia de pensamento é menos comum por padrão, mas você pode induzir Claude a mostrar seu raciocínio adicionando algo como "Antes de responder, explique seu raciocínio passo a passo em tags." à mensagem do usuário ou prompt do sistema.

É importante notar que embora as tags <thinking> sejam uma convenção comum que Claude usa para denotar sua cadeia de pensamento, o formato exato (como o nome desta tag XML) pode mudar ao longo do tempo. Seu código deve tratar a cadeia de pensamento como qualquer outro texto gerado pelo assistente, e não depender da presença ou formatação específica das tags <thinking>.

​

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

​

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:

​

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

A resposta do Claude difere baseada em se ele usa uma ferramenta do cliente ou 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 de uso de ferramenta específico. 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.

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 seu código correspondente a esse nome de ferramenta, passando a 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") ou lista de blocos de conteúdo aninhados (ex. "content": [{"type": "text", "text": "15 graus"}]). Estes blocos de conteúdo podem usar os tipos text ou image.
   • is_error (opcional): Defina como true se a execução da ferramenta resultou em erro.

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

{"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
]}

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.

​

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.

# 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-20250514",
            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:

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: