Sub-workflows do n8n

Quando Usar

Use esta habilidade quando a lógica compartilhada ou de múltiplos passos deve se tornar um workflow reutilizável e tipado, quando um workflow existente se torna difícil de entender, ou quando um agente precisa de um workflow exposto como uma ferramenta.

Preserve os limites de autenticação e autorização ao extrair lógica. Não coloque credenciais em entradas ou dados retornados, declare explicitamente o comportamento de mudança de estado e pergunte antes de executar ou ativar um sub-workflow que envia, escreve, deleta ou chama um serviço externo cobrável.

Um sub-workflow é uma função reutilizável. Um Gatilho de Executar Workflow declara entradas tipadas, o corpo faz o trabalho e o último nó retorna a saída. Um chamador o invoca através de um nó Executar Workflow como qualquer outra etapa.

Essa estrutura oferece os benefícios que as funções oferecem em qualquer lugar: encapsulamento, reutilização, testabilidade, substituibilidade. É o principal mecanismo de reutilização no n8n e é muito subutilizado. Sem ele, a mesma lógica é copiada e colada em vários workflows — então um bug é corrigido em dois lugares, a terceira cópia é esquecida e suas cópias "idênticas" silenciosamente divergem.

Esta habilidade trata de quando usar um sub-workflow, como definir seu contrato de entrada/saída para que chamadores (e agentes) possam realmente usá-lo, como chamá-lo corretamente (all vs each, bloqueante vs. "dispare e esqueça") e como nomeá-lo para que seja encontrado em vez de reconstruído.

Os dois não negociáveis

Todo o resto é julgamento. Estes dois não são.

1. Pesquise antes de construir

Antes de escrever lógica para um problema genérico, verifique se um sub-workflow já o faz. O MCP da comunidade não pode filtrar workflows por tag, então o nome é a superfície de descoberta:

n8n_list_workflows()                          # scan the library
n8n_get_workflow({ id: "<candidate>" })       # read its inputs/outputs + body

Se algo se encaixa, use-o e diga ao usuário ("Encontrei Subworkflow: Parse RFC2822 date — usando isso"). Se nada se encaixa, construa-o com um nome detectável para que a próxima pesquisa o encontre. A convenção de descoberta (prefixos verbais) está em references/NAMING_AND_DISCOVERY.md.

2. O Gatilho de Executar Workflow usa "Definir Abaixo" com campos tipados — não passagem direta

O gatilho tem dois modos de entrada. Defina como padrão "Definir Abaixo" com campos tipados explícitos. "Definir Abaixo" é o único modo que dá aos chamadores um esquema para preencher — é o que permite que um agente de IA passe valores via $fromAI e o que permite que chamadores estruturados mapeiem campos de forma limpa. A passagem direta não tem esquema, então o gatilho não pode ser configurado como uma ferramenta de agente limpa e chamadores estruturados não têm nada para vincular.

Duas exceções, e apenas duas:

• Entrada binária. Campos tipados são apenas JSON. Se o sub-workflow deve receber uma imagem/arquivo/PDF, você precisa de passagem direta para que o slot binary flua.
• Zero entradas. "Definir Abaixo" requer pelo menos um campo. Uma operação genuinamente sem argumentos ("listar credenciais ativas", "contagem atual") não tem onde colocar um esquema vazio, então a passagem direta é a única opção.

Fora desses dois casos, a passagem direta é um bug. Veja "Entradas e saídas como um contrato" abaixo.

Isso deveria ser um sub-workflow?

Você está prestes a escrever um pedaço de lógica. Passe-o por isto:

Could this plausibly be needed in another workflow?
  └─ Yes → extract.

Is it a generic concern (auth, retry, parsing, formatting, ID generation)?
  └─ Almost always → extract. These are the canonical reusable sub-workflows.

Is it >5 nodes and conceptually one thing?
  └─ Probably extract, even if reuse isn't certain. It's better isolated.

Is it one HTTP call with no logic around it?
  └─ Don't. A sub-workflow that's just trigger → HTTP → return adds a boundary
     for nothing.

Is it tightly coupled to this one caller's data shape?
  └─ Don't extract yet — fix the data shape first, or you just relocate the coupling.

As razões para extrair vão além da reutilização:

• Legibilidade. O chamador mostra um nó ("Analisar data") em vez de cinco.
• Testabilidade. Execute o sub-workflow sozinho com entrada fixada (n8n_test_workflow).
• Substituibilidade. Troque a implementação sem propagar para os chamadores.

Um workflow de 20 nós é bom se for majoritariamente uma sequência linear de chamadas de Executar Workflow e decisões — cada nó tem um propósito e você inspeciona uma seção abrindo o sub-workflow que ele chama. Um workflow de 20 nós de transformações inline não é bom. Se o seu tem 15+ nós e não é majoritariamente chamadas de sub-workflow e ramificações, extraia mais.

…