Como implementar o uso de ferramentas

Escolhendo um modelo

Recomendamos usar o modelo Claude Opus (4.6) mais recente para ferramentas complexas e consultas ambíguas; ele lida melhor com múltiplas ferramentas e busca esclarecimentos quando necessário.

Use modelos Claude Haiku para ferramentas diretas, mas observe que eles podem inferir parâmetros ausentes.

Especificando ferramentas do cliente

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

Prompt do sistema de uso de ferramentas

Quando você chama a API Claude com o parâmetro tools, construímos um prompt do sistema especial a partir das definições de ferramentas, configuração de ferramentas e qualquer prompt do 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 funcione 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 for pouco claro. Quanto mais contexto você puder dar ao Claude sobre suas ferramentas, melhor ele será em decidir quando e como usá-las. Procure por pelo menos 3-4 frases por descrição de ferramenta, mais se a ferramenta for complexa.
• Priorize descrições, mas considere usar input_examples para ferramentas complexas. Descrições claras são mais importantes, mas para ferramentas com entradas complexas, objetos aninhados ou parâmetros sensíveis ao formato, você pode usar o campo input_examples (beta) para fornecer exemplos validados por schema. Veja Fornecendo exemplos de uso de ferramentas para detalhes.

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 Claude com muitas questões em aberto sobre o comportamento e uso da ferramenta.

Fornecendo exemplos de uso de ferramentas

Você pode fornecer exemplos concretos de entradas de ferramentas válidas para ajudar Claude a entender como usar suas ferramentas de forma mais eficaz. Isso é particularmente útil para ferramentas complexas com objetos aninhados, parâmetros opcionais ou entradas sensíveis ao formato.

Uso básico

Adicione um campo input_examples opcional à sua definição de ferramenta com uma matriz de objetos de entrada de exemplo. Cada exemplo deve ser válido de acordo com o input_schema da ferramenta:

Os exemplos são incluídos no prompt junto com seu schema de ferramenta, mostrando ao Claude padrões concretos para chamadas de ferramentas bem formadas. Isso ajuda Claude a entender quando incluir parâmetros opcionais, quais formatos usar e como estruturar entradas complexas.

Requisitos e limitações

• Validação de schema - Cada exemplo deve ser válido de acordo com o input_schema da ferramenta. Exemplos inválidos retornam um erro 400
• Não suportado para ferramentas do lado do servidor - Apenas ferramentas definidas pelo usuário podem ter exemplos de entrada
• Custo de token - Os exemplos adicionam aos tokens de prompt: ~20-50 tokens para exemplos simples, ~100-200 tokens para objetos aninhados complexos

Executor de ferramentas (beta)

O executor de ferramentas fornece uma solução pronta para executar ferramentas com Claude. Em vez de lidar manualmente com chamadas de ferramentas, resultados de ferramentas e gerenciamento de conversas, o executor de ferramentas automaticamente:

• Executa ferramentas quando Claude as chama
• Lida com o ciclo de solicitação/resposta
• Gerencia o estado da conversa
• Fornece segurança de tipo e validação

Recomendamos que você use o executor de ferramentas para a maioria das implementações de uso de ferramentas.

Uso básico

Defina ferramentas usando os auxiliares do SDK e, em seguida, use o executor de ferramentas para executá-las.

A função de ferramenta deve retornar um bloco de conteúdo ou matriz de blocos de conteúdo, incluindo texto, imagens ou blocos de documento. Isso permite que ferramentas retornem respostas ricas e multimodais. Strings retornadas serão convertidas em um bloco de conteúdo de texto. Se você quiser retornar um objeto JSON estruturado para Claude, codifique-o como uma string JSON antes de retorná-lo. Números, booleanos ou outras primitivas não-string também devem ser convertidas para strings.

Iterando sobre o executor de ferramentas

O executor de ferramentas é um iterável que produz mensagens do Claude. Isso é frequentemente referido como um "loop de chamada de ferramenta". A cada iteração, o executor verifica se Claude solicitou um uso de ferramenta. Se sim, ele chama a ferramenta e envia o resultado de volta para Claude automaticamente, depois produz a próxima mensagem do Claude para continuar seu loop.

Você pode encerrar o loop em qualquer iteração com uma instrução break. O executor fará loop até que Claude retorne uma mensagem sem um uso de ferramenta.

Se você não precisar de mensagens intermediárias, pode obter a mensagem final diretamente:

Uso avançado

