Fluxo de aprovação humana no n8n com uma API compatível com OpenAI e validação por JSON Schema

A decisão: aprove a ação, não apenas a extração

Para faturas, tickets de suporte, formulários e solicitações recebidas, a parte arriscada muitas vezes não é extrair os campos. É o que acontece depois: criar um registro de cliente, alterar um status, enviar uma mensagem externa ou excluir dados.

Por isso, um projeto robusto no n8n usa três etapas de controle:

1. Extração: uma API compatível com OpenAI retorna dados estruturados.
2. Validação: o n8n verifica se os dados estão em conformidade com um JSON Schema.
3. Aprovação: um AI Agent do n8n só pode chamar uma ferramenta consequente depois que uma pessoa a aprovar.

Isso impede que dados malformados cheguem ao revisor e mantém a execução aprovada separada da saída do modelo.

O OneMux oferece acesso a modelos de IA líderes por meio de uma única API compatível com OpenAI. Você pode usá-lo como rota de acesso ao modelo se o endpoint e o modelo selecionado documentarem suporte ao formato da solicitação e aos parâmetros exigidos pela sua configuração do n8n. Não se afirma aqui que a integração entre OneMux e n8n tenha sido testada.

Pré-requisitos

Você precisa de:

• Uma instância do n8n com acesso aos nós HTTP Request, Code e, quando aplicável, AI Agent.
• Um canal de aprovação compatível com sua configuração do n8n, como n8n Chat, Slack, Telegram, e-mail ou outro canal documentado.
• Acesso a uma API compatível com OpenAI. Se usar o OneMux, comece pelo guia de início rápido do OneMux e confirme o endpoint atual, o método de autenticação, os identificadores dos modelos e os parâmetros de solicitação compatíveis na documentação do OneMux.
• Um JSON Schema que descreva o objeto que você deseja extrair.
• Uma ferramenta de destino, como uma atualização de CRM ou uma ação de envio de mensagens, que não deve ser executada sem revisão humana.

Não presuma que todo endpoint compatível com OpenAI ofereça suporte a todos os recursos de saída estruturada. Verifique o suporte a response_format, JSON Schema, chamadas de ferramentas e ao modelo específico que você selecionar. O diretório de modelos do OneMux pode ajudar você a analisar as opções de modelos disponíveis, mas, por si só, não comprova o suporte a uma configuração específica de nó do n8n.

Fluxo de trabalho recomendado no n8n

Um fluxo prático pode usar estes nós:

1. Webhook ou outro gatilho recebe o texto de origem.
2. HTTP Request envia o texto ao endpoint do modelo compatível.
3. Code analisa e valida o objeto retornado.
4. IF encaminha resultados inválidos para um caminho de erro ou correção manual.
5. AI Agent recebe o objeto validado e tem acesso a uma ferramenta consequente.
6. Revisão humana pausa o fluxo antes da execução dessa ferramenta.
7. Ferramenta aprovada grava o registro ou envia a mensagem.

A solicitação de extração deve pedir apenas os campos necessários ao seu fluxo. Um exemplo compacto de schema para uma solicitação de suporte poderia ser:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "customer_email"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1
    },
    "customer_email": {
      "type": "string",
      "format": "email"
    }
  }
}

Configure a solicitação compatível com OpenAI

No nó HTTP Request, use a URL base e as instruções de autenticação da documentação do provedor. Não defina uma URL específica do provedor sem verificá-la para sua conta e região.

O formato de solicitação abaixo é ilustrativo. A aceitação de response_format e de sua estrutura JSON Schema depende do endpoint, do modelo e da configuração do n8n escolhidos.

{
  "model": "YOUR_DOCUMENTED_MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Extract the requested fields. Do not guess missing values. Return only an object matching the supplied schema."
    },
    {
      "role": "user",
      "content": "{{$json.source_text}}"
    }
  ],
  "temperature": 0,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_request",
      "strict": true,
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["category", "priority", "summary", "customer_email"],
        "properties": {
          "category": {"type": "string"},
          "priority": {"type": "string"},
          "summary": {"type": "string"},
          "customer_email": {"type": "string"}
        }
      }
    }
  }
}

O exemplo usa deliberadamente um ID de modelo fictício. Selecione um modelo documentado como compatível com o endpoint escolhido. Se a saída estrita por JSON Schema não estiver disponível, use um modo JSON compatível somente se o seu caminho de validação puder rejeitar com segurança respostas que não estejam em conformidade. O modo JSON, por si só, não equivale à validação por schema.

Valide a resposta antes da execução

As respostas dos provedores podem colocar o conteúdo gerado em campos diferentes. Inspecione uma resposta real no n8n antes de escrever o parser. O nó Code a seguir pressupõe que o modelo retornou uma string JSON em message.content; ajuste o caminho para corresponder à resposta que você realmente receber.

