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 certa. Para orientação prática, comece com o tutorial Construa um agente que usa ferramentas ou o guia Defina ferramentas.



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 determina 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 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 API 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 escolhendo qual função chamar 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. 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 pelo cliente)

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

Quando Claude chama 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 vê apenas o schema que você forneceu e o resultado que você retornou.



Ferramentas com schema da Anthropic (executadas pelo 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 seu próprio equivalente é que esses schemas fazem parte do 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 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. 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 no momento em que 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 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, 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 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 outra razão de parada ("end_turn", "max_tokens", "stop_sequence" ou "refusal"), o que significa que Claude produziu uma resposta final ou parou por outra razão que sua aplicação deve tratar.

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



O loop do lado do servidor

Ferramentas executadas pelo servidor executam seu próprio loop dentro da infraestrutura da Anthropic. Uma única solicitação da sua aplicação pode disparar várias pesquisas na web ou execuções de código antes que uma resposta retorne. O modelo pesquisa, lê os resultados, determina se deve pesquisar 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 Razões 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 realizá-las.
• Dados recentes 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 forma garantida. 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 a forma.
• Chamar 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.

Um sinal claro 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 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 o 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 "latency" (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