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 simples, mas observe que eles podem inferir parâmetros ausentes.

​

Especificando ferramentas do cliente

As 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:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

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 da ferramenta. Suas descrições devem explicar cada detalhe 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 quais 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 incluir 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 somente depois de ter elaborado completamente a descrição.

A boa descrição explica claramente o que a ferramenta faz, quando usá-la, quais dados ela retorna e o que o parâmetro ticker significa. A descrição ruim é muito breve e deixa o Claude com muitas questões em aberto 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 o Claude use uma ferramenta específica para responder à pergunta do usuário, mesmo que o 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 o Claude decida se deve chamar quaisquer ferramentas fornecidas 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 permite forçar o Claude a sempre usar uma ferramenta específica.
• none impede que o Claude use qualquer ferramenta. Este é o valor padrão quando nenhuma tools é fornecida.

Este diagrama ilustra como cada opção funciona:

Observe 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 de cadeia de pensamento text antes dos blocos de conteúdo tool_use, mesmo se explicitamente solicitados a fazê-lo.

Nossos testes mostraram que isso não deve reduzir o desempenho. Se você quiser manter a cadeia de pensamento (particularmente com o 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

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

​

Cadeia de pensamento

Ao usar ferramentas, o Claude frequentemente mostrará sua “cadeia de pensamento”, ou seja, o raciocínio passo a passo que ele usa para decompor 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 o Sonnet e o 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á?”, o Claude pode responder com:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

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

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

É importante observar que, embora as tags <thinking> sejam uma convenção comum que o Claude usa para denotar sua cadeia de pensamento, o formato exato (como o nome dessa tag XML) pode mudar com o 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, o Claude pode usar várias ferramentas para responder a uma consulta do usuário. Você pode desativar esse comportamento:

• Definindo disable_parallel_tool_use=true quando o tipo de tool_choice é auto, o que garante que o 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 o Claude use exatamente uma ferramenta

​

Manipulando blocos de conteúdo de uso de ferramentas e resultados de ferramentas

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

​

Manipulando 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 posteriormente.
• 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 de 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 de content contendo o tipo tool_result e as seguintes informações:
   • tool_use_id: O id da solicitação de uso da ferramenta para a qual este é um resultado.
   • content: O resultado da ferramenta, como uma string (por exemplo, "content": "15 degrees") ou lista de blocos de conteúdo aninhados (por exemplo, "content": [{"type": "text", "text": "15 degrees"}]). Esses blocos de conteúdo podem usar os tipos text ou image.
   • is_error (opcional): Definido como true se a execução da ferramenta resultou em um erro.

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

​

Manipulando resultados de ferramentas do servidor

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

​

Manipulando o motivo de parada pause_turn

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

Veja como lidar com o motivo de parada pause_turn:

import anthropic

client = anthropic.Anthropic()

# Solicitação inicial com pesquisa na web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 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": "Search for comprehensive information about quantum computing breakthroughs in 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 lidar com pause_turn:

• Continue a conversa: Passe a resposta pausada de volta como está em uma solicitação subsequente para permitir que o Claude continue 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 problemas de erros

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