Tutorial de Agentes IA no n8n: Crie Fluxos Inteligentes Passo a Passo

Tutorial de Agentes IA no n8n: Crie Fluxos Inteligentes Passo a Passo

A lacuna entre "quero um agente de IA" e "tenho um agente de IA funcional" geralmente consiste em centenas de linhas de código de ligação em Python. Os agentes de IA do n8n colmatam essa lacuna com um editor visual de fluxos de trabalho onde pode arrastar, largar e ligar agentes alimentados por LLM que realmente executam ações, pesquisam na web, consultam bases de dados, enviam e-mails e atualizam folhas de cálculo. Escreve uma mensagem do sistema em vez do código boilerplate de uma framework.

Este tutorial guia-o na construção de dois fluxos de trabalho reais de agentes desde zero: um agente de pesquisa na web e um bot de apoio ao cliente com memória. No final, compreenderá todos os tipos de nós necessários e como se articulam entre si.

O que é o n8n (e por que usá-lo para Agentes de IA)?

O n8n é uma plataforma de automação de fluxos de trabalho de código aberto, pense no Zapier, mas autoalojável e com uma filosofia de "código quando precisar". Liga mais de 500 serviços através de um editor visual baseado em nós.

O que torna o n8n interessante especificamente para agentes de IA é a sua integração nativa com LangChain. Em vez de escrever código Python do LangChain, configura os mesmos conceitos (agentes, ferramentas, memória, modelos) como nós visuais. O nó Agente de IA gere o ciclo de raciocínio; basta indicar-lhe com o que deve pensar e o que pode fazer.

Por que escolher o n8n em vez de código puro?

• Depuração visual: vê exatamente onde a cadeia de raciocínio do agente falha
• Mais de 500 integrações tornam-se ferramentas instantâneas para o agente (Slack, Gmail, Google Sheets, bases de dados)
• Autoalojamento gratuito (Edição Comunitária) ou use o n8n Cloud a partir de $20/mês
• O suporte para MCP permite que os fluxos do n8n se tornem ferramentas para agentes de IA externos e vice-versa

Se está a avaliar diferentes frameworks de agentes como LangGraph, CrewAI ou o OpenAI Agents SDK, o n8n situa-se numa categoria diferente: é para quem deseja agentes em produção sem gerir um runtime Python.

Como funciona o Nó de Agente de IA do n8n

Cada fluxo de trabalho de agente de IA no n8n tem uma estrutura hierárquica. O nó Agente fica no centro, e os subnós ligam-se abaixo dele para fornecer capacidades.

Eis a anatomia:

O Agente de Ferramentas é aquele que utilizará 90% das vezes. É o tipo de agente mais flexível: recebe o seu prompt, raciocina sobre quais ferramentas chamar, executa-as e repete o ciclo até obter uma resposta. Internamente, executa um ciclo ReAct (Raciocinar + Agir): pensar, agir, observar, repetir.

O n8n também oferece agentes especializados, um Agente SQL para consultas a bases de dados, um Agente de Planeamento e Execução que divide tarefas em subpassos, e um Agente Conversacional para fluxos de chat mais simples. Mas o Agente de Ferramentas cobre a maioria dos casos de uso.

O que precisa antes de começar

Antes de construir qualquer coisa, organize estes três itens:

1. Instância do n8n: inscreva-se no n8n Cloud ($20/mês plano Starter) ou aloje automaticamente com Docker:

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

1. Uma chave API de LLM: OpenAI, Anthropic ou Google Gemini. Também pode usar o Ollama para modelos locais gratuitos, embora o desempenho da chamada de ferramentas varie.

2. Uma chave API de ferramenta (opcional): SerpAPI para pesquisa na web ($50/mês) ou Brave Search API (camada gratuita). Pode criar agentes sem pesquisa, mas é a primeira ferramenta mais comum.

Assim que o n8n estiver em execução, abra http://localhost:5678 (autoalojado) ou o seu painel na cloud. Crie um novo fluxo de trabalho e estará pronto.

Construir Agente 1: Um Agente de Pesquisa na Web

Este agente recebe um tópico, pesquisa na web, lê os resultados e escreve um resumo estruturado. É o "hello world" dos agentes de IA do n8n e genuinamente útil para pesquisa de conteúdo.

Passo 1: Adicionar um Gatilho Manual

Clique no botão + e procure "Gatilho Manual". Largue-o na tela. Isto permite testar o fluxo de trabalho clicando em "Testar Fluxo de Trabalho"; mais tarde, poderá substituí-lo por um webhook ou gatilho de chat.

