GuidesOneMux

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.

AI

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 null somente 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:

  1. Acionar e buscar: receba um documento ou registro e mantenha o identificador de origem.
  2. 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.
  3. Analisar e validar: confira se a resposta pode ser analisada e se cada campo atende aos tipos e às regras de negócio.
  4. 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.
  5. Confirmar: grave no destino somente após a validação e, quando necessário, a aprovação humana.
  6. 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 testeResultado esperadoCondição de aprovação
Fatura clara com todos os camposExtração válidaTodos os campos obrigatórios correspondem ao exemplo de teste e a validação é aprovada
Data da fatura ausenteInválido ou null explicitamente permitidoNenhuma data é inventada; a política configurada é seguida
Total contém texto em vez de númeroResultado inválidoO registro não chega à etapa de gravação
Dois totais plausíveis na páginaRevisão humanaNenhuma confirmação automática enquanto a ambiguidade persistir
Falha temporária na solicitaçãoNova tentativa limitadaAs tentativas param no limite configurado; a falha é registrada
Pessoa responsável rejeita uma atualização propostaSem gravaçãoA 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