AI Agent no n8n: como criar um agente de IA no fluxo

Entenda o nó AI Agent do n8n: o que é o Tools Agent, as peças Chat Model, Memory e Tools, um passo a passo com Chat Trigger, as opções do nó e os erros comuns.

Por Redação Eleven Host · @robson.direitodigital · 30 de outubro de 2026 · 9 min de leitura

O AI Agent no n8n é um nó que monta um agente de IA no fluxo: você liga um modelo de chat e ferramentas, e o agente decide qual ferramenta chamar. Este guia mostra as peças, um passo a passo e as opções do nó.

O que é o AI Agent (Tools Agent)

Segundo a documentação do n8n, o nó AI Agent permite montar um agente de IA no n8n. Você conecta um modelo de chat e uma ou mais ferramentas, e o agente decide quais ferramentas chamar. A documentação exige pelo menos uma ferramenta conectada ao nó.

Sobre o tipo de agente: a opção de escolher o tipo ficou obsoleta a partir do n8n 1.82.0, e os nós AI Agent funcionam como Tools Agent. Esse agente usa ferramentas externas e APIs para executar ações e buscar informações, pela interface de tool calling do LangChain. A documentação também diz que o nó v1, com a opção de tipo, será removido no n8n 3.0.

AI Agent ou n8n com ChatGPT

O guia n8n com ChatGPT: como usar a API da OpenAI nos fluxos trata de usar a API da OpenAI como um passo do fluxo. Aqui o assunto é outro: o nó AI Agent, em que o modelo vem acompanhado de ferramentas e é o agente que escolhe qual delas usar. Os dois guias se complementam, e vale ler o primeiro se você quer entender a chamada ao modelo sozinha.

As peças do agente: Chat Model, Memory e Tools

O AI Agent funciona com sub-nós ligados a ele. Os nomes abaixo seguem a documentação em inglês, que é como aparecem na tela:

• Chat Model: o modelo de linguagem. Na prática é obrigatório. Sem ele, o nó mostra o erro A Chat Model sub-node must be connected. A página do Tools Agent lista como compatíveis, entre outros, os modelos de OpenAI, Groq, Mistral Cloud, Anthropic e Microsoft Foundry. O Chat Model precisa da credencial do provedor que você escolher.
• Memory: guarda o histórico da conversa. É opcional. Um nó para isso é o Simple Memory, visto mais abaixo.
• Tools: as ferramentas que o agente pode chamar. A documentação pede pelo menos uma.

A documentação resume as ferramentas assim: elas funcionam como complementos que a IA pode usar para acessar contexto ou recursos extras. Em outro ponto, ela diz que as ferramentas podem usar $fromAI() para a IA preencher os parâmetros, e que dá para exigir aprovação humana antes de certas ferramentas rodarem (Chat, Slack e Telegram).

Quer conhecer o n8n da Eleven Host? n8n Essencial a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Ver planos de n8n

Passo a passo de um agente simples com Chat Trigger

O exemplo abaixo junta as opções descritas na documentação. Ele monta um chat em que cada mensagem chega a um agente com memória e uma ferramenta:

1. Crie um fluxo e adicione o nó Chat Trigger. Ele é indicado para fluxos de IA com chatbots e outras interfaces de chat. Cada mensagem enviada roda o fluxo e conta como uma execução.
2. No Chat Trigger, deixe Make Chat Publicly Available desligado enquanto você monta. Em Mode, o Hosted Chat usa a interface do n8n, e a documentação o recomenda.
3. Adicione o nó AI Agent e ligue o Chat Trigger a ele. A documentação diz que é preciso conectar ao gatilho um nó raiz de agente ou chain.
4. No AI Agent, em Prompt, deixe Take from previous node automatically. O agente lê o campo chatInput do nó anterior.
5. Conecte o Chat Model ao agente, pelo botão + Chat Model que aparece na parte de baixo da tela quando o nó está aberto, e escolha o provedor. O Chat Model precisa da credencial do provedor.
6. Nas opções do nó, adicione o System Message com as regras do assistente.
7. Conecte pelo menos uma ferramenta ao agente, como o HTTP Request Tool, e, se quiser memória, o Simple Memory.
8. Envie uma mensagem pelo chat e confira a resposta.

Na documentação, o valor output ou text do agente é enviado ao usuário por padrão. Teste com perguntas diferentes antes de depender dele.

As opções do nó: prompt, System Message e Max Iterations

Prompt

O parâmetro Prompt define como o nó monta a mensagem que vai ao modelo. Há duas escolhas. Em Take from previous node automatically, o agente lê o campo chatInput do nó anterior. Em algumas versões e páginas da documentação, essa opção aparece como Connected Chat Trigger Node: é a mesma ideia com outro nome. Em Define below, você escreve um texto fixo ou uma expressão no campo Prompt (User Message).

Opções do Tools Agent