Passo 2: Adicionar um Nó de Editar Campos

Adicione um nó Editar Campos após o gatilho. Defina um campo chamado topic com um valor de string como "Últimos desenvolvimentos no Protocolo de Contexto de Modelo". Isto simula a entrada do utilizador.

Passo 3: Adicionar o Nó de Agente de IA

Procure por "Agente de IA" e adicione-o. Selecione Agente de Ferramentas como o tipo de agente.

No campo Mensagem do Sistema, escreva um prompt que defina o comportamento:

You are a research assistant. When given a topic:
1. Search the web for the latest information
2. Read at least 3 different sources
3. Write a structured summary with:
   - Key findings (bullet points)
   - Notable quotes or data points
   - Sources used

Be specific. Include dates, names, and numbers when available.
Do NOT make up information. If search results are unclear, say so.

Em Prompt, defina-o para a expressão: {{ $json.topic }}, isto extrai o tópico do nó Editar Campos.

Passo 4: Ligar um Modelo de Chat

Clique no + abaixo do nó Agente para adicionar um subnó. Selecione Modelo de Chat OpenAI (ou qualquer LLM que esteja a usar).

Configure-o:

• Modelo: gpt-4o (ou gpt-4o-mini para execuções mais económicas)
• Temperatura: 0.3 (mais baixa = mais factual, menos criativo)

Cole a sua chave API na secção de credenciais.

Passo 5: Adicionar a Ferramenta de Pesquisa

Clique novamente em + para adicionar um subnó de ferramenta. Escolha SerpAPI (ou Ferramenta de Pedido HTTP se quiser aceder a uma API de pesquisa personalizada).

Para SerpAPI:

• Adicione a sua chave API como credencial
• O agente chamará esta ferramenta sempre que decidir que precisa de pesquisar

Para uma alternativa gratuita, use a Ferramenta de Pedido HTTP configurada para aceder à API Brave Search:

URL: https://api.search.brave.com/res/v1/web/search
Method: GET
Query Parameters: q={{ $fromAI("query", "search query") }}
Headers: X-Subscription-Token: YOUR_BRAVE_KEY

A expressão $fromAI() é a magia: diz ao agente "tu decides que valor passar aqui".

Passo 6: Testar

Clique em Testar Fluxo de Trabalho. Observe o painel de execução à direita. Verá:

1. O agente recebe o tópico
2. Decide pesquisar (chamada de ferramenta)
3. A SerpAPI devolve resultados
4. O agente raciocina sobre os resultados
5. Pode pesquisar novamente para mais detalhes
6. Produz um resumo final

Se o agente entrar num ciclo sem convergir, o seu prompt do sistema provavelmente precisa de instruções mais precisas. Indique-lhe exatamente quando deve parar de pesquisar.

Construir Agente 2: Um Bot de Apoio ao Cliente com Memória

O agente de pesquisa era stateless (sem estado): esquecia tudo após cada execução. Um bot de apoio ao cliente precisa de lembrar a conversa. É aqui que entra a memória do agente.

Passo 1: Usar um Gatilho de Chat

Desta vez, comece com o nó Gatilho de Chat em vez do Gatilho Manual. Isto fornece-lhe o widget de chat integrado do n8n para testar conversas.

Passo 2: Configurar o Agente

Adicione um nó Agente de Ferramentas. Prompt do sistema:

You are a customer support agent for a SaaS project management tool called "TaskFlow."

Rules:
- Always greet the user by name if provided
- Check the knowledge base before answering questions
- If you cannot find an answer, say: "Let me connect you with a human agent"
- Never make up features or pricing that you don't find in the knowledge base
- Keep responses concise (2-3 sentences max unless the user asks for detail)

Available tools:
- Knowledge base search: use this for product questions
- Ticket creation: use this when the user reports a bug or requests a feature

Passo 3: Adicionar Memória

Clique em + no Agente para adicionar um subnó e selecione Memória de Buffer de Janela.

• Comprimento da Janela de Contexto: 10 (lembra os últimos 10 pares de mensagens)
• ID da Sessão: {{ $json.sessionId }} (do gatilho de chat)

Esta é a opção de memória mais simples: mantém as mensagens recentes numa janela deslizante. Para bots de produção que necessitam de memória persistente entre sessões, use Memória de Chat Postgres ou Memória de Chat Redis em vez disso. O nosso guia sobre as melhores ferramentas de memória para agentes de IA aborda as compensações entre estas abordagens.

Passo 4: Adicionar Ferramentas

Adicione dois subnós de ferramenta:

