Um agente de IA no n8n é a combinação de três peças: um modelo de linguagem para pensar, ferramentas para agir e memória para lembrar da conversa. Neste passo a passo, o foco é montar essa combinação com o AI Agent node e memória persistente no Postgres, de modo que o histórico do chat sobreviva entre execuções e sessões.
O roteiro vai dos requisitos até a configuração do session key, do table name e do context window, passando pelos erros mais comuns e terminando nas próximas paradas de evolução, como multiagente e RAG usando o mesmo banco.
O que você precisa antes de começar
- n8n 2.42.5: é a versão estável mais recente, lançada em 2026-10-08, conforme a página de releases do n8n no GitHub. Se a sua instalação for antiga, vale atualizar antes de seguir.
- Um Postgres acessível: local ou em nuvem, desde que o n8n consiga se conectar. O mesmo banco pode servir a memória e, no futuro, vetores com o PGVector.
- Um modelo de IA: uma instância Ollama rodando na sua máquina ou uma API de modelo em nuvem, com credencial válida.
- Familiaridade básica com o n8n: saber criar workflows, adicionar nodes e configurar credenciais é suficiente para acompanhar.
Um detalhe de versão que evita confusão: a configuração de tipo de agente do AI Agent node foi depreciada a partir do n8n 1.82.0. Em versões atuais, todos os AI Agent nodes funcionam como Tools Agent, e workflows antigos configurados como Tools Agent continuam funcionando normalmente.
AI Agent node: o cérebro do agente de IA no n8n
O AI Agent node é o ponto de partida: ele permite construir um agente conectando um chat model e uma ou mais ferramentas, e é o próprio agente quem decide quais ferramentas chamar para completar a tarefa. A documentação do AI Agent node detalha cada parâmetro disponível.
Três pontos práticos valem destaque antes de montar o workflow:
- Streaming por padrão: no Tools Agent, o streaming de resposta em tempo real vem ativado por padrão e requer um trigger que o suporte, como o Chat Trigger ou o Webhook em modo Streaming.
- Memória só no agente: memory sub-nodes só podem ser anexados ao root node AI Agent. Nenhum node de chain suporta memória, então chains não conseguem referenciar mensagens anteriores — para isso é preciso usar agente.
- Custo de manutenção baixo: por não existir mais um seletor de tipo de agente, não há configuração extra a fazer no node raiz.
Conectando o modelo de IA: Ollama local ou API em nuvem
O chat model é um sub-node ligado ao agente. Sem ele, o workflow nem executa: aparece o erro "A Chat Model sub-node must be connected", e a solução é sempre conectar o sub-node de chat model.
Para rodar tudo local, o Ollama Chat Model node conecta a instâncias Ollama via base URL nas credenciais, usando a porta padrão 11434. Um detalhe que economiza tempo: a documentação recomenda usar 127.0.0.1 em vez de localhost na base URL para evitar erro de conexão relacionado a IPv6/IPv4. A página de problemas comuns do Ollama Chat Model reúne esses casos.
Com um modelo em nuvem, o processo muda pouco: escolha o node do provedor, crie a credencial com a chave de API e conecte ao agente. Para parâmetros específicos de cada provedor, consulte a documentação oficial do node correspondente.
Ferramentas: dando poderes de ação ao seu agente
Sem ferramentas, o agente é apenas um chat competente. Com ferramentas, ele consulta dados, chama serviços e executa ações conforme a tarefa pede — e é o agente quem decide quando acionar cada uma.
Para o primeiro agente, comece com uma ou duas ferramentas simples e valide o comportamento antes de ampliar. Cada ferramenta nova amplia o espaço de decisão do agente e, junto com ele, o esforço de teste.
Memória persistente: por que Postgres Chat Memory em vez de Simple Memory
A Simple Memory armazena o histórico apenas da sessão atual: quando a sessão acaba, o contexto vai embora. O n8n também oferece nodes de memória para os serviços Motorhead, Redis Chat Memory, Postgres Chat Memory, Xata e Zep, que mantêm o histórico fora da sessão.
O Postgres Chat Memory, na versão 1.4, a mais recente do node, usa o Postgres como servidor de memória para armazenar o histórico do chat. Isso significa que o agente retoma a conversa em execuções futuras, desde que o session key seja o mesmo.
Há ainda um bônus de logística: as credenciais Postgres no n8n são usadas pelos nodes Postgres, Agent, Postgres Chat Memory e PGVector Vector Store. A mesma credencial criada para a memória serve depois para consultas SQL e para RAG. A documentação das credenciais Postgres lista todos os campos de configuração.
| Aspecto | Simple Memory | Postgres Chat Memory |
|---|---|---|
| Onde o histórico fica | Sessão atual | Tabela em um banco Postgres |
| Contexto preservado entre execuções | Não | Sim, com o mesmo session key |
| Credencial compartilhada | Não usa Postgres | Mesma credencial dos nodes Postgres, Agent e PGVector Vector Store |
Passo a passo: configurando o Postgres Chat Memory
1. Crie a credencial Postgres
Crie uma credencial Postgres apontando para o seu banco, com host, porta, usuário e senha. Guarde essa credencial: ela será reaproveitada por outros nodes que conversam com o mesmo banco.
2. Anexe a memória ao agente
Adicione o Postgres Chat Memory como sub-node do AI Agent. Lembre da regra: memory sub-nodes só podem ser anexados ao root node AI Agent, então não tente ligar memória em chains.
3. Configure o Session Key
O Session Key identifica a conversa. Use um valor fixo para testar e, quando houver mais de uma pessoa ou contexto conversando com o agente, use chaves únicas por usuário ou conversa.
Atenção a um comportamento importante: se mais de um Postgres Chat Memory for adicionado ao workflow, todos acessam a mesma instância de memória por padrão. Para ter instâncias separadas, defina session IDs diferentes.
4. Defina o Table Name
O Table Name é a tabela onde o histórico será gravado. A tabela é criada automaticamente se não existir, então não é preciso rodar script algum no banco antes.
5. Ajuste o Context Window Length
O Context Window Length define o número de interações anteriores consideradas como contexto. Um valor maior dá mais histórico ao modelo e consome mais tokens; um valor menor mantém a conversa enxuta.
Um exemplo ilustrativo de configuração:
Session Key: cliente-joao
Table Name: historico_agente
Context Window Length: 10Os valores acima são só exemplo: ajuste o session key à sua lógica de usuários e o context window ao tamanho de contexto do modelo escolhido.
Testando o agente, erros comuns e como evoluir
Para testar, use o Chat Trigger e converse com o mesmo session key em dois momentos diferentes: pergunte algo, feche a sessão, abra de novo e verifique se o agente lembra. Se a resposta aparecer em partes, é o streaming funcionando — ele vem ativado por padrão no Tools Agent e depende de um trigger que o suporte, como o Chat Trigger ou o Webhook em modo Streaming.
Erros comuns
- "A Chat Model sub-node must be connected": ocorre ao executar o AI Agent sem um Chat Model conectado. A solução é conectar o sub-node de chat model ao agente.
- Falha de conexão com Ollama: confira a base URL nas credenciais, a porta padrão 11434 e use 127.0.0.1 em vez de localhost para evitar o problema de IPv6/IPv4.
- Conversas misturadas: histórico de contextos diferentes aparecendo junto geralmente é session key repetido ou múltiplos nodes de memória compartilhando a mesma instância por padrão.
Próximos passos
Quando o primeiro agente estiver estável, dois caminhos naturais usam o mesmo Postgres. O AI Agent Tool node permite que um agente raiz chame outros agentes como ferramentas, simplificando a orquestração multiagente em um único workflow; a documentação do node está publicada em docs.n8n.io. Já o PGVector Vector Store, uma extensão do Postgres, pode ser conectado diretamente ao agente como ferramenta, abrindo caminho para RAG no mesmo banco da memória.
Conclusão
O AI Agent node com Postgres Chat Memory forma uma base sólida para quem está começando com agentes: modelo local ou em nuvem, ferramentas acionadas sob demanda e histórico persistente em um banco que você já conhece. Comece pequeno, valide a memória com sessões distintas e evolua para multiagente e RAG quando o básico estiver redondo.
Perguntas frequentes
Preciso criar a tabela de memória no Postgres manualmente?
Não. O Postgres Chat Memory cria a tabela automaticamente se ela não existir. Basta definir o nome no parâmetro Table Name.
Qual a diferença entre Simple Memory e Postgres Chat Memory?
A Simple Memory armazena o histórico apenas da sessão atual. O Postgres Chat Memory grava o histórico em uma tabela Postgres, preservando o contexto entre execuções com o mesmo session key.
Dá para usar memória em chains?
Não. Memory sub-nodes só podem ser anexados ao root node AI Agent, e nenhum node de chain suporta memória. Para referenciar mensagens anteriores, é preciso usar agente.
