Como criar um agente de IA

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
  • Loops descontrolados, contas inesperadas, ações destrutivas
  • Avaliação
  • 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.

Decidir

Agir

Observar

Guardrail

Concluído

Simulador do loop de agente

Próximo passo

Reiniciar

Exigir aprovação antes de send_email

Passo {n} de {v}

Execução concluída.

ainda não alcançado

Comece grátis · Sem cartão de crédito

Relacionados: Guias

Produto

Para quem é

Recursos

Recursos

Empresa

Mapa do site