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 agêntico funciona e quando o uso de ferramentas é a abordagem correta. Para orientações práticas, 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.

Esse 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 APIs podem integrar o uso de ferramentas da mesma forma que fariam com qualquer outra interface tipada: defina o schema, trate o callback, retorne um resultado. A diferença é que o chamador do outro lado é um modelo de linguagem que escolhe qual função invocar com base na conversa.

Onde as ferramentas são executadas

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

Ferramentas definidas pelo usuário (executadas pelo cliente)

Você escreve o schema, 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 ao 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 schema que você forneceu e o resultado que você retornou.

Ferramentas com schema da Anthropic (executadas pelo cliente)

Para um conjunto de operações comuns (executar comandos shell, editar arquivos, controlar um navegador, gerenciar memória de rascunho), a Anthropic publica o schema da ferramenta e sua aplicação lida com 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 com schema da Anthropic em vez de definir seu próprio equivalente é que esses schemas são treinados internamente. Claude foi otimizado em milhares de trajetórias bem-sucedidas que usam exatamente essas assinaturas de ferramentas, portanto ele as chama de forma mais confiável e se recupera de erros com mais elegância do que faria com uma ferramenta personalizada que faz a mesma coisa. O schema é a interface que o modelo já espera.

Ferramentas executadas pelo 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 cuida de 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 que a resposta chegue até você.

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

O loop agêntico (ferramentas do cliente)

As ferramentas executadas pelo cliente (tanto as definidas pelo usuário quanto as com schema da Anthropic) exigem que sua aplicação conduza um loop. O modelo não pode executar seu código, portanto cada chamada de ferramenta é uma viagem de ida e volta: o modelo solicita, você executa, você reporta de volta, o modelo continua.

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

1. Envie uma solicitação com seu array 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 do passo 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 termina 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 construção de solicitações, tratamento de chamadas de ferramentas paralelas e formatação de resultados, consulte Tratar chamadas de ferramentas.

O loop do lado do servidor

As ferramentas executadas pelo servidor executam seu próprio loop dentro da infraestrutura da Anthropic. Uma única solicitação da sua aplicação pode acionar várias pesquisas na web ou execuções de código antes que uma resposta retorne. O modelo pesquisa, lê os resultados, decide pesquisar novamente e itera até ter o que precisa, tudo sem que sua aplicação participe.

Este loop interno tem um limite de iterações. Se o modelo ainda estiver iterando quando atingir o limite, a resposta retorna com stop_reason: "pause_turn" em vez de "end_turn". Um turno pausado significa que o trabalho não está concluído; reenvie a conversa (incluindo a resposta pausada) para permitir que o modelo continue 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 é adequado quando a tarefa requer algo que o modelo não pode fazer apenas com texto:

• Ações com efeitos colaterais. Enviar um e-mail, escrever um arquivo, atualizar um registro. O modelo pode descrever essas ações, mas apenas uma ferramenta pode realizá-las.
• Dados frescos ou externos. Preços atuais, o clima de hoje, o conteúdo de um banco de dados. Qualquer coisa fora dos dados de treinamento ou específica ao 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 texto que por acaso contém a informação, um schema 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 atendem.

O sinal de que você deveria 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 schema.

O uso de ferramentas não é adequado quando:

• O modelo pode responder apenas com o treinamento. Resumo, tradução e perguntas de conhecimento geral não precisam de uma viagem de ida e volta com ferramenta.
• A interação é uma pergunta e resposta única sem efeitos colaterais. Se não há nada a 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 superar o trabalho.

Escolhendo entre abordagens

Próximos passos