Ferramenta 1 -- Base de Conhecimento (QA de Armazenamento Vetorial): Se tiver documentação de produto num armazenamento vetorial (Pinecone, Qdrant, Supabase), use a Ferramenta de Pergunta e Resposta de Armazenamento Vetorial. Isto é essencialmente RAG (Geração Aumentada por Recuperação) num único nó.

Ferramenta 2 -- Criação de Ticket (Pedido HTTP): Adicione uma Ferramenta de Pedido HTTP configurada para POST para a sua API de tickets:

URL: https://api.yourapp.com/tickets
Method: POST
Body (JSON):
{
  "title": "{{ $fromAI('title', 'ticket title') }}",
  "description": "{{ $fromAI('description', 'issue description') }}",
  "priority": "{{ $fromAI('priority', 'low, medium, or high') }}"
}

Passo 5: Testar a Conversa

Clique em Testar Fluxo de Trabalho e abra o painel de chat. Tente uma conversa com múltiplos turnos:

• "Olá, sou o Alex. Como exporto as minhas tarefas para CSV?"
• "E quanto à exportação para PDF?"
• "Na verdade, a exportação para PDF não está a funcionar comigo, podem registar um bug?"

Observe como o agente pesquisa na base de conhecimento para as duas primeiras perguntas e cria um ticket para a terceira. O nó de memória garante que se lembra do nome do Alex e do contexto do problema do PDF.

Usar MCP para Expandir os seus Agentes

O n8n agora suporta o Protocolo de Contexto de Modelo (MCP) em ambas as direções, e é aqui que as coisas se tornam poderosas.

Consumir servidores MCP: Adicione o subnó Ferramenta Cliente MCP ao seu agente. Aponte-o para qualquer URL de servidor MCP e o agente descobre automaticamente e pode invocar todas as ferramentas que esse servidor expõe. Um nó, dezenas de ferramentas.

Expor fluxos de trabalho como ferramentas MCP: Use o nó Gatilho Servidor MCP para transformar qualquer fluxo de trabalho do n8n numa ferramenta compatível com MCP. Agentes externos em execução no Claude Desktop, Cursor ou VS Code podem então descobrir e chamar os seus fluxos de trabalho do n8n. Construa um fluxo de trabalho "enviar notificação Slack" uma vez, e todos os agentes compatíveis com MCP na sua stack podem usá-lo.

Este suporte bidirecional para MCP transforma o n8n num hub de agentes: os seus agentes n8n chamam ferramentas externas via MCP, e agentes externos chamam os seus fluxos de trabalho n8n via MCP.

Dicas Práticas para Melhores Agentes no n8n

Após construir dezenas de fluxos de trabalho de agentes, eis o que realmente importa:

Mantenha o número de ferramentas baixo. Os agentes ficam confusos com mais de 5-7 ferramentas. Se precisar de mais, crie um "agente gestor" que encaminha tarefas para "agentes trabalhadores" especializados; o n8n suporta fluxos de trabalho de agente para agente.

Seja prescritivo nos prompts do sistema. Não diga apenas "ajude o utilizador". Detalhe regras exatas, formatos de saída e quando usar cada ferramenta. Quanto mais específico for o seu prompt, menos chamadas de ferramenta surpreendentes ocorrerão.

Defina limites de tokens. Na configuração do Modelo de Chat, defina um limite máximo de tokens. Sem isso, um agente confuso pode esgotar o seu orçamento de API num único ciclo.

Use nós de tratamento de erros. Adicione um fluxo de trabalho de Gatilho de Erro que captura falhas e o notifica via Slack ou e-mail. Caso contrário, os agentes falham silenciosamente.

Teste primeiro com casos extremos. Pergunte ao seu agente algo que ele não deveria saber. Se alucinar em vez de dizer "não sei", o seu prompt precisa de guardas.

Registe tudo durante o desenvolvimento. Ative o registo de execução (disponível no plano Pro ou autoalojado) para poder reproduzir e depurar exatamente onde um agente errou.

Quando os Agentes n8n Fazem Sentido (e Quando Não)

O n8n é uma ótima escolha se:

• Quer agentes em produção sem gerir infraestrutura Python
• Os seus fluxos de trabalho ligam múltiplas ferramentas SaaS (Slack, Gmail, Notion, bases de dados)
• A sua equipa inclui não programadores que precisam de modificar o comportamento do agente
• Precisa de depuração visual das cadeias de raciocínio do agente

O n8n é provavelmente a escolha errada se:

