MessagesFerramentas

Como funciona o uso de ferramentas

Copy page



Entenda o loop de uso de ferramentas, onde as ferramentas são executadas e quando usar ferramentas em vez de texto.

Esta página explica os conceitos por trás do uso de ferramentas: onde as ferramentas são executadas, como funciona o loop agêntico e quando o uso de ferramentas é a abordagem correta. 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 formato suas entradas e saídas assumem; 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 o modelo se comportar menos como um gerador de texto e mais como uma função que você chama. Engenheiros com experiência em APIs clássicas 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 principal eixo ao longo do 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 caso mais comum: 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 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 desktop ou um navegador), a Anthropic publica o schema da ferramenta e sua aplicação trata a execução. As ferramentas nesta categoria são memory, bash, text_editor, computer e browser.

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 no modelo. 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 trata 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 pelo cliente (tanto definidas pelo usuário quanto com schema da Anthropic) exigem que sua aplicação conduza um loop. O modelo não pode executar seu código, então toda chamada de ferramenta é uma ida e volta: o modelo pergunta, você executa, você reporta de volta, o modelo continua.

O formato canônico é 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 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, tratar 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 buscas na web ou execuções de código antes que uma resposta retorne. O modelo busca, lê resultados, determina se deve 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 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 executá-las.
• Dados novos 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 texto que por acaso contém a informação, um schema de ferramenta impõe o formato.
• 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 em formato 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. Resumo, 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 de chamada de ferramenta dominaria uma resposta trivial. Toda 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