Blog

04 de novembro de 2026

n8n 3.0: migrar o workflow ou mover a regra de negócio para código?

O n8n 3.0 é uma versão major com breaking changes, lançada em 27 de outubro de 2026 e descrita como early access. O artigo lista o que quebra, como usar o Migration Report e um critério para decidir o que fica no workflow e o que vira código com teste.

por Thalena Lima

6 min de leitura6 leituras
Três camadas físicas de uma automação, com um módulo de regra de negócio separado para migração a código.

Resposta rápida

Antes de migrar para o n8n 3.0, rode o Migration Report, resolva o que bloqueia o upgrade e decida onde cada regra mora: orquestração e conectores ficam no workflow; regras que não podem variar, como preço, alçada e agendamento, ficam em código com teste. O 3.0.0 está descrito como early access.

O n8n 3.0 é uma versão major, lançada em 27 de outubro de 2026, com mudanças que quebram workflows existentes. A decisão para quem opera automação com IA não é migrar tudo nem abandonar o n8n: é separar a orquestração, que pode ficar no workflow, da regra de negócio, que precisa de código testado.

O que o n8n 3.0 quebra e quem precisa agir primeiro

A página de notas de versão do n8n registra o 3.0 em 27 de outubro de 2026 como uma versão major com breaking changes. A página de breaking changes traz um aviso que pesa na decisão: o 3.0.0 está disponível como early access release (consulta feita em 4 de novembro de 2026).

Quem opera automação para clientes deve ler a lista antes de qualquer upgrade. A tabela traz cinco itens da documentação oficial; a lista completa é maior.

Mudança no 3.0Quem é afetadoO que a documentação manda fazer
Self-hosted exige Docker; instalações por npm ou npx n8n deixam de ser suportadasQuem hospeda o n8n em servidor próprio sem containerMigrar para Docker antes do upgrade
Nós removidos, como Function, Function Item, Cron e IntervalWorkflows antigos que usam esses nósTrocar pelo Code node (Function e Function Item) e pelo Schedule Trigger (Cron e Interval)
AI Agent na versão 1 removido, com os modos SQL, Conversational, OpenAI Functions, Plan and Execute e ReActAgentes montados com a versão antiga do nóAtualizar para a versão mais recente, que usa o Tools Agent
Timeout padrão das tarefas do Code node cai de 300 para 60 segundos (N8N_RUNNERS_TASK_TIMEOUT)Code nodes que rodam por mais de 1 minutoDefinir a variável de forma explícita
Credencial Slack API passa a exigir o signing secretWorkflows com Slack TriggerCadastrar o secret antes do upgrade; sem ele o workflow não ativa

A ferramenta de migração mostra o tamanho do problema na sua instância. Em Settings > Migration Report, ela lista workflows e configurações afetados, em cinco níveis de impacto, de "Upgrade blocked" a "Capability removed". A migração automática cobre só mudanças de nós, e a documentação manda testar o resultado antes de publicar e revisar a página de breaking changes para o que a ferramenta não detecta. Um detalhe de governança: marcar um workflow como "Won't fix" conta como resolvido no relatório.

Diagrama conceitual com três camadas de uma automação com IA: modelo para linguagem natural, workflow para orquestração e código para a regra de negócio.

Diagrama conceitual da Lena AI: exemplos de divisão por camada, sem captura de ferramenta.

Quando manter o fluxo no n8n e quando tirar a regra do workflow

A Anthropic distingue workflows, sistemas em que modelos e ferramentas seguem caminhos de código predefinidos, de agentes, em que o modelo dirige o próprio processo. A mesma publicação recomenda a solução mais simples possível e observa que sistemas agênticos costumam trocar latência e custo por desempenho. Para o gestor, a pergunta vem antes da escolha de ferramenta: quais decisões da operação não podem variar?

O critério da Lena AI separa três camadas, como no diagrama. O modelo cuida da linguagem natural. O workflow, no n8n 3.0 ou fora dele, cuida de gatilho, ordem e conectores. A regra de negócio, como preço, janela de agendamento e alçada, fica em código com teste: a mesma entrada produz a mesma saída, e cada mudança passa por revisão.

Isso não obriga a sair do n8n. O Code node roda JavaScript ou Python como uma etapa do workflow, mas não acessa o sistema de arquivos nem faz requisições HTTP, e no 3.0 o timeout padrão das tarefas cai para 60 segundos. Regra que cresce além desse limite pede um serviço próprio, chamado pelo workflow.

Para escrever e testar esse código, uma ferramenta como o Claude Code ajuda. A documentação oficial a descreve como uma ferramenta de programação agêntica que lê a base de código, edita arquivos e roda comandos, e cita entre os usos escrever testes e corrigir falhas. O código gerado continua exigindo revisão de quem responde pela operação.

Situação na operaçãoOnde a regra ficaCritério (Lena AI)
Fluxo estável, muitos conectores, quem mantém não programaWorkflow no n8n, depois do Migration ReportMudar um passo não exige deploy
Regra que não pode variar: preço, alçada, trava de segurançaCódigo com teste, no Code node ou em serviço chamado pelo workflowA mesma entrada dá a mesma saída e a mudança passa por revisão
Texto livre que precisa virar dado: classificar, extrair camposModelo, dentro de uma etapa do workflowO código valida a saída antes de seguir
Passos imprevisíveis, ferramentas claras e erro barato de reverterAgente, com limite de tentativas e aprovação humanaSó aqui o modelo decide o próximo passo

