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.
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
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:
Parâmetro | Descrição |
---|---|
name | O nome da ferramenta. Deve corresponder ao 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. |
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:
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:
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 quandotools
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 nenhumatools
é 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:
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
outool
, o que garante que o Claude use exatamente uma ferramenta
Uso paralelo de ferramentas com Claude Sonnet 3.7
O Claude Sonnet 3.7 pode ser menos propenso a fazer chamadas paralelas de ferramentas em uma resposta, mesmo quando você não definiu disable_parallel_tool_use
. Para contornar isso, recomendamos habilitar o uso de ferramentas com eficiência de tokens, o que ajuda a incentivar o Claude a usar ferramentas paralelas. Este recurso beta também reduz a latência e economiza uma média de 14% em tokens de saída.
Se você preferir não optar pelo uso de ferramentas com eficiência de tokens beta, você também pode introduzir uma “ferramenta em lote” que pode atuar como uma meta-ferramenta para agrupar invocações para outras ferramentas simultaneamente. Descobrimos que, se essa ferramenta estiver presente, o modelo a usará para chamar várias ferramentas em paralelo simultaneamente para você.
Veja este exemplo em nosso cookbook para saber como usar essa solução alternativa.
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 oinput_schema
da ferramenta.
Quando você recebe uma resposta de uso de ferramenta para uma ferramenta de cliente, você deve:
- Extrair o
name
,id
einput
do blocotool_use
. - Executar a ferramenta real em seu código correspondente a esse nome de ferramenta, passando a
input
da ferramenta. - Continuar a conversa enviando uma nova mensagem com o
role
deuser
, e um bloco decontent
contendo o tipotool_result
e as seguintes informações:tool_use_id
: Oid
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 tipostext
ouimage
.is_error
(opcional): Definido comotrue
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.
Diferenças de outras APIs
Ao contrário de APIs que separam o uso de ferramentas ou usam funções especiais como tool
ou function
, a API da Anthropic integra ferramentas diretamente na estrutura de mensagens user
e assistant
.
As mensagens contêm arrays de blocos text
, image
, tool_use
e tool_result
. As mensagens user
incluem conteúdo do cliente e tool_result
, enquanto as mensagens assistant
contêm conteúdo gerado por IA e tool_use
.
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
:
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: