Tutorial N8N AI Agent: Do Prompt Simples ao Fluxo de Trabalho com Dados Estruturados

Por que a automação de fluxo de trabalho agora precisa de mais do que regras fixas

Imagine um fluxo de trabalho que recebe uma frase como esta: “Um novo cliente chamado John comprou um servidor gpu em 01/06/2026.” Uma pessoa lê isso e instantaneamente vê três valores úteis: o nome do cliente, o produto e a data.

Um fluxo de trabalho rígido não. Ele pode dividir texto, procurar padrões e validar formatos, mas no momento em que a redação muda — “John acabou de encomendar um servidor GPU ontem” ou “Novo cliente John comprou hospedagem em 1º de junho” — a análise frágil começa a se quebrar.

Essa é a fronteira entre automação clássica e a camada de IA. Fluxos de trabalho determinísticos se destacam quando as entradas estão limpas: roteamento de dados, transformação de campos, validação de registros, chamadas de API e repetição de sequências de forma confiável. Eles tropeçam no primeiro passo confuso — interpretar intenção, classificar solicitações, resumir conteúdo não estruturado ou extrair campos de linguagem natural antes que o fluxo de trabalho possa agir.

É exatamente aí que um n8n AI Agent se torna prático. Neste guia, você primeiro obterá uma compreensão em linguagem simples do que o n8n AI Agent realmente é dentro de um fluxo de trabalho, depois construirá um primeiro caso de uso fundamentado que transforma linguagem natural em dados estruturados.

O que um Agente n8n AI realmente é

Dentro do n8n, um Agente AI é melhor compreendido como um passo de raciocínio dentro de um workflow. É um nó que usa um modelo para interpretar entrada, trabalhar com contexto e ajudar a moldar o que acontece a seguir. Isso pode significar responder a um prompt, extrair campos, classificar uma solicitação ou decidir como o próximo passo do workflow deve ser preparado. A parte importante é que o agente vive dentro do workflow. Não é o sistema inteiro por si só.

As partes móveis são mais fáceis de entender quando você as separa por função:

O modelo lida com a interpretação flexível. Os nós n8n circundantes ainda possuem a estrutura: de onde os dados vêm, como são mapeados, o que é validado, qual nó é executado a seguir e o que finalmente é escrito em outro sistema. Se você precisa de execução previsível, aprovações, integrações ou regras de negócio, o workflow permanece no comando.

💡 Dica: O modelo mental mais limpo é este: o workflow ainda são os trilhos; o agente é o passo de raciocínio dentro desses trilhos.

Isso também torna mais fácil dizer o que o Agente n8n AI não é. Não é apenas um nó de chatbot. Não é autonomia mágica. Não é algo que todo workflow precisa. Se uma regra fixa, uma transformação simples ou um prompt AI limitado já resolve o trabalho, adicionar uma camada de agente apenas adiciona complexidade. O valor aparece quando o workflow tem que lidar com ambiguidade antes de poder se tornar determinístico novamente.

Onde os Agentes de IA n8n ajudam mais em fluxos de trabalho reais

O melhor lugar para usar um Agente de IA n8n é na borda onde a ambiguidade humana entra no sistema.

• As equipes de suporte podem precisar ler uma solicitação recebida e classificar se é faturamento, técnica ou urgente.
• As equipes de operações podem receber solicitações internas em linguagem natural e precisar extrair campos antes do roteamento.
• As equipes de vendas podem querer transformar uma mensagem de lead confusa em dados limpos e prontos para CRM.
• Fluxos de trabalho com muitos documentos podem precisar extrair nomes, datas, números de faturas ou detalhes de serviço de texto não estruturado.

Em cada um desses casos, a divisão de trabalho permanece a mesma. O agente interpreta, extrai, resume ou classifica. Os nós determinísticos então validam a saída, a roteiam para o ramo correto, criam registros, notificam pessoas ou escrevem o resultado em outro sistema. Essa fronteira é importante porque mantém a parte útil da IA — interpretação flexível — sem abrir mão da previsibilidade que torna a automação de fluxo de trabalho vale a pena usar.

A extração estruturada é um caso de uso particularmente forte porque é limitado, visível e imediatamente útil a jusante. Você pode ver a frase de entrada, definir os campos que deseja de volta e usar esses campos como dados normais de fluxo de trabalho. Isso torna o resultado concreto. Em vez de “a IA disse algo útil,” você obtém “o fluxo de trabalho agora tem nome, produto e data, e o próximo nó pode agir sobre eles.”