const raw = $json.choices?.[0]?.message?.content;

if (typeof raw !== 'string') {
  throw new Error('Model response did not contain message.content as a string');
}

let extracted;
try {
  extracted = JSON.parse(raw);
} catch (error) {
  throw new Error('Model returned invalid JSON');
}

const required = ['category', 'priority', 'summary', 'customer_email'];
const missing = required.filter((key) => extracted[key] === undefined || extracted[key] === '');

const validCategory = ['billing', 'technical', 'account', 'other'].includes(extracted.category);
const validPriority = ['low', 'normal', 'high', 'urgent'].includes(extracted.priority);
const validEmail = typeof extracted.customer_email === 'string' &&
  /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(extracted.customer_email);

if (missing.length || !validCategory || !validPriority || !validEmail) {
  throw new Error('Extracted object failed application validation');
}

return [{ json: { extracted } }];

Para uso em produção, substitua esta verificação simples por um validador de JSON Schema mantido, quando sua implantação do n8n permitir. O schema da solicitação e o schema aplicado na validação devem ser versionados em conjunto. Adicione uma versão do schema à saída se os sistemas posteriores precisarem distinguir revisões.

Adicione aprovação humana à ferramenta do AI Agent

Use o objeto validado como contexto para um AI Agent. Dê ao Agent uma ferramenta com escopo restrito, como CreateSupportTicket, em vez de acesso amplo ao banco de dados. Configure a revisão humana para essa ferramenta selecionada no painel Tools do AI Agent.

A documentação do n8n afirma que um fluxo é pausado quando um Agent tenta usar uma ferramenta que exige revisão. Um revisor pode aprovar a chamada, permitindo que a ferramenta seja executada com a entrada proposta, ou recusá-la, cancelando a ação. O n8n oferece suporte a vários canais de aprovação, incluindo sua interface de chat integrada e integrações como Slack, Telegram, Discord, Teams, e-mail, WhatsApp, Google Chat e e-mail do Outlook. Consulte a documentação oficial do n8n sobre human-in-the-loop para ver as etapas atuais de configuração e os detalhes dos canais.

Uma mensagem de aprovação útil deve apresentar a ação e os parâmetros propostos:

The AI wants to use {{ $tool.name }} with the following parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

A documentação de origem identifica $tool.name e $tool.parameters para este contexto de revisão. Mantenha a mensagem legível e inclua a solicitação original ou uma referência ao ticket quando os revisores precisarem de contexto adicional.

O prompt de sistema do seu Agent também deve explicar o comportamento da revisão:

The CreateSupportTicket tool requires human approval. If approval is denied, do not retry automatically. Tell the user that the action was not completed and explain what information or correction is needed.

Limitações e solução de problemas

O modelo retorna Markdown ou texto adicional

Verifique se o endpoint oferece suporte aos parâmetros de saída estruturada enviados. Caso não ofereça, remova os parâmetros incompatíveis, torne a instrução mais específica e mantenha a validação no nó Code como uma barreira obrigatória. Nunca envie um objeto não validado para a ferramenta de gravação.

O n8n não encontra o campo de resposta esperado

Inspecione a saída do HTTP Request e atualize o parser. APIs compatíveis com OpenAI podem compartilhar convenções de solicitação, mas diferir nos detalhes da resposta e nos parâmetros compatíveis.

A solicitação de aprovação é vaga demais

Use uma ferramenta com escopo restrito e inclua $tool.name e $tool.parameters na mensagem de aprovação. Não peça a um revisor que aprove uma instrução opaca, como “processe esta solicitação”.

Uma chamada de ferramenta recusada causa um loop

Adicione um comportamento explícito para recusas ao prompt de sistema do Agent e configure o fluxo para que uma recusa encerre o caminho da ação ou encaminhe para esclarecimento. A documentação do n8n recomenda explicar quais ferramentas exigem aprovação e como o Agent deve responder à rejeição.

Os revisores aprovam dados incorretos

A validade do schema não comprova a correção semântica. Mostre juntos o trecho da fonte, os campos extraídos e a ação pretendida. Em fluxos de alto impacto, exija que um revisor confirme independentemente os campos sensíveis.

Conclusão

O padrão mais seguro do n8n para extração estruturada não é “deixar o modelo gravar diretamente”. Extraia para um objeto restrito, valide-o e coloque a aprovação humana diante da ferramenta que altera o mundo externo. Uma API compatível com OpenAI pode simplificar o acesso aos modelos, enquanto o n8n oferece controles de orquestração e aprovação. Com o OneMux, use o endpoint compatível e os parâmetros do modelo documentados, verifique a configuração em seu próprio ambiente e trate recursos de saída estruturada não compatíveis como motivo para interromper o fluxo ou recorrer a um caminho de resposta validado separadamente.