Dentro do loop, você pode personalizar completamente a próxima solicitação do executor de ferramentas para a API de Mensagens. O executor automaticamente anexa resultados de ferramentas ao histórico de mensagens, então você não precisa gerenciá-los manualmente. Você pode opcionalmente inspecionar o resultado da ferramenta para logging ou depuração e modificar os parâmetros da solicitação antes da próxima chamada da API.

Depurando execução de ferramentas

Quando uma ferramenta lança uma exceção, o executor de ferramentas a captura e retorna o erro para Claude como um resultado de ferramenta com is_error: true. Por padrão, apenas a mensagem de exceção é incluída, não o rastreamento de pilha completo.

Para visualizar rastreamentos de pilha completos e informações de depuração, defina a variável de ambiente ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Quando habilitado, o SDK registra detalhes completos de exceção (usando o módulo logging do Python, o console em TypeScript ou o logger do Ruby), incluindo o rastreamento de pilha completo quando uma ferramenta falha.

Interceptando erros de ferramentas

Por padrão, erros de ferramentas são passados de volta para Claude, que pode então responder apropriadamente. No entanto, você pode querer detectar erros e tratá-los diferentemente—por exemplo, para parar a execução antecipadamente ou implementar tratamento de erro personalizado.

Use o método de resposta de ferramenta para interceptar resultados de ferramentas e verificar erros antes de serem enviados para Claude:

Modificando resultados de ferramentas

Você pode modificar resultados de ferramentas antes de serem enviados de volta para Claude. Isso é útil para adicionar metadados como cache_control para habilitar cache de prompt em resultados de ferramentas, ou para transformar a saída da ferramenta.

Use o método de resposta de ferramenta para obter o resultado da ferramenta, modificá-lo e, em seguida, adicionar sua versão modificada às mensagens:

Streaming

Habilite streaming para receber eventos conforme chegam. Cada iteração produz um objeto de stream que você pode iterar para eventos.

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 uma das 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 particular.
• tool permite que forcemos Claude a sempre usar uma ferramenta particular.
• none impede que 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 uma resposta em linguagem natural ou explicação antes dos blocos de conteúdo tool_use, mesmo que explicitamente solicitado.

Nossos testes mostraram que isso não deve reduzir o desempenho. Se você gostaria que o modelo fornecesse contexto em linguagem natural ou explicações enquanto ainda solicitasse 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: What's the weather like in London? Use the get_weather tool in your response.

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 saída JSON que siga um esquema fornecido. Por exemplo, você pode usar uma ferramenta record_summary com um esquema particular. Veja Uso de ferramentas com Claude para um exemplo completo funcionando.

Respostas do modelo com ferramentas

Ao usar ferramentas, Claude frequentemente comentará sobre o que está fazendo ou responderá naturalmente ao usuário antes de invocar ferramentas.

Por exemplo, dado o prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude pode responder com:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Este estilo de resposta natural ajuda os usuários a entender o que Claude está fazendo e cria uma interação mais conversacional. Você pode guiar o estilo e o conteúdo dessas respostas através de seus prompts do sistema e fornecendo <examples> em seus prompts.

É importante notar que Claude pode usar várias frases e abordagens ao explicar suas ações. Seu código deve tratar essas respostas 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 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

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:

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

A resposta do Claude difere dependendo se ele usa uma ferramenta de cliente ou servidor.

Manipulando resultados de ferramentas de 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 particular. 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 de 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 ao nome da 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 (por exemplo, ), uma lista de blocos de conteúdo aninhados (por exemplo, ), ou uma lista de blocos de documento (por exemplo, ). Estes blocos de conteúdo podem usar os tipos , ou .

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Text before tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

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

Manipulando resultados de ferramentas de servidor

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 max_tokens

Se a resposta do Claude for cortada devido ao limite max_tokens e a resposta truncada contiver 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 de ferramenta completo.

Manipulando o motivo de parada pause_turn

Ao usar ferramentas de servidor como busca na web, a API pode retornar um motivo de parada pause_turn, indicando que a API pausou uma volta longa.

Aqui está como manipular o motivo de parada pause_turn:

Ao manipular pause_turn:

• Continue a conversa: Passe a resposta pausada como está em uma solicitação subsequente para deixar Claude continuar sua volta
• 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

Resolvendo problemas de erros

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

Isto está correto:

Se você receber um erro como "tool_use ids were found without tool_result blocks immediately after", verifique se seus resultados de ferramentas estão formatados corretamente.