Crie um fluxo de extração de dados repetível no n8n, com validação, novas tentativas e revisão humana
Configure um fluxo de extração no n8n que valide dados estruturados, tente novamente em caso de falhas temporárias, encaminhe registros incertos para revisão e possa ser avaliado com casos de teste fixos.
Resumo · TL;DR
Separe a extração, a validação e os efeitos colaterais no n8n. Valide cada resultado com base em um contrato explícito, tente novamente apenas em falhas recuperáveis e dentro de um limite fixo, e encaminhe registros incertos ou com consequências importantes para uma pessoa antes de confirmá-los.
Principais pontos
- Trate o resultado da extração como entrada não confiável até que passe pelas verificações de esquema e regras de negócio.
- Defina um limite de novas tentativas e diferencie erros temporários de resultados inválidos do modelo.
- Use a revisão humana para registros ambíguos ou ações com consequências importantes; mostre aos revisores exatamente os valores propostos.
- Mantenha um conjunto fixo de testes com resultados esperados e critérios explícitos de aprovação para comparar alterações de forma consistente.
Nesta página (7)
Um fluxo de extração no n8n é mais confiável quando inclui três etapas distintas: validação de esquema, recuperação limitada e revisão humana. Não encaminhe uma resposta gerada por IA diretamente para uma atualização de banco de dados ou mensagem externa. Primeiro, verifique se ela tem o formato esperado e, em seguida, determine se é seguro processá-la automaticamente.
Este projeto é ilustrativo, não uma exportação de fluxo testada. Os nomes dos nós e as opções disponíveis podem variar conforme a versão do n8n. O guia oficial do n8n documenta a aprovação humana para ferramentas selecionadas conectadas a um AI Agent; ele não descreve uma etapa de aprovação de uso geral para todos os registros extraídos. n8n: Human-in-the-loop for tools.
Comece com um contrato de extração bem definido
Escolha um tipo de registro e defina exatamente o que os nós seguintes precisam. Por exemplo, a extração de campos de uma fatura poderia gerar:
{
"invoice_number": "INV-1042",
"invoice_date": "2025-02-14",
"total": 128.50,
"currency": "USD"
}
Decida se cada campo é obrigatório, quais tipos são permitidos e como representar valores ausentes ou incertos. Evite usar um campo vago como notes em vez de um contrato confiável. Para este exemplo, as regras poderiam ser:
invoice_number: string não vazia.invoice_date: data ISO válida (YYYY-MM-DD).total: número finito maior ou igual a zero.currency: três letras maiúsculas.- Valores desconhecidos: use
nullsomente se o contrato permitir; nunca adivinhe.
Estas são regras de negócio ilustrativas, não requisitos impostos pelo n8n. Defina regras adequadas aos seus documentos de origem e ao sistema de destino.
Crie o fluxo em etapas separadas
Um fluxo prático pode seguir esta sequência:
- Acionar e buscar: receba um documento ou registro e mantenha o identificador de origem.
- Extrair: peça à etapa de extração escolhida apenas os campos definidos no contrato. Exija uma saída estruturada se o nó ou modelo selecionado for compatível, mas valide o resultado por conta própria mesmo assim.
- Analisar e validar: confira se a resposta pode ser analisada e se cada campo atende aos tipos e às regras de negócio.
- Direcionar: encaminhe os registros válidos e de baixo risco. Envie os registros inválidos ou ambíguos para revisão. Trate separadamente os erros temporários de serviço.
- Confirmar: grave no destino somente após a validação e, quando necessário, a aprovação humana.
- Registrar o resultado: armazene o identificador de origem, o resultado extraído, os erros de validação, o número de tentativas e a decisão final. Evite registrar o conteúdo sensível dos documentos, a menos que sua política de retenção permita isso.
Um nó Code de validação pode executar verificações básicas após a análise. Adapte a propriedade de entrada e a política para valores nulos aos nós anteriores:
const item = $input.first().json;
const data = item.extraction; // Set this to the parsed extraction object.
const errors = [];
if (!data || typeof data !== 'object' || Array.isArray(data)) {
errors.push('Extraction must be a JSON object');
} else {
if (typeof data.invoice_number !== 'string' || !data.invoice_number.trim()) {
errors.push('invoice_number must be a non-empty string');
}
if (typeof data.invoice_date !== 'string' ||
!/^\d{4}-\d{2}-\d{2}$/.test(data.invoice_date) ||
Number.isNaN(Date.parse(`${data.invoice_date}T00:00:00Z`))) {
errors.push('invoice_date must be a valid YYYY-MM-DD date');
}
if (typeof data.total !== 'number' || !Number.isFinite(data.total) || data.total < 0) {
errors.push('total must be a finite, non-negative number');
}
if (typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)) {
errors.push('currency must be three uppercase letters');
}
}
return [{ json: { ...item, valid: errors.length === 0, validation_errors: errors } }];
Isso verifica o formato e restrições simples, mas não confirma se o valor da fatura está factualmente correto. Mesmo um valor bem formatado, mas lido incorretamente, exige comparação com a fonte, uma política de confiança ou verificação humana.
Tente novamente diante das falhas certas — e saiba quando parar
Defina um limite pequeno e explícito de novas tentativas para falhas provavelmente temporárias, como um limite de requisições ou um erro temporário de conexão. Use as configurações de novas tentativas do nó, quando disponíveis, ou crie um ciclo controlado com contador de tentativas e intervalo de espera. Antes de depender de uma configuração específica, confirme como sua versão do n8n trata erros e novas tentativas.
Não tente novamente às cegas diante de uma falha de esquema como se fosse um problema de rede. Uma tentativa limitada de correção pode ser útil — por exemplo, pedir à etapa de extração que retorne os mesmos campos como JSON válido —, mas contabilize-a em um limite separado e visível. Se a resposta continuar inválida, encaminhe-a para revisão ou marque-a como falha. Nunca permita um ciclo sem limite.
Mantenha resultados distintos, como retryable_error, invalid_output e needs_review. Isso facilita o diagnóstico das execuções do fluxo e evita que um registro inválido seja confundido com uma extração bem-sucedida.
Envolva as pessoas no momento certo da decisão
Para revisar um registro, envie à pessoa responsável a referência à fonte, os valores propostos, os avisos de validação e opções claras para aprovar, editar ou rejeitar. Garanta que o fluxo aguarde uma decisão antes de gravar o registro e defina o que acontece em caso de tempo limite ou rejeição. O desenho específico para aguardar e retomar depende do canal de revisão e dos nós do n8n usados.
O recurso documentado de revisão humana do AI Agent no n8n funciona de outra forma: ferramentas selecionadas podem exigir aprovação antes de o agente executá-las. O fluxo é pausado e a pessoa responsável pode aprovar ou negar a chamada de ferramenta proposta; ela vê a ferramenta e seus parâmetros. O guia lista canais como Slack, Telegram e n8n Chat, e informa que $tool.name e $tool.parameters podem ser usados para fornecer contexto. Configure o prompt do sistema para explicar o significado de uma recusa e como o agente deve responder. Use esse recurso quando o agente estiver prestes a realizar uma ação, como modificar um registro — não como substituto da validação dos campos extraídos. Consulte o guia oficial de configuração.
Torne a avaliação repetível com casos fixos
Crie um pequeno conjunto de exemplos de teste que inclua entradas comuns, malformadas e ambíguas. Para cada caso, registre os campos esperados, o resultado de validação esperado e se uma pessoa deve analisá-lo. Execute os mesmos casos sempre que alterar o prompt, o esquema, a lógica de análise ou a configuração do modelo.
| Caso de teste | Resultado esperado | Condição de aprovação |
|---|---|---|
| Fatura clara com todos os campos | Extração válida | Todos os campos obrigatórios correspondem ao exemplo de teste e a validação é aprovada |
| Data da fatura ausente | Inválido ou null explicitamente permitido | Nenhuma data é inventada; a política configurada é seguida |
| Total contém texto em vez de número | Resultado inválido | O registro não chega à etapa de gravação |
| Dois totais plausíveis na página | Revisão humana | Nenhuma confirmação automática enquanto a ambiguidade persistir |
| Falha temporária na solicitação | Nova tentativa limitada | As tentativas param no limite configurado; a falha é registrada |
| Pessoa responsável rejeita uma atualização proposta | Sem gravação | A rejeição é registrada e o fluxo segue o caminho definido para recusas |
Defina os limites antes de executar os testes: número máximo de tentativas, campos que podem ser nulos, erros que exigem revisão e condições que impedem uma gravação. Informe os resultados de correspondência exata por campo e contabilize os casos inválidos, revisados, rejeitados e com falha. Um pequeno conjunto de exemplos é uma verificação de regressão, não uma prova de que a extração funcionará com todos os tipos de documento.
Lista de verificação para solução de problemas
- O JSON válido ainda falha: confira se o analisador retorna um objeto ou uma string JSON e verifique se a validação lê a propriedade correta.
- Valores incorretos são aceitos: adicione regras de negócio e verificações baseadas na fonte; os tipos JSON, por si só, não comprovam a exatidão factual.
- As novas tentativas repetem a mesma falha: separe erros temporários de erros determinísticos de esquema e limite o número de tentativas.
- As pessoas responsáveis não conseguem decidir: inclua a referência à fonte e todos os valores propostos, e deixe explícitas as decisões disponíveis.
- Uma ação rejeitada é executada mesmo assim: condicione a gravação ao resultado da aprovação e teste a rejeição como um exemplo separado.
- Os resultados mudam entre execuções: mantenha fixos as entradas, o prompt, o esquema e os critérios de avaliação; registre as alterações relevantes na configuração do fluxo.
Conclusão
No n8n, a confiabilidade depende de controlar o que acontece depois da extração: valide com base em um contrato bem definido, tente novamente apenas dentro de um limite fixo e exija julgamento humano quando o registro for ambíguo ou a ação tiver consequências importantes. Um conjunto fixo de testes torna esses controles observáveis e repetíveis.
Perguntas frequentes
O recurso de revisão humana do AI Agent no n8n valida os dados extraídos?
Não. O recurso documentado pausa chamadas de ferramentas selecionadas do AI Agent para aprovação ou recusa. Valide os campos extraídos separadamente antes de armazená-los ou agir com base neles.
Devo tentar novamente quando a saída do modelo é inválida?
Não como se fosse um erro temporário. Você pode permitir uma tentativa limitada de correção, mas mantenha-a separada das novas tentativas para falhas temporárias de serviço e encaminhe resultados persistentemente inválidos para revisão ou tratamento de falha.
O que uma avaliação de extração deve testar?
Use exemplos fixos que cubram registros válidos, campos ausentes ou malformados, valores de origem ambíguos, erros que permitem nova tentativa e rejeições de revisores. Defina os resultados esperados e as condições de aprovação antes de executar os testes.
Um fluxo de extração pode gravar dados diretamente após uma validação de esquema bem-sucedida?
Somente se a validade do esquema for suficiente para o caso de uso. Um resultado pode ter os tipos corretos e ainda estar factualmente errado, portanto registros ambíguos ou com consequências importantes podem exigir verificações na fonte ou revisão humana.
Artigos relacionados
Guides
Crie um fluxo de extração de dados recuperável no n8n
Projete um fluxo de extração no n8n que valide registros, tente novamente após falhas transitórias e encaminhe exceções para revisão humana sem gerar gravações duplicadas.
Guides
Crie um fluxo de extração de dados no n8n com atenção à privacidade
Projete um fluxo de extração no n8n que valide saídas estruturadas, trate falhas com segurança e encaminhe ações sensíveis para revisão humana.
Guides
Crie um fluxo confiável de extração de dados no n8n com validação de JSON Schema
Projete um pipeline de extração no n8n que valide saídas estruturadas de modelos, repita tentativas em caso de falhas temporárias e encaminhe registros incertos ou inválidos para revisão humana.
Guides
Crie um fluxo de trabalho confiável no n8n para alterações em repositórios, validação e revisão humana
Saiba como criar um fluxo no n8n que extrai informações estruturadas de alterações em repositórios, valida os resultados, tenta novamente em caso de falhas temporárias, verifica os testes e encaminha ações de risco para revisão humana.