Escolhendo um modelo
Recomendamos usar o modelo Claude Sonnet (4.5) ou Claude Opus (4.1) mais recente para ferramentas complexas e consultas ambíguas; eles lidam melhor com múltiplas ferramentas e buscam 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 de nível superiortools 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 que define os parâmetros esperados para a ferramenta. |
Exemplo de definição de ferramenta simples
Exemplo de definição de ferramenta simples
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 de uso de ferramentas
Quando você chama a API Claude com o parâmetrotools, 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 as ferramentas especificadas e fornecer o contexto necessário para que a ferramenta funcione corretamente:
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 fornecer 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 sobre exemplos. Embora você possa incluir exemplos de como usar uma ferramenta em sua descrição ou no prompt acompanhante, 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
Exemplo de uma boa descrição de ferramenta
Exemplo de descrição de ferramenta ruim
Exemplo de descrição de ferramenta ruim
ticker significa. A descrição ruim é muito breve e deixa Claude com muitas questões em aberto sobre o comportamento e uso da ferramenta.
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
Uso básico
@beta_tool para definir ferramentas e client.beta.messages.tool_runner() para executá-las.@beta_tool por @beta_async_tool e defina a função com async def.@beta_tool inspecionará os argumentos da função e a docstring para extrair uma representação de esquema json da função fornecida, no exemplo acima calculate_sum será transformado em:Controlando a saída de 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 campotool_choice assim:
autopermite que Claude decida se deve chamar qualquer ferramenta fornecida ou não. Este é o valor padrão quandotoolssão fornecidas.anydiz a Claude que ele deve usar uma das ferramentas fornecidas, mas não força uma ferramenta particular.toolnos permite forçar Claude a sempre usar uma ferramenta particular.noneimpede Claude de usar qualquer ferramenta. Este é o valor padrão quando nenhumatoolsé fornecida.
tool_choice invalidarão blocos de mensagens em cache. Definições de ferramentas e prompts do sistema permanecem em cache, mas o conteúdo da mensagem deve ser reprocessado.
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 se explicitamente solicitado.
tool_choice: {"type": "any"} e tool_choice: {"type": "tool", "name": "..."} não são suportados e resultarão em um erro. Apenas tool_choice: {"type": "auto"} (o padrão) e tool_choice: {"type": "none"} são compatíveis com pensamento estendido.{"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
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 ferramentarecord_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, dada a solicitação “What’s the weather like in San Francisco right now, and what time is it there?”, Claude pode responder com:<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 confiar em 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:- Configurar
disable_parallel_tool_use=truequando o tipo de tool_choice éauto, o que garante que Claude use no máximo uma ferramenta - Configurar
disable_parallel_tool_use=truequando o tipo de tool_choice éanyoutool, o que garante que Claude use exatamente uma ferramenta
Exemplo completo de uso paralelo de ferramentas
Exemplo completo de uso paralelo de ferramentas
Script de teste completo para ferramentas paralelas
Script de teste completo para ferramentas paralelas
- Como formatar corretamente chamadas paralelas de ferramentas e resultados
- Como verificar que chamadas paralelas estão sendo feitas
- A estrutura de mensagem correta que incentiva o uso paralelo de ferramentas no futuro
- Erros comuns a evitar (como texto antes dos resultados das ferramentas)
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 do sistema para uso paralelo de ferramentas
Prompts do sistema para uso paralelo de ferramentas
Prompting de mensagem do usuário
Prompting de mensagem do usuário
disable_parallel_tool_use. Para contornar isso, recomendamos ativar uso eficiente de ferramentas em termos de tokens, que ajuda a incentivar 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 beta de uso eficiente de ferramentas em termos de 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
Tratando resultados de ferramentas de cliente
A resposta terá umstop_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 oinput_schemada ferramenta.
Exemplo de resposta da API com um bloco de conteúdo `tool_use`
Exemplo de resposta da API com um bloco de conteúdo `tool_use`
- Extrair o
name,ideinputdo blocotool_use. - Executar a ferramenta real em sua base de código correspondente a esse nome de ferramenta, passando a
inputda ferramenta. - Continuar a conversa enviando uma nova mensagem com o
roledeusere um blococontentcontendo o tipotool_resulte as seguintes informações:tool_use_id: Oidda solicitação de uso de ferramenta para a qual este é um resultado.content: O resultado da ferramenta, como uma string (por exemplo,"content": "15 degrees"), uma lista de blocos de conteúdo aninhados (por exemplo,"content": [{"type": "text", "text": "15 degrees"}]), ou uma lista de blocos de documento (por exemplo,"content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Estes blocos de conteúdo podem usar os tipostext,imageoudocument.is_error(opcional): Defina comotruese a execução da ferramenta resultou em um erro.
- 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.
Exemplo de resultado de ferramenta bem-sucedido
Exemplo de resultado de ferramenta bem-sucedido
Exemplo de resultado de ferramenta com imagens
Exemplo de resultado de ferramenta com imagens
Exemplo de resultado de ferramenta vazio
Exemplo de resultado de ferramenta vazio
Exemplo de resultado de ferramenta com documentos
Exemplo de resultado de ferramenta com documentos
Tratando 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.tool ou function, a API Claude integra ferramentas diretamente na estrutura de mensagem user e assistant.As 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 de Claude for cortada devido ao limite max_tokens, e a resposta truncada contiver um bloco de uso de ferramenta incompleto, você precisará repetir a solicitação com um valor max_tokens mais alto para obter o uso de ferramenta completo.
Tratando 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 um turno de longa duração.
Aqui está como tratar o motivo de parada pause_turn:
pause_turn:
- Continue a conversa: Passe a resposta pausada 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
Resolvendo problemas de erros
Erro de execução de ferramenta
Erro de execução de ferramenta
content junto com "is_error": true:Nome de ferramenta inválido
Nome de ferramenta inválido
description mais detalhados em suas definições de ferramentas.No entanto, você também pode continuar a conversa para frente com um tool_result que indica o erro, e Claude tentará usar a ferramenta novamente com as informações ausentes preenchidas:Tags <search_quality_reflection>
Tags <search_quality_reflection>
Erros de ferramentas de servidor
Erros de ferramentas de servidor
is_error para ferramentas de servidor.Para busca na web especificamente, os códigos de erro possíveis incluem:too_many_requests: Limite de taxa excedidoinvalid_input: Parâmetro de consulta de busca inválidomax_uses_exceeded: Máximo de usos da ferramenta de busca na web excedidoquery_too_long: Consulta excede o comprimento máximounavailable: Um erro interno ocorreu
Chamadas paralelas de ferramentas não funcionando
Chamadas paralelas de ferramentas não funcionando
- ❌ Errado: Enviar mensagens de usuário separadas para cada resultado de ferramenta
- ✅ Correto: Todos os resultados de ferramentas devem estar em uma única mensagem de usuário
- Claude Opus 4.1, Opus 4 e Sonnet 4: Excelentes em uso paralelo de ferramentas com prompting mínimo
- Claude Sonnet 3.7: Pode precisar de prompting mais forte ou uso eficiente de ferramentas em termos de tokens
- Claude Haiku: Menos provável de usar ferramentas paralelas sem prompting explícito