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çã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 formato suas entradas e saídas assumem; Claude decide quando e como chamá-las. O modelo nunca executa nada por conta própria. Ele emite uma requisiçã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 com que o modelo se comporte 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: definir o schema, tratar o callback, retornar 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 principal eixo ao longo do qual as ferramentas diferem é onde o código é executado. Toda ferramenta se enquadra em uma de três categorias, e a categoria determina pelo que sua aplicação é responsável.



Ferramentas definidas pelo usuário (executadas no 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 consiste em 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 em arquivo, o que quer que a ferramenta faça) e envia a saída de volta em um bloco tool_result na próxima requisição. Claude nunca vê sua implementação; ele vê apenas o schema que você forneceu e o resultado que você retornou.



Ferramentas com schema da Anthropic (executadas no cliente)

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

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 sua própria equivalente é que esses schemas são incorporados ao treinamento. Claude foi otimizado em milhares de trajetórias bem-sucedidas que usam exatamente essas assinaturas de ferramentas, então 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 no servidor

Para web_search, web_fetch, code_execution e tool_search, a Anthropic executa o código. Você habilita a ferramenta em sua requisição e o servidor cuida de todo o resto. Você nunca constrói um bloco tool_result para essas ferramentas. Quando um turno chama apenas ferramentas de servidor, 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 menos que o loop pare antes de terminar, na maioria das vezes porque ele pausa.

A resposta que você recebe contém blocos server_tool_use mostrando o que foi executado e o que retornou. No caso comum, a execução já está completa quando você os vê, e o trabalho da sua aplicação é habilitar a ferramenta e ler a resposta final em vez de participar do loop de execução; as principais exceções são um loop pausado (pause_turn) e um turno que também chama uma ferramenta de cliente.



O loop agêntico (ferramentas de cliente)

Ferramentas executadas no 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, então cada chamada de ferramenta é uma ida e volta: o modelo pede, você executa, você reporta de volta, o modelo continua.

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

1. Envie uma requisiçã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 requisição contendo as mensagens originais, a resposta do assistente e uma mensagem de 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 construir requisições, lidar com chamadas de ferramentas paralelas e formatar resultados, consulte Tratar chamadas de ferramentas.



O loop do lado do servidor

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

Esse 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 de servidor para o padrão de continuação.

O loop também devolve o controle a você antes que uma ferramenta de servidor seja executada se Claude chamar essa ferramenta de servidor e uma ferramenta de cliente no mesmo grupo de chamadas de ferramentas paralelas. A resposta então retorna com stop_reason: "tool_use" e um bloco server_tool_use que ainda não tem bloco de resultado; a API o executa depois que você retorna os resultados da ferramenta de cliente. Consulte Motivos de parada e fallback para o contrato exato.



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 a partir de 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 executá-las.
• Dados atualizados 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 do seu sistema precisa de uma ferramenta para buscá-la.
• Saídas estruturadas com formato garantido. Quando você precisa de um objeto JSON com campos específicos em vez de prosa que por acaso contém a informação, um schema de ferramenta impõe o formato.
• Chamadas a sistemas existentes. Bancos de dados, APIs internas, sistemas de arquivos. O uso de ferramentas é a ponte entre requisiçõ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. Fazer parsing de texto livre para recuperar intenção estruturada é um sinal de que a estrutura pertence ao schema.

O uso de ferramentas não se encaixa quando:

• O modelo pode responder apenas com base no treinamento. Sumarização, tradução e perguntas de conhecimento geral não precisam de uma ida e volta de ferramenta.
• A interação é uma pergunta e resposta única sem efeitos colaterais. Se não há nada para executar, não há nada para uma ferramenta fazer.
• A latência da chamada de ferramenta dominaria uma resposta trivial. Cada chamada de ferramenta é pelo menos uma ida e volta extra; para tarefas leves, a sobrecarga pode exceder o trabalho.



Escolhendo entre abordagens



Próximos passos