Os princípios de engenharia para agentes e sistemas com IA em produção detalham permissões, idempotência e testes, e o custo de uma migração de versão entra na conta de quanto custa operar uma automação com IA, junto com suporte e plano de saída.

Como decidir em seis passos antes de migrar

  1. Rode o Migration Report em Settings > Migration Report e exporte o CSV: a documentação descreve a exportação da visão geral, com uma linha por problema.
  2. Resolva primeiro o que bloqueia. Os itens "Upgrade blocked" e "Executions will fail" vêm antes de "Behavior changes".
  3. Liste as regras que não podem variar em cada workflow: preço, desconto, alçada, janela de agenda, trava de segurança. Cada regra recebe um dono e um par de entrada e saída esperada.
  4. Defina o lugar de cada regra: fica no workflow, vira código no Code node ou vira um serviço chamado pelo workflow. Use a tabela acima.
  5. Teste em cópia antes de publicar. Rode as mesmas entradas no fluxo antigo e no migrado e compare as saídas. A migração automática cobre só os nós.
  6. Registre as exceções. Cada "Won't fix" precisa de dono, motivo e data de revisão, porque o relatório já o conta como resolvido.

Como a documentação descreve o 3.0.0 como early access, o plano mais seguro é uma janela de teste em cópia da instância antes de qualquer data em produção.

Recursos e ecossistema Lena AI

Para continuar

Perguntas frequentes

Resumo e fontes

Pontos-chave5
  • O n8n 3.0 foi lançado em 27 de outubro de 2026 como versão major com breaking changes; a documentação oficial descreve o 3.0.0 como early access release.
  • O Migration Report do n8n 3.0 fica em Settings > Migration Report e classifica cada problema em cinco níveis de impacto, de Upgrade blocked a Capability removed.
  • A migração automática do n8n 3.0 cobre apenas mudanças de nós; a documentação manda testar o workflow migrado antes de publicar.
  • Regra de negócio que não pode variar, como preço, alçada e agendamento, deve viver em código com teste; o workflow orquestra e o modelo cuida da linguagem natural.
  • A Anthropic define workflows como sistemas em que modelos e ferramentas seguem caminhos de código predefinidos e recomenda a solução mais simples possível, aumentando a complexidade só quando necessário.
Respostas curtas4
O que muda no n8n 3.0 e quem precisa agir primeiro?
O 3.0 exige Docker para self-hosted, remove nós antigos como Function e Cron, remove a versão 1 do AI Agent, reduz o timeout das tarefas do Code node de 300 para 60 segundos e passa a exigir o signing secret na credencial Slack API. O Migration Report lista o que afeta cada instância.
Como usar a ferramenta de migração do n8n 3.0?
Abra Settings > Migration Report, revise os workflows e as configurações por nível de impacto, resolva primeiro o que bloqueia o upgrade e teste os workflows migrados antes de publicar. A migração automática cobre só mudanças de nós; o que a ferramenta não detecta está na página de breaking changes.
Quando mover a regra de negócio do workflow para código?
Quando a regra não pode variar, como preço, desconto, alçada, janela de agendamento ou trava de segurança. Em código, ela ganha teste e revisão, e a mesma entrada produz a mesma saída. O workflow continua cuidando de gatilhos, conectores e da ordem das etapas.
O n8n 3.0 já é uma versão estável para produção?
A documentação do n8n descreve o 3.0.0 como early access release (consulta em 4 de novembro de 2026). Por isso, o plano mais seguro é testar a migração em uma cópia da instância e só então definir a data em produção.
Fontes6
  • n8n Docs — Release notes(abre em nova guia)

    O n8n 3.0 está registrado nas notas de versão com data de 27 de outubro de 2026, como versão major com breaking changes.

  • n8n Docs — v3.0 Breaking changes(abre em nova guia)

    A página de breaking changes diz que o n8n 3.0.0 está disponível como early access release, exige Docker para self-hosted (sem suporte a npm ou npx n8n), remove nós como Function, Function Item, Cron e Interval, remove a versão 1 do AI Agent (a versão atual usa Tools Agent), reduz o timeout padrão do Code node de 300 para 60 segundos e exige o signing secret na credencial Slack API.

  • n8n Docs — v3.0 Migration tool(abre em nova guia)

    A ferramenta de migração fica em Settings > Migration Report, classifica problemas em cinco níveis de impacto (de Upgrade blocked a Capability removed), migra automaticamente apenas mudanças de nós, manda testar os workflows migrados antes de publicar, não detecta todas as mudanças e conta Won't fix como resolvido.

  • n8n Docs — Using the Code node(abre em nova guia)

    O Code node executa JavaScript ou Python como etapa do workflow e não acessa o sistema de arquivos nem faz requisições HTTP.

  • Anthropic — Building effective agents (19 de dezembro de 2024)(abre em nova guia)

    A Anthropic define workflows como sistemas em que modelos e ferramentas são orquestrados por caminhos de código predefinidos e agentes como sistemas em que o modelo dirige o próprio processo; recomenda a solução mais simples possível e observa que sistemas agênticos costumam trocar latência e custo por desempenho.

  • Claude Code Docs — Overview(abre em nova guia)

    O Claude Code é descrito pela documentação oficial como uma ferramenta de programação agêntica que lê a base de código, edita arquivos e roda comandos; entre os usos citados está escrever testes e corrigir falhas.

Próximas leituras