Como o uso de ferramentas funciona

Esta página explica os conceitos por trás do uso de ferramentas: onde as ferramentas são executadas, como o loop agentico funciona e quando o uso de ferramentas é a abordagem correta. Para orientação prática, comece com o tutorial ou o guia de implementação.

O contrato de uso de ferramentas

O uso de ferramentas é um contrato entre sua aplicação e o modelo. Você especifica quais operações estão disponíveis e qual é a forma de suas entradas e saídas; Claude decide quando e como chamá-las. O modelo nunca executa nada por conta própria. Ele emite uma solicitação estruturada, seu código (ou os servidores da Anthropic) executa a operação e o resultado flui de volta para a conversa.

Este contrato faz o modelo se comportar menos como um gerador de texto e mais como uma função que você chama. Engenheiros com experiência clássica em API podem integrar o uso de ferramentas da mesma forma que fariam com qualquer outra interface tipada: defina o esquema, trate o callback, retorne um resultado. A diferença é que o chamador do outro lado é um modelo de linguagem escolhendo qual função invocar com base na conversa.

Onde as ferramentas são executadas

O eixo principal ao longo do qual as ferramentas diferem é onde o código é executado. Cada ferramenta se enquadra em um dos três grupos, e o grupo determina pelo que sua aplicação é responsável.

Ferramentas definidas pelo usuário (executadas no cliente)

Você escreve o esquema, você executa o código, você retorna os resultados. Este é o evento principal: a grande maioria do tráfego de uso de ferramentas são ferramentas definidas pelo usuário chamando lógica específica da aplicação.

Quando Claude decide usar uma de suas ferramentas, a resposta da API contém um bloco tool_use com o nome da ferramenta e um objeto JSON de argumentos. Sua aplicação extrai esses argumentos, executa a operação (uma consulta de banco de dados, uma chamada HTTP, uma escrita de arquivo, o que quer que a ferramenta faça) e envia a saída de volta em um bloco tool_result na próxima solicitação. Claude nunca vê sua implementação; ele apenas vê o esquema que você forneceu e o resultado que você retornou.

Ferramentas de esquema Anthropic (executadas no cliente)

Para um punhado de operações comuns (executar comandos shell, editar arquivos, controlar um navegador, gerenciar memória de bloco de rascunho), a Anthropic publica o esquema da ferramenta e sua aplicação trata a execução. As ferramentas nesta categoria são bash, text_editor, computer e memory.

O modelo de execução é idêntico ao das ferramentas definidas pelo usuário: a resposta contém um bloco tool_use, seu código executa a operação e você envia de volta um tool_result. A razão para usar uma ferramenta de esquema Anthropic em vez de definir sua própria equivalente é que esses esquemas são treinados. Claude foi otimizado em milhares de trajetórias bem-sucedidas que usam essas assinaturas de ferramenta exatas, então ele as chama com mais confiabilidade e se recupera de erros com mais elegância do que faria com uma ferramenta personalizada que faz a mesma coisa. O esquema é a interface que o modelo já espera.

Ferramentas executadas no servidor

Para web_search, web_fetch, code_execution e tool_search, a Anthropic executa o código. Você habilita a ferramenta em sua solicitação e o servidor trata todo o resto. Você nunca constrói um bloco tool_result para essas ferramentas porque o loop do lado do servidor executa a operação e alimenta a saída de volta ao modelo antes da resposta chegar até você.

A resposta que você recebe contém blocos server_tool_use mostrando o que foi executado e o que voltou, mas no momento em que você os vê, a execução já está completa. O trabalho de sua aplicação é habilitar a ferramenta e ler a resposta final, não participar do loop de execução.

O loop agentico (ferramentas do cliente)

Ferramentas executadas no cliente (tanto definidas pelo usuário quanto esquema Anthropic) exigem que sua aplicação conduza um loop. O modelo não pode executar seu código, então cada chamada de ferramenta é uma viagem de ida e volta: o modelo pergunta, você executa, você relata, o modelo continua.

A forma canônica é um loop while baseado em stop_reason:

1. Envie uma solicitação com sua matriz tools e a mensagem do usuário.
2. Claude responde com stop_reason: "tool_use" e um ou mais blocos tool_use.
3. Execute cada ferramenta. Formate as saídas como blocos tool_result.
4. Envie uma nova solicitação contendo as mensagens originais, a resposta do assistente e uma mensagem do usuário com os blocos tool_result.
5. Repita a partir da etapa 2 enquanto stop_reason for "tool_use".

Na prática, isso se lê como: enquanto stop_reason == "tool_use", execute as ferramentas e continue a conversa. O loop sai em qualquer outro motivo de parada ("end_turn", "max_tokens", "stop_sequence" ou "refusal"), o que significa que Claude produziu uma resposta final ou parou por outro motivo que sua aplicação deve tratar.

Para a mecânica de construir solicitações, lidar com chamadas de ferramentas paralelas e formatar resultados, consulte Lidar com chamadas de ferramentas.

O loop do lado do servidor

Ferramentas executadas no servidor executam seu próprio loop dentro da infraestrutura da Anthropic. Uma única solicitação de sua aplicação pode disparar várias buscas na web ou execuções de código antes de uma resposta voltar. O modelo busca, lê resultados, decide buscar novamente e itera até ter o que precisa, tudo sem sua aplicação participar.

Este loop interno tem um limite de iteração. Se o modelo ainda estiver iterando quando atingir o limite, a resposta volta com stop_reason: "pause_turn" em vez de "end_turn". Uma volta pausada significa que o trabalho não está terminado; reenvie a conversa (incluindo a resposta pausada) para deixar o modelo continuar de onde parou. Consulte Ferramentas do servidor para o padrão de continuação.

Quando usar ferramentas (e quando não usar)

O uso de ferramentas se encaixa quando a tarefa requer algo que o modelo não pode fazer apenas com texto:

• Ações com efeitos colaterais. Enviar um email, escrever um arquivo, atualizar um registro. O modelo pode descrever essas ações, mas apenas uma ferramenta pode executá-las.
• Dados frescos ou externos. Preços atuais, o tempo de hoje, o conteúdo de um banco de dados. Qualquer coisa fora dos dados de treinamento ou específica do seu sistema precisa de uma ferramenta para buscá-la.
• Saídas estruturadas com forma garantida. Quando você precisa de um objeto JSON com campos específicos em vez de prosa que acontece conter a informação, um esquema de ferramenta impõe a forma.
• Chamadas para sistemas existentes. Bancos de dados, APIs internas, sistemas de arquivos. O uso de ferramentas é a ponte entre solicitações em linguagem natural e os sistemas que as cumprem.

O indicador de que você deve estar usando ferramentas: se você está escrevendo uma regex para extrair uma decisão da saída do modelo, essa decisão deveria ter sido uma chamada de ferramenta. Analisar texto de forma livre para recuperar intenção estruturada é um sinal de que a estrutura pertence ao esquema.

O uso de ferramentas não se encaixa quando:

• O modelo pode responder apenas do treinamento. Resumo, tradução e perguntas de conhecimento geral não precisam de uma viagem de ida e volta de ferramenta.
• A interação é Q&A único com nenhum efeito colateral. Se não há nada para executar, não há nada para uma ferramenta fazer.
• A latência de chamada de ferramenta dominaria uma resposta trivial. Cada chamada de ferramenta é pelo menos uma viagem de ida e volta extra; para tarefas leves, a sobrecarga pode exceder o trabalho.

Escolhendo entre abordagens

Próximas etapas