Como criar um agente de IA: loop, ferramentas, memória e guardrails | We.Inc
Crie um agente de IA do zero: o loop decidir, agir, observar, a definição de ferramentas, memória, limites de passos, aprovação humana e testes. Inclui um simulador de passos.
Como criar um agente de IA
Um agente de IA é um loop. Um modelo de linguagem lê o objetivo e tudo o que aconteceu até agora e então chama uma das ferramentas que você definiu ou dá uma resposta final. O seu código executa a ferramenta, anexa o resultado e pergunta de novo. Limites de passos, permissões, aprovação humana e testes mantêm esse loop seguro.
As cinco partes de um agente
Parte
O que você constrói
O que dá errado sem ela
Loop
Código que chama o modelo, executa ferramentas e repete
Nada acontece depois da primeira resposta
Ferramentas
Funções com nome, descrição e um schema de entrada
O modelo só consegue falar, não agir
Memória
A transcrição em andamento, mais as notas salvas entre execuções
O modelo repete chamadas que já fez
Guardrails
Limites de passos e de custo, privilégio mínimo, aprovação para ações arriscadas
Tarefas de teste fixas com verificações que você roda de novo a cada mudança
Você descobre regressões pelos usuários
Rode o simulador para ver uma tarefa passar pelo loop. Desligue e ligue a aprovação para ver onde um guardrail interrompe um passo arriscado. O trace é roteirizado para você poder estudá-lo; uma execução real consultaria um modelo a cada passo de decisão.
Clique em Próximo passo para avançar o loop um movimento por vez.
Leia cada linha: decidir é o modelo escolhendo, agir é o seu código executando uma ferramenta, observar é o resultado sendo adicionado à memória.
Alterne a aprovação para send_email e rode de novo para comparar os dois traces.
Clique em Reiniciar para começar de novo.
Comece com uma ferramenta e uma tarefa. Adicione ferramentas só quando uma tarefa de teste falhar por falta de uma, porque cada ferramenta extra é mais uma escolha que o modelo pode errar.
Deixe os resultados das ferramentas curtos e objetivos. A transcrição inteira volta para o modelo a cada passo, então resultados longos custam dinheiro e escondem o que importa.
Coloque as verificações de permissão no código da ferramenta, não nas instruções. Um modelo pode ser convencido a ignorar uma instrução; ele não consegue contornar uma verificação que a sua função impõe.
Registre cada passo com entrada, saída e custo. Quando uma execução dá errado, o log é a única forma de ver qual decisão foi ruim.
Perguntas frequentes
Preciso de um framework para criar um agente?
Não. O núcleo é um loop while em volta de uma chamada ao modelo e um switch sobre os nomes das ferramentas, como mostra o exemplo desta página. Frameworks adicionam novas tentativas, tracing e integrações, que ajudam depois mas escondem o loop enquanto você aprende.
Como o modelo chama uma ferramenta?
Você envia as definições das ferramentas em cada requisição. Quando o modelo quer usar uma, ele responde com o nome da ferramenta e os argumentos em vez de texto comum. O seu código executa a função e devolve o resultado como a próxima mensagem.
Qual é a diferença entre memória e contexto?
Contexto é o que o modelo vê nesta chamada: instruções, o objetivo e a transcrição até aqui. Memória é tudo o que você armazena e decide colocar de volta no contexto depois, como notas de uma execução anterior.
Como impedir que um agente rode para sempre?
Limite o número de passos e o gasto total, e encerre a execução com uma mensagem clara quando qualquer um deles for atingido. A OWASP inclui o Unbounded Consumption entre os riscos de 2025 para aplicações baseadas em modelos de linguagem.
Como testar um agente?
Escreva um conjunto de tarefas fixas com resultados verificáveis: a ferramenta certa foi chamada, uma ação arriscada esperou aprovação, a resposta final contém um valor. Rode o conjunto depois de cada mudança no prompt ou nas ferramentas e compare quantas passaram.
Guardrails que realmente funcionam
A lista de 2025 da OWASP aponta o Excessive Agency como um risco central e o atribui a três causas: funcionalidade excessiva, permissões excessivas e autonomia excessiva. Cada uma corresponde a uma correção que você controla no código.
Dê ao agente só as ferramentas de que a tarefa precisa, dê a cada ferramenta as credenciais mais restritas que funcionem e exija que uma pessoa aprove ações de alto impacto, como enviar, pagar ou excluir. Verifique a autorização no sistema que a ferramenta chama, em vez de confiar que o modelo vai se comportar.
Texto não confiável é a principal superfície de ataque
Qualquer coisa que uma ferramenta busca, como uma página web, um e-mail ou um arquivo, pode conter instruções direcionadas ao seu modelo. A OWASP chama isso de prompt injection indireta.
Marque claramente o conteúdo buscado como dados, mantenha-o separado das suas próprias instruções e nunca deixe que o texto de um resultado de ferramenta libere sozinho uma ferramenta mais poderosa. A aprovação humana para passos privilegiados é a última barreira quando as outras defesas falham.
O loop em JavaScript puro
Sem framework e sem SDK de fornecedor. callModel é um stub que reproduz decisões fixas para que o arquivo rode como está; substitua-o por uma requisição ao serviço de modelo que você usa.
As ferramentas ficam em um único objeto, as arriscadas precisam de aprovação e o loop para em um limite de passos. Rode com node agent.mjs.
Riscos para levar em conta no design
Itens do OWASP Top 10 for LLM Applications 2025 que mais importam para agentes
Risco
Como aparece em um agente
Correção no código
LLM01:2025 Prompt Injection
Uma página buscada manda o modelo enviar seus dados por e-mail para outro lugar
Separe o conteúdo não confiável, aprove ações privilegiadas
LLM06:2025 Excessive Agency
O agente pode excluir registros que só precisava ler
Menos ferramentas, credenciais restritas, aprovação para alto impacto
LLM10:2025 Unbounded Consumption
Um loop tenta de novo uma ferramenta com falha a noite toda
Limite de passos, limite de gasto, timeouts, rate limits
LLM05:2025 Improper Output Handling
A saída do modelo é colada em SQL ou HTML sem verificação
Valide e faça escape antes de qualquer uso posterior
Objetivo: encontrar o mais barato de três orçamentos de fornecedores e enviar o resumo por e-mail ao gerente do escritório.
O modelo escolhe read_quotes para ver o que chegou.
O código executa read_quotes() e retorna três arquivos.
Resultado adicionado à memória: A $1,240, B $1,180, C $1,315.
O modelo tem o que precisa e escolhe send_email com um rascunho de resumo.
send_email está marcado como alto impacto, então a execução pausa para uma pessoa aprovar o rascunho.
Aprovado. O código executa send_email() com o texto aprovado.
Resultado adicionado à memória: mensagem enviada.
O modelo retorna uma resposta final: o orçamento B é o mais barato, com $1,180; resumo enviado. 3 chamadas ao modelo, abaixo do limite de 10 passos.
O modelo escolhe read_quotes para ver o que chegou.
O código executa read_quotes() e retorna três arquivos.
Resultado adicionado à memória: A $1,240, B $1,180, C $1,315.
O modelo tem o que precisa e escolhe send_email com um rascunho de resumo.
Não há regra de aprovação, então o código envia o rascunho na hora. Ninguém viu antes.
Resultado adicionado à memória: mensagem enviada.
O modelo retorna uma resposta final. Desta vez deu certo, mas um valor errado ou uma instrução injetada também teria saído sem verificação.