• Precisa de controlo granular sobre arquiteturas de agentes (use LangGraph ou CrewAI em vez disso)
• O seu agente é puramente computacional (pipeline de ML, processamento de dados) sem integrações
• Está a construir um sistema de pesquisa multi-agente com gestão de estado complexa

Para casos de uso de automação empresarial, bots de apoio ao cliente, agentes de processamento de dados, assistentes de pesquisa, qualificação de leads, o n8n atinge um ponto ideal entre potência e acessibilidade.

FAQ

Que LLMs o n8n suporta para agentes de IA?

O n8n suporta OpenAI (GPT-4o, GPT-4, GPT-3.5), Anthropic Claude (famílias Claude 3.5 e 4), Google Gemini, Mistral, Cohere, modelos HuggingFace e modelos locais via Ollama. Troca de modelos alterando um único subnó, sem necessidade de alterar o fluxo de trabalho.

O n8n é gratuito para criar agentes de IA?

A Edição Comunitária autoalojada é completamente gratuita sem limites de execução. O n8n Cloud começa em $20/mês (Starter) com 2.500 execuções. Ainda terá de pagar separadamente ao seu fornecedor de LLM (OpenAI, Anthropic, etc.) pelas chamadas API.

Como se compara o Agente de IA do n8n a escrever agentes em Python?

O n8n troca personalização por velocidade. Um agente Python com LangChain dá-lhe controlo total sobre cada passo de raciocínio. O n8n dá-lhe 80% dessa capacidade em 20% do tempo, com depuração visual e mais de 500 integrações integradas. Escolha Python para pesquisa ou arquiteturas novas; escolha n8n para automação empresarial.

Os agentes n8n podem usar ferramentas como pesquisa na web e bases de dados?

Sim. Os agentes n8n podem usar qualquer ferramenta disponível como um nó: SerpAPI, Brave Search, Pedido HTTP (para qualquer API), bases de dados SQL, Google Sheets, Slack e centenas mais. Adiciona-as como subnós abaixo do nó Agente.

O que é a Ferramenta Cliente MCP no n8n?

A Ferramenta Cliente MCP liga o seu agente n8n a servidores MCP (Protocolo de Contexto de Modelo) externos. O seu agente descobre automaticamente todas as ferramentas que esse servidor expõe e pode chamá-las durante o raciocínio. É um único nó que pode desbloquear dezenas de ferramentas externas.

Como adiciono memória a um agente de IA no n8n?

Adicione um subnó de memória abaixo do seu nó Agente. A Memória de Buffer de Janela é a opção mais simples (mantém as últimas N mensagens). Para memória persistente entre sessões, use Memória de Chat Postgres, Memória de Chat Redis ou Memória Zep. Defina um ID de sessão para rastrear conversas individuais.

Posso ligar múltiplos agentes no n8n?

Sim. O n8n suporta fluxos de trabalho de agente para agente onde um agente "gestor" delega tarefas para agentes "trabalhadores" especializados. Constrói cada trabalhador como um subfluxo separado e liga-os através da ferramenta Chamar Fluxo de Trabalho n8n.

Qual é a diferença entre o Agente de Ferramentas e outros tipos de agente?

O Agente de Ferramentas usa um ciclo de raciocínio ReAct e funciona com qualquer ferramenta. O Agente de Funções OpenAI usa a API nativa de chamada de funções da OpenAI (ligeiramente mais rápida, mas apenas para OpenAI). O Agente SQL é especializado em consultas a bases de dados. O Agente de Planeamento e Execução divide tarefas complexas em subpassos. Para a maioria dos casos de uso, comece com o Agente de Ferramentas.

Como implemento um agente n8n em produção?

Para autoalojamento: use Docker Compose com PostgreSQL e Redis, ative o modo de fila para escalonamento horizontal e coloque-o atrás de um proxy reverso com SSL. Para cloud: basta ativar o fluxo de trabalho, o n8n gere a infraestrutura. Em ambos os casos, substitua o Gatilho de Chat por um gatilho Webhook para que aplicações externas possam chamar o seu agente.

Os agentes n8n podem lidar com uploads de ficheiros e imagens?

O n8n pode processar ficheiros através da sua gestão de dados binários. Pode criar agentes que recebem uploads de ficheiros via webhook, extraem texto (usando, por exemplo, um nó de Código com um analisador de PDF) e raciocinam sobre o conteúdo. A análise nativa de visão/imagem depende do seu LLM suportar entrada multimodal (o GPT-4o suporta, por exemplo).

Fontes

• Documentação do Nó Agente de IA n8n
• Visão Geral da Plataforma de Agentes de IA n8n
• Planos de Preços n8n
• Integração Servidor MCP n8n