--- title: Como funciona o uso de ferramentas url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/how-tool-use-works description: 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/build-a-tool-using-agent) ou o guia [Defina ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools). ## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools) 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/memory-tool), [`bash`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool), [`text_editor`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/text-editor-tool), [`computer`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) e [`browser`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool). 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool), [`web_fetch`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool), [`code_execution`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) e [`tool_search`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools), 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/how-tool-use-works#the-server-side-loop)) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls). ## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) 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](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use) 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 | Abordagem | Quando usá-la | O que esperar | Saiba mais | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Ferramentas de cliente definidas pelo usuário | Lógica de negócios personalizada, APIs internas, dados proprietários | Você trata a execução e o loop agêntico | [Defina ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools) | | Ferramentas de cliente com schema da Anthropic | Operações de desenvolvimento padrão (bash, edição de arquivos, controle de desktop e navegador) | Você trata a execução; Claude chama a ferramenta de forma confiável porque o schema é treinado no modelo | [Referência de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference) | | Ferramentas executadas pelo servidor | Busca na web, sandbox de código, busca de conteúdo web | A Anthropic trata a execução; você lê os resultados em vez de produzi-los | [Ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) | ## Próximos passos Construa um agente passo a passo, de uma única chamada de ferramenta até a produção. Especificação de schema, descrições e `tool_choice`. Diretório de ferramentas fornecidas pela Anthropic.