É também um bom lugar para manter uma disciplina em mente: mais comportamento de agente não é automaticamente melhor. Se uma regra fixa ou um único prompt já resolve o problema, você provavelmente não precisa de uma camada de agente completa. Este artigo se aprofunda em extração estruturada porque mostra valor real de fluxo de trabalho sem pretender que todo problema de automação precisa de ampla autonomia.

O que estamos construindo neste tutorial

Este tutorial ensina dois fluxos de trabalho propositalmente. O Fluxo de trabalho A é o padrão mais pequeno possível:

Manual Trigger -> Set -> AI Agent -> OpenRouter Chat Model -> plain response

O seu trabalho não é impressioná-lo. O seu trabalho é tornar o caminho dos dados visível para que possa ver exatamente como o prompt entra no fluxo de trabalho, chega ao agente e volta como uma resposta normal.

O Fluxo de trabalho B mantém essa mesma base e a atualiza com um Analisador de Saída Estruturada mais um nó de código Criar fatura. Em vez de retornar um parágrafo, o agente retornará campos previsíveis. Esses campos são então usados para construir um objeto de fatura, o que torna a saída imediatamente útil para o resto do fluxo de trabalho.

Essa progressão em duas etapas é importante. Primeiro, vê como o agente se comporta na forma mais simples possível. Depois, vê por que a saída de IA simples é apenas metade da história para automação. O verdadeiro retorno vem quando o fluxo de trabalho transforma linguagem natural em dados estruturados.

Antes de começar: pré-requisitos e preparação

Antes de construir o workflow, tenha três coisas prontas:

1. Uma instância n8n em execução
2. Permissão para criar e editar um workflow
3. Credenciais OpenRouter API funcionando

Você pode executar a mesma lógica no n8n Cloud se quiser, mas este artigo é enquadrado em torno de um ambiente auto-hospedado porque esse é um caso de uso comum no estilo AlexHost quando as equipes querem mais controle sobre dados, rede ou integrações privadas.

A fonte prática para este tutorial foi observada no n8n 2.26.8 em execução em um VPS AlexHost. Se você ainda precisar implantar n8n antes de tentar a parte de IA, use o guia AlexHost separado aqui: n8n automation tutorial for Ubuntu: from zero to flow.

📓 Nota: Uma pequena observação de terminologia antes de continuar: a documentação mais recente pode mostrar o nó Set como Edit Fields (Set), mas este passo a passo mantém a terminologia mais simples Set porque é o que a fonte prática usa.

A razão pela qual este artigo começa com Manual Trigger + Set em vez de Chat Trigger é simples: mantém a entrada explícita, facilita a inspeção do mapeamento e remove uma camada de confusão para uma primeira construção. Você está aprendendo como um nó AI Agent se encaixa em um workflow e como esse workflow se move de um prompt livre para uma saída estruturada e pronta para automação.

Hands-on Part 1: construir o fluxo de AI Agent n8n mais pequeno possível

Este primeiro fluxo de trabalho prova o padrão base antes de pedirmos para fazer algo mais útil. Você criará uma entrada visível, passará para o AI Agent, conectará um modelo OpenRouter e confirmará que o fluxo de trabalho retorna uma resposta de texto normal.

1.0 Adicionar o nó de gatilho e entrada

Comece colocando um nó Manual Trigger e um nó Set na tela. Isso mantém o ponto de entrada simples e oferece um campo claro para passar para o agente.

Neste ponto, você ainda não está fazendo nada “específico de IA”. Você está preparando uma entrada de fluxo de trabalho limpa para que o próximo nó tenha algo explícito para ler.

1.1 Configurar o nó Set

Abra o nó Set, mude para Manual Mapping, crie um campo chamado prompt e cole o texto inicial abaixo. Isso oferece ao fluxo de trabalho um valor visível que você pode trocar posteriormente por uma frase mais comercial.

Hello, who are you?

O que isso faz é simples mas importante: em vez de ocultar o prompt dentro do nó de IA, você o mantém em dados normais do fluxo de trabalho. Isso torna o caminho de entrada mais fácil de entender e reutilizar.

2.0 Colocar o AI Agent e conectar um modelo de chat

Agora adicione um nó AI Agent e conecte um OpenRouter Chat Model à sua entrada Chat Model. Em termos de iniciante, as entradas visíveis significam isto: Chat Model é o modelo que o agente usa para responder, Memory é contexto opcional que persiste entre turnos, e Tool é a conexão opcional que permite ao agente chamar capacidades externas. Neste primeiro fluxo de trabalho, apenas o modelo está conectado porque o objetivo é entender o padrão de funcionamento mais pequeno.

Uma vez que isto está em vigor, a divisão de papéis torna-se visível: o fluxo de trabalho carrega a entrada e o agente tratará da etapa de interpretação.

2.1 Configurar o modelo OpenRouter

