GUIA · NÍVEL 2 · 11 MIN DE LEITURA
Como criar seu primeiro agente de IA no n8n
Aprenda a criar seu primeiro agente de IA no n8n com o nó AI Agent, conectando modelo de chat e ferramentas para automação que decide por você.
Para criar seu primeiro agente de IA no n8n, use o nó AI Agent (a partir da versão 1.82.0, chamado Tools Agent). Conecte um modelo de chat, como GPT-4 ou Claude, e ao menos uma ferramenta para executar ações. O agente decide sozinho quais ferramentas chamar com base na sua instrução.
# Como criar seu primeiro agente de IA no n8n
Quando comecei a explorar automação além de fluxos fixos, os agentes de IA no n8n apareceram como uma forma de delegar decisões para a máquina. Você escreve uma instrução, conecta ferramentas e o agente escolhe o que fazer. Funciona, mas exige entender como o nó AI Agent opera dentro de um workflow.
O que é um agente de IA no n8n?
Um agente de IA no n8n é um nó de workflow, o AI Agent node, que conecta um modelo de linguagem grande (LLM) a ferramentas. Diferente de um fluxo comum, onde você programa cada passo, o agente decide quais ferramentas usar e em que ordem. Você dá a tarefa, ele planeja e executa.
Desde a versão 1.82.0, o tipo de agente anterior foi depreciado. O nó agora usa o Tools Agent por padrão, que foca em conectar o modelo de chat (a inteligência), as ferramentas (as ações) e as instruções (a estratégia). Isso simplifica: você configura modelo, ferramentas e prompt, e o agente faz o resto.
A documentação do n8n deixa claro que o AI Agent node opera dentro de um workflow que tem início e fim. Ele não é um robô autônomo que vive para sempre. É um componente inteligente que age durante a execução, decide quais ferramentas usar e retorna o resultado para o próximo nó.
Como o AI Agent node funciona?
O AI Agent node segue um ciclo de raciocínio e ação:
- Entrada da tarefa: Você define o objetivo, como "pesquise sobre X e resuma".
- Modelo de linguagem (LLM): O agente se conecta a um modelo de chat (GPT-4, Claude, Gemini ou outro). Esse modelo é o cérebro que interpreta a tarefa e decide o que fazer.
- Ferramentas: Você conecta ferramentas ao nó AI Agent, como um nó HTTP Request (para chamar APIs), Google Sheets (para ler ou gravar dados) ou pesquisa na web. O agente tem acesso a essas ferramentas e escolhe qual usar.
- Processo de decisão: O LLM analisa a tarefa, as ferramentas disponíveis e decide qual chamar, com quais parâmetros. Ele pode usar várias ferramentas em sequência até considerar a tarefa completa.
- Saída: Quando o agente termina, ele retorna o resultado para o próximo nó do workflow.
A Anthropic, em seus princípios para construção de agentes, defende começar com agentes modulares e transparentes. No n8n, isso significa criar agentes com ferramentas específicas e instruções claras, para que você entenda como ele chega às decisões.
Qual a diferença entre workflow e agente no n8n?
A diferença central está na tomada de decisão e na autonomia.
- Estrutura: Workflow tradicional: Caminho fixo, cada nó executa em ordem pré-definida; AI Agent node: Caminho dinâmico, o agente decide a sequência de ferramentas
- Tomada de decisão: Workflow tradicional: Programada por você; lógica explícita (IF/ELSE); AI Agent node: Autônoma; o modelo decide com base na tarefa e no contexto
- Flexibilidade: Workflow tradicional: Menos flexível a variações; exige muitos condicionais; AI Agent node: Mais flexível; lida com tarefas que exigem raciocínio
- Melhor para: Workflow tradicional: Processos repetitivos com regras fixas (ex: enviar e-mail); AI Agent node: Tarefas que exigem raciocínio e uso de múltiplas ferramentas (ex: pesquisa)
- Complexidade: Workflow tradicional: Menor para tarefas simples; AI Agent node: Maior na configuração inicial do agente e das ferramentas
Como descrevi no artigo Workflow ou agente? Como decidir antes de construir, a escolha depende da complexidade e da imprevisibilidade da tarefa. Se o processo é 100% previsível, um workflow tradicional é mais eficiente e barato. Se exige raciocínio adaptativo, o agente vale a pena.
Como começar seu primeiro agente de IA no n8n?
Preparar o ambiente não é complicado, mas exige alguns itens:
- Conta n8n: Cloud ou self-hosted. Recomendo cloud para começar.
- Modelo de chat: Credenciais de um LLM (OpenAI GPT-4, Anthropic Claude, Google Gemini ou Mistral). Você vai precisar da chave de API.
- Ferramentas: Ao menos uma ferramenta para o agente interagir. Pode ser um nó HTTP Request, um nó para manipular arquivos ou outro nó customizado.
- Um objetivo claro: "Responder perguntas" é vago. "Responder perguntas sobre tema X usando base de conhecimento Y" é melhor.
Passo a passo para o seu primeiro agente
Vamos criar um agente que pesquisa algo na web e resume:
- Inicie um novo workflow: No n8n, clique em "Add new workflow". - Adicione um nó Start: Esse é o gatilho do seu workflow. - Adicione o nó AI Agent: Pesquise por "AI Agent" e adicione. - Configure o modelo de chat: Dentro do nó AI Agent, na seção "Model", selecione seu LLM (ex: OpenAI Chat Model). Adicione suas credenciais de API. - Defina as instruções (prompt): Na seção "Prompt", você diz ao agente o que fazer. Exemplo: ``` Você é um assistente de pesquisa. Sua tarefa é buscar informações na internet sobre o tópico fornecido e resumir os 3 pontos mais importantes. Seja conciso. Use a ferramenta 'Search Web' para buscar. ``` - Adicione a ferramenta de pesquisa: Para o agente pesquisar na web, você precisa de uma ferramenta. Use um nó HTTP Request configurado para chamar uma API de pesquisa (como Serper API ou Google Search API). Para que o nó AI Agent enxergue essa ferramenta, você conecta um nó AI Agent Tool ao nó AI Agent e configura esse AI Agent Tool para apontar para o nó de pesquisa. - Conecte e teste: Conecte o nó Start ao AI Agent. Adicione um nó "Set" antes do AI Agent para passar o tópico da pesquisa (ex: `{"topic": "engenharia de prompt"}`). Execute o workflow e observe a saída.
Seu workflow fica assim: Start > Set (com o tópico) > AI Agent > Chat Model (configurado dentro do AI Agent) > AI Agent Tool (que referencia um nó HTTP Request para pesquisa web).
Erros comuns e como evitá-los
No meu dia a dia, encontro alguns obstáculos recorrentes:
- Instruções vagas: "Aja como assistente" não basta. Seja específico: "Você é um assistente de marketing que analisa campanhas no Instagram e propõe melhorias, usando a ferramenta X para coletar dados." A clareza do prompt é tudo.
- Ferramentas não conectadas ou mal configuradas: O agente só usa as ferramentas que você conecta. Garanta que o nó AI Agent Tool está configurado corretamente e que a ferramenta subjacente (como o HTTP Request) funciona. Eu sempre testo a ferramenta sozinha antes de conectá-la ao agente.
- Alucinações e respostas imprecisas: Isso acontece se o LLM não tem informações suficientes ou se as instruções são ambíguas. Garanta que o agente tenha acesso aos dados corretos através das ferramentas e que o prompt direcione o comportamento.
- Custos inesperados: Cada interação do agente com o LLM e com as ferramentas gera custo. Fique atento ao volume de chamadas e ao tamanho das entradas/saídas. Um agente mal otimizado pode sair caro. Como abordei no artigo Quanto custa implementar IA numa PME (em reais), planejar e monitorar é essencial.
- Dependência excessiva: Não use agente para tudo. Se a tarefa é determinística e não exige raciocínio complexo, um workflow tradicional é mais eficiente e barato.
Quando usar e quando não usar um agente de IA?
Minha regra prática:
Use um agente de IA se:
- A tarefa exige raciocínio, planejamento e tomada de decisão baseada em informações variadas.
- A tarefa envolve múltiplas etapas que não são totalmente previsíveis ou que podem variar dependendo do contexto.
- Você precisa que a IA escolha a ferramenta mais adequada entre várias opções para resolver um problema.
- A tarefa exige síntese e análise de dados de diferentes fontes.
- A complexidade de um workflow tradicional se tornaria proibitiva, com muitas ramificações e condicionais.
Não use um agente de IA (e prefira um workflow determinístico) se:
- A tarefa é simples, repetitiva e segue um caminho linear sem grandes variações (ex: enviar e-mail após preencher formulário, agendar posts).
- Os custos de execução precisam ser extremamente previsíveis e baixos. Agentes tendem a ser mais caros devido às chamadas ao LLM e às ferramentas.
- A segurança e a privacidade dos dados são críticas, e qualquer autonomia do agente pode representar um risco.
- A tarefa pode ser facilmente resolvida com nós sequenciais do n8n, sem necessidade de lógica de decisão complexa.
Como disse no artigo Por onde começar com IA na empresa: 5 passos, comece com o problema, não com a tecnologia. Se o problema não se encaixa na flexibilidade de um agente, não force. Um agente não é a solução para todos os problemas de automação, mas é uma ferramenta poderosa no contexto certo.
FAQ: Perguntas frequentes sobre agentes de IA no n8n
O que é o Tools Agent no n8n? O Tools Agent é o tipo de agente padrão no nó AI Agent do n8n a partir da versão 1.82.0. Ele é otimizado para decidir quais ferramentas chamar para completar uma tarefa, baseado nas instruções fornecidas e nas ferramentas que você conecta a ele.
Qual LLM devo usar para meu agente no n8n? A escolha do LLM depende do seu caso de uso e orçamento. Modelos como GPT-4 da OpenAI, Claude da Anthropic ou Gemini do Google são boas opções pela capacidade de raciocínio. Comece com um modelo que ofereça um bom equilíbrio entre capacidade e custo para experimentação.
O agente precisa de memória? Para tarefas simples, não. Para conversas mais longas ou para agentes que precisam lembrar de interações anteriores, a memória (geralmente implementada com o nó Memory no n8n) é essencial. Ela permite que o agente mantenha o contexto ao longo de múltiplas interações.
Posso usar agentes de IA para atendimento ao cliente no WhatsApp? Sim, é possível usar agentes de IA no n8n para atendimento no WhatsApp, configurando o agente para interagir com a API do WhatsApp e ferramentas de base de conhecimento. É essencial testar exaustivamente e monitorar para garantir a qualidade das interações, como explorado no artigo [Atendimento no WhatsApp com IA: como funciona](/blog/atendimento-whatsapp-ia).
Como garantir a segurança do meu agente de IA no n8n? Para garantir a segurança, valide todas as entradas do usuário, limite o acesso do agente às ferramentas necessárias e monitore as execuções. Além disso, pratique o harness engineering, controlando as saídas e o comportamento do agente para evitar prompt injection ou ações indesejadas, um tema que abordei em [Harness engineering: o que é e por que importa](/artigos/o-que-e-harness-engineering).
Perguntas frequentes
O que é o Tools Agent no n8n?
O Tools Agent é o tipo de agente padrão no nó AI Agent do n8n a partir da versão 1.82.0. Ele é otimizado para decidir quais ferramentas chamar para completar uma tarefa, baseado nas instruções fornecidas e nas ferramentas que você conecta a ele.
Qual LLM devo usar para meu agente no n8n?
A escolha do LLM depende do seu caso de uso e orçamento. Modelos como GPT-4 da OpenAI, Claude da Anthropic ou Gemini do Google são boas opções pela capacidade de raciocínio. Comece com um modelo que ofereça um bom equilíbrio entre capacidade e custo para experimentação.
O agente precisa de memória?
Para tarefas simples, não. Para conversas mais longas ou para agentes que precisam lembrar de interações anteriores, a memória (geralmente implementada com o nó Memory no n8n) é essencial. Ela permite que o agente mantenha o contexto ao longo de múltiplas interações.
Posso usar agentes de IA para atendimento ao cliente no WhatsApp?
Sim, é possível usar agentes de IA no n8n para atendimento no WhatsApp, configurando o agente para interagir com a API do WhatsApp e ferramentas de base de conhecimento. É essencial testar exaustivamente e monitorar para garantir a qualidade das interações.
Como garantir a segurança do meu agente de IA no n8n?
Para garantir a segurança, valide todas as entradas do usuário, limite o acesso do agente às ferramentas necessárias e monitore as execuções. Além disso, pratique o harness engineering, controlando as saídas e o comportamento do agente para evitar prompt injection ou ações indesejadas.