Agente de IA n8n: o primeiro fluxo, passo a passo

Um agente de IA n8n, ou seja, montado dentro do n8n, nasce de um fluxo com três peças: um gatilho de chat, o nó AI Agent ligado a um modelo de linguagem e pelo menos uma ferramenta. Depois você escreve a mensagem de sistema dizendo o que o agente faz e testa no chat do próprio n8n.

Este guia é para quem já sabe o que é o n8n e já entendeu o que é um agente. Se ainda não, leia antes o que é o n8n e para que serve e o que é um agente de IA, com exemplos. Aqui a gente vai direto para a tela.

O que é um agente de IA no n8n

Um agente de IA no n8n nada mais é do que um nó (o AI Agent) que recebe um pedido, decide sozinho qual ferramenta usar e devolve a resposta. A documentação do n8n descreve assim: você conecta um modelo de chat e uma ou mais ferramentas, e o agente decide quais ferramentas chamar para completar a tarefa.

Pense num funcionário novo no balcão. O modelo de linguagem é a cabeça dele. As ferramentas são o que ele tem à mão: a planilha de produtos, a agenda, o e-mail. A mensagem de sistema é o treinamento do primeiro dia. Sem ferramenta, ele só conversa. Com ferramenta, ele consulta e age.

Uma diferença que confunde no começo: o n8n também tem as "chains" (cadeias), como o Basic LLM Chain. A cadeia segue sempre o mesmo caminho. O agente escolhe o caminho. E, segundo a documentação, só os nós de agente usam memória; as cadeias não.

As quatro peças do fluxo

Peça	Nó no n8n	O que faz
Gatilho	Chat Trigger	Recebe a mensagem e dispara o fluxo
Cérebro	AI Agent + um Chat Model (OpenAI, Anthropic, Google Gemini e outros)	Entende o pedido e decide o que fazer
Memória	Simple Memory	Guarda as últimas mensagens da conversa
Ferramenta	Google Sheets, Gmail, Google Calendar, HTTP Request etc.	Onde o agente consulta ou age

No n8n, modelo, memória e ferramentas aparecem como "sub-nós" pendurados embaixo do AI Agent. A documentação é clara num ponto: você precisa conectar pelo menos uma ferramenta ao nó AI Agent.

Passo a passo do primeiro agente

O exemplo deste guia é pequeno de propósito: um agente que responde dúvidas sobre produtos consultando uma planilha do Google. Imagine uma loja que recebe toda hora a mesma pergunta ("tem no tamanho M?", "qual o prazo?"). É o caso perfeito para começar, porque a resposta já existe em algum lugar e só precisa ser buscada.

Passo 1: organize a planilha antes de abrir o n8n

Qual é o primeiro passo? Não é o n8n. É a fonte de verdade. Monte uma planilha com colunas simples: produto, tamanhos, cores, prazo de entrega, observação. Uma linha por produto, sem célula mesclada, sem anotação solta. Se a planilha está bagunçada, o agente vai responder bagunçado, só que mais rápido.

Passo 2: crie o fluxo com o Chat Trigger

Crie um workflow novo e adicione o nó Chat Trigger. Ele recebe a mensagem e precisa estar ligado a um agente ou a uma cadeia. Deixe a opção Make Chat Publicly Available desligada enquanto você monta: assim o chat só funciona dentro do editor, para testes. A documentação recomenda ligar só quando o fluxo estiver pronto.

Passo 3: adicione o nó AI Agent e conecte o modelo

Depois do gatilho, adicione o AI Agent. Embaixo dele aparecem as entradas para o modelo, a memória e as ferramentas. Em "Chat Model", escolha o provedor que você já usa (OpenAI, Anthropic ou Google Gemini, por exemplo) e cadastre a credencial com a chave de API dele. O uso da API é cobrado à parte pelo provedor, por uso; confira na página oficial de cada um.

Uma observação de versão: desde a versão 1.82.0 o n8n tirou a opção de "tipo de agente" e todo AI Agent funciona como Tools Agent. Se você pegar um modelo antigo da internet com o nó na versão 1, atualize o nó. A documentação avisa que essa versão sai no n8n 3.0. Falei disso no post sobre o que muda no n8n 3.0 e o que fazer antes de atualizar.

Passo 4: escreva a mensagem de sistema

Nas opções do AI Agent existe o campo System Message. A documentação diz que ele serve para orientar a tomada de decisão do agente. Na prática, é aqui que o agente fica bom ou ruim. Use o mesmo raciocínio do método C.L.A.R.O. (Contexto, Linguagem, Ação, Referência, Objetivo). Um modelo para adaptar:

Contexto: você atende clientes da loja [NOME], que vende [TIPO DE PRODUTO].
Linguagem: responda curto, educado, no tom de uma conversa de WhatsApp.
Ação: quando perguntarem sobre produto, tamanho, cor ou prazo,
consulte a ferramenta "planilha_produtos" antes de responder.
Referência: use só o que está na planilha. Se a informação
não estiver lá, diga que vai confirmar com a equipe.
Objetivo: tirar a dúvida do cliente sem inventar nada.
Não fale de preço, desconto nem troca: encaminhe para a equipe.

Repare na última linha. Escrever o que o agente não pode fazer é tão importante quanto escrever o que ele faz.

