Se você já leu sobre agentes de IA e ficou curioso sobre como o agente “sabe” quando consultar o banco de dados, chamar uma API ou pesquisar um documento, a explicação é mais direta do que parece. Entender esse mecanismo faz diferença real entre construir um sistema que funciona de verdade e um que funciona só na demo.
A palavra que a indústria usa é “tools” ou ferramentas. O conceito em si não é complicado. O que confunde as pessoas é imaginar que o modelo de linguagem executa alguma coisa por conta própria. Não executa. O que ele faz é decidir.
O que é uma ferramenta na prática
Uma ferramenta em um sistema de agente é, no fundo, uma função que você define no seu código e descreve para o modelo. Você diz: existe uma função chamada “buscar pedido”, que recebe um número de pedido e retorna os dados desse pedido no sistema. Isso é tudo.
O modelo lê essa descrição, entende o que a função faz e, quando o contexto exige, responde ao sistema dizendo que quer chamar aquela função com determinado argumento. Seu código recebe esse pedido, executa a função de verdade, pega o resultado e devolve para o modelo continuar o raciocínio.
O modelo de linguagem nunca toca no banco de dados diretamente. Nunca chama a API de faturamento. Nunca lê o arquivo. Ele apenas sinaliza o que quer executar e espera o resultado. Quem executa é o seu código.
Essa separação parece trivial até você ter que debugar um problema em produção. Aí faz muita diferença saber exatamente onde a responsabilidade está.
O loop que faz o agente funcionar
O ciclo básico de um agente com ferramentas é assim: o modelo recebe uma tarefa, raciocina sobre o que precisa, escolhe uma ferramenta para chamar, seu código executa, o resultado volta pro modelo, ele raciocina de novo, talvez chame outra ferramenta, e continua até concluir ou pedir confirmação.
Esse loop parece simples. E é.
O problema não está no loop em si. O que torna ou não torna o sistema confiável é a qualidade de cada peça: a descrição da ferramenta, os dados que ela retorna, o que acontece quando ela falha, e se o modelo entendeu claramente o que cada ferramenta faz no contexto do problema real.
A descrição é mais importante do que parece
Olha, já vi isso dar errado de formas que não eram óbvias no início. Você tem duas ferramentas: uma que busca dados de clientes por nome, outra que busca por CNPJ. O modelo mistura as duas. Chama a de nome passando o CNPJ. Falha. Tenta de novo com a outra. Funciona, mas você queimou duas chamadas de API e o raciocínio ficou confuso no meio.
O problema não estava nas ferramentas. Estava na descrição.
“Busca cliente” e “busca cliente por documento fiscal” são descrições com sobreposição suficiente para o modelo hesitar. Escrever a descrição de uma ferramenta bem é escrever de forma que um humano lendo entenda exatamente quando usar aquela e não a outra. Se você precisa de uma frase como “use essa ferramenta quando tiver o CNPJ ou CPF do cliente, não o nome”, você escreveu melhor do que a maioria dos sistemas que eu reviso.
Não é detalhe de implementação. É o coração do comportamento do agente em produção.
Tipos de ferramentas que aparecem em praticamente todo projeto
Consulta a banco de dados é a mais comum. O agente precisa buscar informações do sistema: status de pedidos, dados de clientes, histórico de transações, contratos. Você expõe funções de leitura específicas, com parâmetros claros e retorno limitado ao que o modelo precisa. Não uma query genérica. Uma função com propósito definido.
Chamadas a APIs externas vêm logo depois. Consultar CEP, integrar com ERP, buscar dados de uma API de notas fiscais. Aqui o cuidado é com o que você devolve pro modelo: uma API de logística pode retornar vinte campos e o agente precisar de três. Passar tudo é jogar token fora e contaminar o contexto com ruído que ele não pediu.
Busca semântica é a terceira categoria que aparece cedo. Quando o agente precisa encontrar informações em documentos, base de conhecimento ou histórico de atendimentos. Essa é a camada de RAG dentro do sistema de ferramentas, e funciona muito bem quando está bem integrada com o resto.
Ações com efeito colateral merecem atenção especial. Enviar e-mail, criar registro, atualizar status, disparar notificação. Uma ferramenta que envia e-mail chamada duas vezes num ciclo de retry não é tolerável. Aqui a cautela precisa estar explícita, tanto na descrição quanto na arquitetura.
E tem a ferramenta que as pessoas subestimam até sentirem falta: “finalizar tarefa”, “pedir confirmação ao usuário”, “escalar para humano”. Parecem supérfluas até você ter um agente que fica girando em loop porque não sabe quando parou de trabalhar.
O que quebra em produção que a demo não mostra
A ferramenta retornou erro. O que o agente faz?
Depende de como você tratou isso. Se a função lançou uma exceção sem mensagem útil, o modelo pode tentar de novo com os mesmos parâmetros, entrar em loop, ou simplesmente inventar uma resposta baseada no que ele acha que o resultado deveria ter sido. E o pior caso é quando ele inventa algo que parece plausível o suficiente para passar despercebido.
Já vi isso travar em produção quando uma API de terceiro voltou com timeout. O agente tentou várias vezes, cada iteração acumulando mais tokens no contexto, até estourar e retornar um resultado completamente fabricado. A resposta final era plausível. Só não era verdadeira. Levou algumas horas para alguém perceber.
A correção foi simples depois que o problema estava claro: a ferramenta precisa retornar um objeto de erro estruturado, não lançar exceção. Com erro estruturado, o modelo consegue ler “a API retornou timeout” e tomar uma decisão inteligente. Com exceção genérica, ele está voando às cegas e faz o que pode.
Aliás, isso vale para qualquer integração com API externa. A ferramenta que consome bem-sucedida é só metade do problema. A que comunica falha de forma legível para o modelo é a outra metade, e é onde a maioria dos projetos economiza tempo na hora errada.
Por que vale entender isso antes de comprometer orçamento
Não é porque você vai implementar. É porque a qualidade de um agente com ferramentas depende de decisões de design que acontecem cedo: quais ferramentas existem, como são descritas, o que retornam, o que acontece quando falham.
Você pode ter um modelo de linguagem excelente e um agente que não funciona porque as ferramentas foram definidas com pressa. Ou ter um modelo mais simples funcionando de forma muito confiável porque o design foi feito com cuidado. Eu prefiro o segundo. Sempre preferi.
A conversa com quem vai construir para você começa com “quais ferramentas o agente precisa e o que acontece quando cada uma falha”. Se essa conversa não acontecer antes do primeiro sprint, vai acontecer no pior momento possível, no meio de um incidente, com cliente aguardando explicação.
Gabriel Schunck está disponível para projetos de automação e sistemas com IA. Se você está avaliando arquitetura de agentes antes de comprometer equipe e orçamento, entra em contato pelo gabriels.dev.br.