Selecione a credencial da sua conta OpenRouter e escolha o mesmo modelo mostrado no fluxo de trabalho de origem: deepseek/deepseek-v4-flash. Você não precisa de ajuste extra para esta primeira passagem.

📝 Nota: Os modelos OpenRouter disponíveis podem variar por conta, mesmo que o exemplo de fonte de verdade aqui use deepseek/deepseek-v4-flash.

Se a sua conta mostrar uma lista diferente, o padrão do fluxo de trabalho ainda importa mais do que o nome exato do modelo.

3.0 Mapear o campo prompt para o AI Agent

Conecte a saída do nó Set ao AI Agent, defina Source for Prompt (User Message) como Define below e mapeie o valor do fluxo de trabalho para o campo de prompt usando a expressão abaixo. Isto diz ao agente para ler o valor prompt dos dados a montante em vez de usar uma mensagem codificada dentro do nó.

{{ $json.prompt }}

Esse mapeamento é a ponte-chave entre dados normais do n8n e a etapa de IA. Uma vez que clica, o resto do tutorial fica muito mais fácil de seguir.

3.1 Executar o fluxo de trabalho

Execute o fluxo de trabalho para que os dados se movam através da cadeia completa: Manual Trigger -> Set -> AI Agent -> OpenRouter Chat Model. Você está verificando não apenas que o modelo responde, mas que o fluxo de trabalho passa o prompt de forma limpa de um nó para o próximo.

Se a execução for bem-sucedida, você agora tem prova de que o agente pode consumir dados do fluxo de trabalho em vez de apenas digitar livremente dentro de sua própria interface.

3.2 Rever a resposta

Abra a saída e inspecione o resultado. Nesta fase, o AI Agent retorna uma resposta de texto normal ao prompt. Esse é o padrão básico na sua forma mais simples: prompt dentro, resposta fora.

Esse primeiro fluxo de trabalho importa porque prova a tubagem. Também mostra a limitação claramente: um parágrafo é bom para interação, mas desajeitado para automação a jusante. O próximo passo é onde o fluxo de trabalho se torna muito mais útil.

Parte Prática 2: transformar a resposta em dados de fluxo de trabalho estruturados

Agora mantemos o mesmo fluxo de trabalho base e alteramos o objetivo. Em vez de pedir ao agente uma resposta geral, pediremos que ele extraia campos previsíveis que o próximo nó possa usar como JSON normal.

4.0 Alterar o prompt e exigir um formato específico

Volte ao nó Set e substitua a saudação casual pela frase em estilo comercial abaixo. Em seguida, ative Require Specific Output Format no AI Agent para que o fluxo de trabalho deixe de visar prosa e comece a visar extração estruturada.

A new client named John bought a gpu server on 01/06/2026

Este é o momento em que o caso de uso se torna real. A frase contém dados que um humano compreende instantaneamente, e o fluxo de trabalho está sendo ensinado a retornar esses dados em um formato utilizável por máquinas.

4.1 Adicionar um Analisador de Saída Estruturada

Conecte um Structured Output Parser à entrada Output Parser do AI Agent. Este analisador é o que dá ao modelo uma estrutura alvo em vez de deixá-lo responder em texto livre.

📝 Nota: O Structured Output Parser é uma boa opção para esta primeira demonstração, mas a orientação oficial do n8n observa que a análise direta em agentes pode ser menos confiável em fluxos de trabalho mais avançados. Para este padrão iniciante, ainda é o passo de ensino correto porque torna a mudança de forma de dados fácil de ver.

A ideia importante não é o nó extra em si. É que você está transformando “resposta de IA” em “contrato de fluxo de trabalho.”

4.2 Definir o esquema de saída a partir de um exemplo JSON

No analisador, defina Schema Type como Generate From JSON Example e use o exemplo exato abaixo. Isso dá ao agente um esquema claro com os três campos que o fluxo de trabalho espera receber.

{
  "name": "Alex",
  "product": "VPS hosting",
  "date": "21/6/2026"
}

Depois de definir esse exemplo, você não está mais pedindo ao modelo para “dizer algo útil.” Você está pedindo que ele retorne uma estrutura previsível com name, product e date.

4.3 Verificar o resultado estruturado

Execute o fluxo de trabalho novamente e inspecione a saída do AI Agent. Desta vez, o resultado deve retornar como campos em vez de um parágrafo.

Essa mudança de forma é a verdadeira atualização. A saída estruturada não é apenas formatação mais bonita. É o que torna o resultado confiável o suficiente para que a lógica downstream o consuma sem adivinhar.

4.4 Usar os campos analisados em um nó JavaScript de fatura