• System Message: uma mensagem enviada ao agente antes de a conversa começar. A documentação não mostra o valor padrão.
• Max Iterations: o número de vezes que o modelo pode rodar para tentar gerar uma boa resposta. O padrão é 10.
• Return Intermediate Steps: inclui ou não os passos intermediários do agente na saída final. A documentação indica essa opção para ajustar o comportamento do agente.
• Tracing Metadata: pares de chave e valor nos eventos de rastreamento, útil com o LangSmith.
• Automatically Passthrough Binary Images: passa imagens binárias ao agente como mensagens de imagem.
• Enable Streaming: o agente devolve os dados ao usuário em tempo real, conforme gera a resposta. Vem ligada e precisa de um gatilho que suporte, como o Chat Trigger.

Outra opção do nó é Require Specific Output Format. Ligada, ela exige conectar um parser: Auto-fixing Output Parser, Item List Output Parser ou Structured Output Parser.

Memória do agente: Simple Memory

O nó Simple Memory (antes chamado Window Buffer Memory) mantém o histórico do chat no fluxo. A documentação diz que nós de agente de IA podem usar memória, e que as chains não podem. Ele tem dois parâmetros:

• Session Key: a chave usada para guardar a memória nos dados do fluxo.
• Context Window Length: o número de interações anteriores que entram no contexto. A documentação não mostra o valor padrão, então escolha o seu.

Há dois limites escritos na documentação. O primeiro: se a instância do n8n usa queue mode, o Simple Memory não funciona num fluxo de produção ativo. O segundo: segundo a página do Tools Agent, a memória não persiste entre sessões. Se for usar o Chat Trigger com a opção Load Previous Session, a documentação recomenda ligar o Chat Trigger e o Agent ao mesmo sub-nó de memória, para haver uma única fonte da verdade nos dois nós.

Ferramentas do agente: Tools

As páginas do n8n citam estas ferramentas: Call n8n Workflow Tool, Custom Code Tool, HTTP Request Tool, Wikipedia e SerpAPI, além de servidores MCP. Três delas aparecem neste guia:

• HTTP Request Tool: deixa o agente chamar uma API. O guia HTTP Request no n8n: como chamar uma API no fluxo explica o nó HTTP Request do fluxo.
• Call n8n Workflow Tool: deixa o agente chamar outro fluxo seu.
• Custom Code Tool: segundo a documentação, serve para escrever código que o agente pode rodar. Tem os campos Description, que diz ao agente quando usar a ferramenta, Language, com JavaScript ou Python, e a caixa de código. A entrada chega como query.

No Custom Code Tool, a Description diz ao agente quando usar a ferramenta. Escreva o que ela faz e quando usá-la.

Erros comuns do AI Agent

A página de erros comuns da documentação lista quatro mensagens:

• Internal error: 400 Invalid value for 'content': pode acontecer se o Prompt tiver um valor nulo. Com Define below, confira se as expressões apontam para campos válidos. Com Connected Chat Trigger Node, remova os valores nulos do campo chatInput.
• Error in sub-node Simple Memory: a documentação o liga a uma versão antiga do nó, como em um fluxo ou template copiado. Ela sugere remover o Simple Memory do fluxo e adicioná-lo de novo.
• A Chat Model sub-node must be connected: o nó rodou sem um Chat Model. Abra o nó e clique em + Chat Model, na parte de baixo da tela.
• No prompt specified: o agente esperava o prompt do nó anterior, normalmente o Chat Trigger. Troque o Prompt para Define below e monte o prompt.

Para tratar falhas do fluxo inteiro, com alertas, o guia Tratar erros no n8n: Error Trigger e alertas no fluxo mostra como receber o aviso quando uma execução falha.

Quer ver os planos de n8n da Eleven Host? n8n Essencial a partir de R$ 19,90/mês; confira na loja o que cada plano inclui. Conhecer o n8n Essencial

Perguntas frequentes

O que é o AI Agent no n8n?

É o nó que monta um agente de IA no fluxo. Você conecta um modelo de chat e ferramentas, e o agente decide quais ferramentas chamar para cumprir a tarefa.

O AI Agent precisa de uma ferramenta?

Sim. A documentação pede pelo menos uma ferramenta conectada ao nó. O Chat Model também é necessário: sem ele, aparece o erro A Chat Model sub-node must be connected.

Qual o padrão do Max Iterations?

10. Esse número é quantas vezes o modelo pode rodar para tentar gerar uma boa resposta.

O agente lembra da conversa?

Só se você conectar uma memória, como o Simple Memory. Segundo a documentação, a memória não persiste entre sessões, e o Simple Memory não funciona em queue mode num fluxo de produção ativo.

Preciso escolher o tipo de agente?

Não. A opção de tipo ficou obsoleta a partir do n8n 1.82.0, e os nós AI Agent funcionam como Tools Agent.