Passo 5: adicione a memória

Conecte o sub-nó Simple Memory. Ele guarda as últimas trocas da conversa, e você define quantas no campo Context Window Length. Sem memória, cada mensagem chega como se fosse a primeira: o cliente diz "e na cor azul?" e o agente não sabe do que ele está falando.

Duas ressalvas da documentação. Primeira: a memória não persiste entre sessões. Segunda: se o seu n8n roda em "queue mode" (modo de fila, comum em instalação própria com vários workers), a Simple Memory não funciona em fluxo ativo de produção. Nesse caso, use uma memória com banco, como a Postgres Chat Memory ou a Redis Chat Memory.

Passo 6: conecte a ferramenta

Em "Tool", adicione o Google Sheets, cadastre a credencial do Google e aponte para a planilha do passo 1, com a operação de leitura das linhas. Dê um nome claro à ferramenta e escreva uma descrição curta do que ela tem ("lista de produtos com tamanhos, cores e prazo"). É por essa descrição que o agente decide quando usar a ferramenta.

Passo 7: teste no chat do editor

Abra o chat do próprio editor e faça perguntas reais, inclusive as chatas: produto que não existe, pergunta de preço, pergunta fora do assunto. Clique na execução e veja o que o agente fez em cada passo. Se ele não consultou a planilha quando deveria, o problema quase sempre está na mensagem de sistema ou na descrição da ferramenta, não no modelo.

Só depois de passar nos testes ligue o chat público. Ao ligar, o Chat Trigger oferece autenticação: nenhuma, usuário e senha (Basic Auth) ou login do n8n. Para um teste com a equipe, comece com senha.

O que costuma dar errado no primeiro agente

• O agente inventa resposta. A IA calcula a resposta mais provável, não a verdadeira. Reforce na mensagem de sistema que ele só responde com o que a ferramenta devolveu.
• A planilha não é a fonte de verdade. Se a equipe atualiza o estoque em outro lugar, o agente fica desatualizado. Resolva o processo antes do fluxo.
• Cada mensagem é uma execução. A documentação do Chat Trigger avisa: uma conversa com dez mensagens conta dez execuções do seu plano. Confira o que o seu plano permite antes de abrir o chat para clientes.
• Ferramenta que age sem conferência. Para ferramenta que envia mensagem, altera registro ou apaga dado, o n8n tem revisão humana: o fluxo pausa e espera alguém aprovar ou negar a ação. Comece com a revisão ligada e vá soltando conforme ganhar confiança.

Se você quer ver isso feito na tela, do gatilho ao fluxo rodando, a aula aberta n8n do zero: o que é e automações reais com IA mostra a lógica do gatilho na prática. E a trilha Automação da Academ.IA segue daí para agentes, WhatsApp e API.

Vale começar por um template do n8n?

O n8n tem uma biblioteca pública de modelos de fluxo, e a página do AI Agent na documentação aponta para os modelos com esse nó. Vale para ver como outras pessoas ligaram as peças. Não vale para copiar e colocar no ar. O template não conhece o seu processo, a sua planilha nem o que o seu agente não pode falar. Use como referência de montagem e reescreva a mensagem de sistema do zero.

Quando o primeiro agente estiver funcionando, o próximo passo natural é tirar ele do chat do n8n e levar para onde o cliente já está. Expliquei esse caminho em como criar um agente de IA para WhatsApp. E se a dúvida ainda é anterior, de como desenhar o agente antes de qualquer ferramenta, veja como criar um agente de IA, do processo ao agente pronto.

Perguntas frequentes

Preciso saber programar para criar um agente de IA no n8n?

Não. O fluxo é montado arrastando nós e preenchendo campos, e a mensagem de sistema é texto comum. Você precisa entender o processo que o agente vai atender e saber cadastrar credenciais, como a chave de API do modelo e o acesso ao Google.

Qual modelo de IA usar no nó AI Agent?

O n8n aceita vários provedores, entre eles OpenAI, Anthropic e Google Gemini. Não existe o melhor. Teste dois com as mesmas perguntas e fique com o que respondeu certo o seu caso, olhando também o custo de uso na página oficial de cada provedor.

Qual a diferença entre o AI Agent e o Basic LLM Chain?

A cadeia faz sempre o mesmo caminho: recebe, manda para o modelo, devolve. O agente decide se e qual ferramenta usar a cada pedido, e pode ter memória. Se a tarefa é sempre igual, como resumir um texto, a cadeia basta.

O agente lembra da conversa de ontem?

Com a Simple Memory, não: ela guarda só as últimas trocas da sessão atual. Para guardar histórico de verdade, você precisa de uma memória ligada a banco de dados, como Postgres ou Redis.

Posso colocar esse agente no WhatsApp?

Pode, trocando o gatilho de chat por um que receba as mensagens do WhatsApp. É um passo a mais de configuração, e vale fazer só depois que o agente estiver respondendo bem no chat de teste.

Próximo passo

O agente é a ponta do iceberg. O que faz ele funcionar é o que vem antes: a planilha organizada, a regra do que ele pode e não pode falar, a conferência das ações. Primeiro o processo, depois a ferramenta. Se você quer montar isso com acompanhamento, a trilha Automação da Academ.IA resolve esse caminho, do primeiro gatilho ao agente conectado nos seus sistemas.