Agora passe o resultado para um nó JavaScript Create invoice. O detalhe de fonte de verdade chave neste passo a passo é que o objeto analisado é lido de $input.first().json.output, o que significa que o código está consumindo a saída do agente estruturado diretamente.

// Input data
const order = $input.first().json.output

// Parse the order date
const [day, month, year] = order.date.split("/");
const orderDate = new Date(`${year}-${month}-${day}`);

// Generate a pseudo unique invoice ID (8 chars)
function generateId() {
  return Math.random().toString(36).substring(2, 10);
}
const invoiceId = generateId();

// Calculate payment due date (7 days later)
const dueDate = new Date(orderDate);
dueDate.setDate(orderDate.getDate() + 7);

// Build invoice record
const invoice = {
  invoice_id: invoiceId,
  customer: order.name,
  product: order.product,
  order_date: orderDate.toISOString().split("T")[0],
  due_date: dueDate.toISOString().split("T")[0],
  status: "Pending"
};

// Print invoice
console.log("Invoice Generated:");
for (const [key, value] of Object.entries(invoice)) {
  console.log(`${key}: ${value}`);
}

// If inside n8n Function node, return JSON
return [{ json: invoice }];

É aqui que o fluxo de trabalho deixa de se comportar como uma demonstração de chat e começa a se comportar como automação. O agente extraiu os campos, e o próximo nó os usou exatamente como qualquer outra entrada estruturada.

4.5 Revisar os dados de fatura gerados

Abra a saída final e inspecione o objeto de fatura. Você deve ver campos utilizáveis como invoice_id, customer, product, order_date, due_date e status.

Este é o ciclo de vida completo que o artigo vinha construindo: frase em linguagem natural -> extração estruturada -> registro de fatura. Uma vez que o resultado tenha essa forma, o fluxo de trabalho pode passá-lo para etapas posteriores com a mesma confiabilidade de qualquer outro payload JSON.

O que estes dois primeiros workflows realmente provam

Em conjunto, os dois workflows mostram dois padrões diferentes para o n8n AI Agent. O primeiro padrão é resposta simples a prompt: o agent recebe texto e responde com texto. O segundo padrão é extração estruturada: o agent recebe linguagem humana desordenada e retorna campos que o workflow pode realmente usar.

Essa diferença importa porque a atualização é sobre capacidade, não estética. A geração de texto ajuda com interação. A extração estruturada ajuda com automação. O segundo padrão é o que transforma o passo de IA de “interessante” em operacionalmente útil.

A tabela abaixo resume essa mudança:

Assim que você compreender esse caminho de atualização, o exemplo de fatura deixa de ser “um tutorial de fatura” e se torna um padrão de workflow reutilizável. A mesma abordagem pode alimentar captura de leads, intake de suporte, análise de pedidos, enriquecimento de tickets ou encaminhamento de solicitações internas. Em cada caso, o objetivo é o mesmo: transformar linguagem natural em dados estruturados e depois deixar os nós de workflow determinísticos fazerem o resto.

O que tentar a seguir após este primeiro caso de uso

O passo mais seguro não é autonomia—é manter o padrão limitado e atualizar uma variável de cada vez. Troque Manual Trigger por um Chat Trigger ou Webhook quando precisar de entrada inbound. Adicione memória apenas quando a continuidade importa. Anexe ferramentas apenas quando o agente deve procurar algo ou agir além do nó. Depois adicione validação ou aprovação se as saídas tocarem sistemas reais.

Self‑hosting torna-se crítico quando workflows precisam de entradas privadas, acesso a serviços internos, uptime previsível ou controle mais apertado—aqui a infraestrutura VPS estilo AlexHost faz parte do design, não apenas do background. Para deployment, o mesmo guia AlexHost cobre setup: n8n automation tutorial for Ubuntu: from zero to flow.

📝 Nota: A regra orientadora: heurística do sistema mais pequeno. Se a extração estruturada resolve o problema, pare aí. Não adicione memória, ferramentas ou autonomia a menos que o workflow realmente as exija.

Comece com um caso de uso limitado, não com hype de autonomia

A automação rígida geralmente quebra no momento em que a entrada humana bagunçada entra no sistema. Essa é a lacuna em que este artigo se concentrou. Agora você tem tanto o modelo mental quanto um padrão funcional: o n8n AI Agent lida com a etapa de interpretação flexível, e o fluxo de trabalho circundante transforma esse resultado em algo estruturado e confiável.

Essa é a regra de design que vale a pena manter. Comece com tarefas de interpretação controladas que produzem dados prontos para fluxo de trabalho. Expanda para memória, ferramentas ou gatilhos mais ricos apenas quando o fluxo de trabalho real precisar deles — não porque a palavra “agente” torna a autonomia maior parecer mais impressionante.