Seu primeiro agente de IA em produção com n8n

O formato de um agente de verdade

A maioria dos tutoriais mostra um agente como um nó só: o gatilho entra, um nó mágico de IA faz tudo, o resultado sai. Sistema em produção não se parece com isso. Ele tem cinco peças distintas:

1. Gatilho — um webhook, envio de formulário, agendamento ou e-mail recebido.
2. Recuperação (opcional) — buscar o contexto de que o modelo precisa: um registro do CRM, o histórico de um chamado, uma linha de planilha.
3. Raciocínio — a chamada ao modelo que decide o que fazer, dado o gatilho e o contexto recuperado.
4. Chamada de ferramenta — a ação decidida: enviar uma mensagem, atualizar um campo do CRM, criar um evento na agenda.
5. Ponto de controle humano — uma pausa antes de qualquer coisa que não se desfaz (enviar e-mail a cliente, cobrar um cartão, apagar um registro).

Pule a quinta e você não tem um agente: tem um script sem supervisão com um modelo dentro.

Um exemplo concreto

Pense em um agente de qualificação de leads. Um formulário é enviado — esse é o gatilho. O fluxo consulta o domínio da empresa em uma base externa — recuperação. Um nó de LLM lê as respostas do formulário junto com esses dados e decide se o lead é qualificado e em que faixa — raciocínio. Então o fluxo cria o registro no CRM e avisa o vendedor — chamada de ferramenta. Ou, se a decisão do modelo for frágil, encaminha para revisão manual em vez de qualificar sozinho — o ponto de controle.

É o mesmo formato de cinco peças de qualquer automação séria, apenas descrito em termos de agente.

Onde os times erram

Nenhuma etapa de recuperação. Alimentar o modelo apenas com o conteúdo do gatilho e pedir que ele "decida" produz saída plausível e sem fundamento. O modelo não conhece as regras de pontuação de lead da sua empresa a menos que você as coloque na frente dele.

Nenhum critério de incerteza. Tratar toda saída como final significa que toda alucinação chega ao cliente ou ao sistema de registro. Acrescente um caminho explícito para o caso duvidoso — mesmo um simples, como uma checagem por palavra-chave ou uma segunda chamada mais barata — antes que a decisão vire ação irreversível.

Um prompt gigante em vez de um fluxo. Se o seu agente é um único prompt tentando recuperar, decidir e agir de uma vez, você escondeu as cinco peças dentro de um texto em vez de deixá-las inspecionáveis como nós separados. Isso é mais difícil de depurar quando quebra — e vai quebrar.

A leitura da Tyna

A quinta peça é a que separa piloto de sistema, e vale explicitar o critério que a torna acionável: irreversível é tudo que sai do seu controle quando executa.

E-mail enviado, cobrança feita, registro apagado, mensagem que o cliente vê. Criar rascunho interno, marcar um lead, escrever em uma tabela de trabalho — isso se desfaz, e automatizar sem pausa é razoável. A pergunta a fazer para cada ação do fluxo não é "o modelo acerta isso?", é "se ele errar, dá para desfazer?". Onde a resposta for não, entra a pausa.

O terceiro erro listado é o mais comum em time que está começando, e o mais caro. Um prompt gigante parece mais simples porque tem menos peças na tela. Só que quando ele falha — e ele falha —, não há onde olhar: a recuperação, a decisão e a ação aconteceram dentro da mesma caixa preta. Separar em nós parece burocracia até o primeiro incidente, quando vira a diferença entre "sei exatamente em qual etapa quebrou" e "vou reler o prompt e tentar adivinhar".

Uma observação sobre a segunda peça, à luz do que já publicamos sobre scores de confiança não serem confiáveis: o critério de incerteza mencionado aqui não precisa vir do modelo. Verificação por regra, validação de esquema ou conferência contra uma fonte de verdade costumam ser mais baratas e muito mais previsíveis do que perguntar ao modelo o quanto ele confia em si mesmo.

Perguntas frequentes

P: Preciso de banco vetorial ou recuperar de uma planilha basta?

R: Depende do que você recupera. Consulta estruturada — um registro de CRM, uma linha de planilha — não precisa de banco vetorial: uma chamada de API é mais rápida e mais fácil de depurar. Reserve busca vetorial para conteúdo realmente não estruturado, como histórico de chamado ou documentação.

P: O que conta como irreversível no ponto de controle?

R: Tudo que deixa o seu sistema ao executar: e-mail enviado, pagamento, exclusão de registro e qualquer ação que o cliente veja diretamente. Rascunho interno ou marcação em CRM costumam ser seguros de automatizar.

P: Esse formato de cinco peças funciona fora do n8n?

R: Sim. É o mesmo formato que um framework de agentes em código produziria, apenas expresso como código em vez de fluxo visual.