Crie um fluxo de perguntas e respostas sobre documentos no n8n, com aprovação humana e uma API compatível com OpenAI

A decisão: em que ponto a aprovação deve acontecer?

Para perguntas e respostas sobre documentos, não adicione aprovação humana apenas porque há um modelo de IA envolvido. Inclua-a no ponto em que o fluxo de trabalho possa acessar material sensível ou publicar uma resposta que precise de revisão.

Um fluxo útil no n8n segue estas etapas:

1. Receber uma pergunta.
2. Pedir a um AI Agent que prepare uma solicitação de busca de documentos.
3. Pausar para obter aprovação humana antes de executar a ferramenta de busca, caso o corpus seja sensível, a consulta possa expor material restrito ou a busca tenha custos operacionais.
4. Recuperar trechos com metadados de origem.
5. Pedir ao modelo que responda apenas com base nesses trechos.
6. Retornar uma resposta com referências às fontes ou encaminhar o rascunho para uma segunda etapa de aprovação antes da publicação.

Isso separa três decisões que muitas vezes são confundidas: se a pergunta é aceitável, se a ação de recuperação é aceitável e se a resposta gerada está pronta para ser enviada.

A documentação do n8n descreve a revisão humana para ferramentas específicas conectadas a um AI Agent. Quando a revisão está ativada, o fluxo de trabalho é pausado e um revisor pode aprovar ou negar a chamada de ferramenta proposta. Consulte a documentação do n8n sobre human-in-the-loop para conhecer o comportamento compatível e os detalhes dos canais de aprovação.

Pré-requisitos

Você precisa de:

• Um fluxo de trabalho no n8n com um AI Agent e uma conexão com um modelo.
• Uma fonte de documentos pesquisável, como um banco de dados vetorial, um banco de dados ou um serviço interno de busca. O conector exato depende da aplicação e não é especificado na página do n8n citada.
• Uma ferramenta de recuperação que retorne texto junto com metadados do documento.
• Um canal de aprovação configurado no n8n. A documentação lista Chat, Slack, Discord, Telegram, Microsoft Teams, Gmail, WhatsApp Business Cloud, Google Chat e Microsoft Outlook como canais disponíveis.
• Acesso a um endpoint de API compatível com OpenAI. O OneMux oferece acesso a modelos de IA líderes por meio de uma única API compatível com OpenAI; consulte o guia de início rápido do OneMux e a documentação da API para obter as instruções atuais sobre endpoint e autenticação.

A compatibilidade é condicional. Antes de conectar o n8n, confirme se o endpoint selecionado oferece suporte ao formato da solicitação, ao identificador do modelo, ao método de autenticação, ao comportamento de streaming, à chamada de ferramentas e aos parâmetros usados pelo seu nó do n8n ou pela solicitação HTTP. Este artigo não afirma que um modelo específico do OneMux ou uma configuração específica do n8n tenha sido testado.

Estrutura recomendada para o fluxo de trabalho no n8n

Organize o fluxo em cinco etapas lógicas:

1. Receba e normalize a pergunta

Use o ponto de entrada do n8n que preferir para receber uma pergunta e normalize-a em um objeto pequeno que contenha a pergunta do usuário, o contexto do usuário ou do espaço de trabalho e um filtro opcional de escopo de documentos.

Não insira texto irrestrito do usuário diretamente em uma instrução de sistema. Mantenha a pergunta como dado e defina separadamente o comportamento do agente. Se o fluxo de trabalho permitir delimitar o acesso por locatário ou departamento, passe esses limites à ferramenta de recuperação como campos controlados, em vez de permitir que o modelo os invente.

2. Adicione uma ferramenta de busca de documentos

Conecte uma ferramenta de busca ao AI Agent. A entrada deve ser específica e bem delimitada, por exemplo:

{
  "query": "string",
  "document_scope": "string or controlled value",
  "max_results": "integer"
}

O resultado da busca deve preservar metadados suficientes para permitir uma citação útil:

{
  "text": "Approved passage from the document",
  "title": "Document title",
  "url": "Document URL or stable identifier",
  "page": "Page number when available",
  "section": "Section heading when available",
  "chunk_id": "Stable passage identifier"
}

Os nomes de campos acima são um padrão de implementação, não uma afirmação de que haja um esquema obrigatório do n8n. Adapte-os ao conector ou serviço que você utiliza. O importante é garantir a rastreabilidade: o gerador de respostas deve receber o trecho e sua origem juntos.

3. Insira a revisão humana na ferramenta selecionada

Abra o painel Tools do AI Agent, localize a seção Human review, escolha um canal de aprovação e conecte a ferramenta de busca de documentos a essa etapa de revisão. Configure no n8n as credenciais e definições do canal escolhido.

A mensagem enviada ao revisor pode mostrar a ação proposta e seus parâmetros. A documentação do n8n descreve as variáveis $tool.name e $tool.parameters para esse fim. Uma mensagem prática seria:

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

Approve only if the query and document scope are appropriate for this request.

Isso é mais útil quando o revisor consegue identificar um escopo arriscado, como uma solicitação que pareça buscar documentos de outra equipe. Para documentação pública comum, exigir aprovação em todas as buscas pode gerar atrito desnecessário. Nesse caso, mantenha a recuperação automática e solicite aprovação em uma ferramenta separada que publique ou envie a resposta final.

4. Conecte o endpoint do modelo compatível com OpenAI

Configure a camada do modelo usando o endpoint e as credenciais documentados pelo seu provedor. Com o OneMux, comece pelo guia de início rápido do OneMux, selecione um modelo compatível com os recursos exigidos pelo seu nó do n8n e verifique o identificador do modelo e os parâmetros da solicitação.

Um formato genérico de solicitação pode ser parecido com este, mas é apenas ilustrativo, não uma configuração do OneMux testada:

curl https://api.example-provider.invalid/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer only from supplied document passages."},
      {"role": "user", "content": "What does the document say about retention?"}
    ]
  }'

Substitua a URL, a gestão da chave e o ID do modelo de exemplo pelos valores indicados na documentação atual do provedor. Não exponha credenciais em exportações do fluxo de trabalho nem em mensagens de aprovação visíveis aos usuários. Se o nó de modelo do n8n exigir um parâmetro que o endpoint não aceite, use uma configuração compatível ou um modelo baseado em HTTP Request, mas somente se os requisitos de segurança e análise da resposta forem atendidos.

5. Exija atribuição de fontes no prompt de resposta

Forneça ao modelo os trechos recuperados em um contexto claramente delimitado e exija uma citação para cada afirmação substancial. Por exemplo:

You answer questions about the supplied documents.

Rules:
- Use only the passages in DOCUMENT_CONTEXT.
- If the passages do not support an answer, say that the documents do not establish it.
- Do not create titles, URLs, page numbers, or quotations.
- Cite each factual answer using the supplied title and page, section, URL, or chunk ID.
- Distinguish a direct statement from an inference.

DOCUMENT_CONTEXT:
{{ JSON.stringify($json.documents) }}

QUESTION:
{{ $json.question }}

A sintaxe exata das expressões depende da forma como os nós anteriores do n8n estruturam os dados. Trate este prompt como um padrão, não como uma exportação de fluxo pronta para uso.

Estratégia de aprovação: recuperação ou publicação

Há dois pontos de aprovação razoáveis:

Também é possível usar os dois pontos em fluxos de trabalho de alto risco. A documentação do n8n informa que a revisão pode se aplicar a todas as ferramentas conectadas a um AI Agent ou apenas às ferramentas selecionadas, o que permite essa estratégia seletiva. Também observa que a aprovação pode ocorrer por um canal diferente daquele da interação principal; por exemplo, um chat voltado ao usuário pode ser combinado com a aprovação do revisor no Slack.

Prompt de sistema e comportamento em caso de recusa

Informe ao agente quais ferramentas exigem aprovação e o que significa uma recusa. Se um revisor negar a busca, o agente não deve repetir a mesma chamada com outra formulação nem alegar que encontrou evidências. Deve explicar que a consulta solicitada não foi aprovada e, se houver uma alternativa permitida, oferecer uma opção mais específica.

Uma política concisa seria:

The document_search tool requires human approval. If it is denied, do not call it again for the same request. Tell the user that the lookup was not approved. Never answer from memory when document evidence is required.

Isso segue as orientações documentadas do n8n para incluir no prompt de sistema o comportamento das ferramentas e da revisão humana, permitindo que o agente lide adequadamente com chamadas recusadas.

Solução de problemas e limitações

A solicitação de aprovação não inclui contexto útil

Verifique se as entradas da ferramenta usam campos explícitos e se a mensagem de revisão inclui $tool.name e $tool.parameters. Não esconda o escopo importante em uma string opaca.

As citações estão ausentes

Inspecione a saída da recuperação antes de ela chegar ao modelo. Se um nó de mapeamento eliminar o título, a URL, a página, a seção ou os identificadores dos trechos, o modelo não poderá reconstruí-los de forma confiável. Instrua também o modelo a recusar afirmações sem suporte.

O endpoint rejeita a solicitação

Verifique a URL base, o cabeçalho de autenticação, o ID do modelo, o suporte à chamada de ferramentas, os limites de contexto e os nomes dos parâmetros. Compatibilidade com OpenAI não significa compatibilidade idêntica: é preciso comparar o formato da solicitação do n8n com a API documentada pelo provedor.

A recusa gera uma resposta inadequada

Adicione uma política explícita para recusas ao prompt de sistema e teste os caminhos de aprovação e recusa. A documentação do n8n descreve aprovação e cancelamento como resultados distintos; o fluxo de trabalho deve lidar com ambos, em vez de presumir que a ferramenta sempre será executada.

O fluxo de trabalho está lento demais

Use revisão seletiva em vez de exigir aprovação para toda busca de baixo risco. Reserve a aprovação para recuperações ou publicações sensíveis e avalie o impacto operacional no seu próprio ambiente. Não presuma a velocidade do modelo, a qualidade da recuperação nem o tempo de aprovação sem testar.

Planejamento de custos e operações

Neste contexto, o OneMux é uma opção de acesso a modelos, não um substituto dos controles de fluxo de trabalho do n8n. Consulte os preços atuais do OneMux antes de escolher um modelo e leve em conta o uso de entrada e saída, o volume de recuperação, as tentativas repetidas de aprovação e os custos de qualquer serviço de busca de documentos. O preço aplicável depende do modelo selecionado e dos termos publicados atualmente; este artigo não estabelece uma tarifa nem promete economia.

Para entender os gastos e ter contexto para a seleção de modelos, consulte o catálogo de modelos do OneMux. Escolha o modelo de acordo com os recursos de que o fluxo de trabalho realmente precisa, especialmente saída estruturada ou chamada de ferramentas.

Conclusão

Um fluxo de perguntas e respostas sobre documentos robusto no n8n não se resume a conectar um agente a um modelo. É uma cadeia controlada: recuperar trechos autorizados, preservar seus metadados, exigir revisão no ponto adequado da ferramenta e gerar uma resposta que cite apenas as evidências recebidas.

Use o n8n para orquestração e aprovação humana e avalie o OneMux como uma opção prática de acesso a modelos compatível com OpenAI quando o endpoint e os parâmetros documentados atenderem ao seu projeto. Comece com um corpus pequeno, teste os caminhos de aprovação e recusa e trate afirmações sem suporte, citações ausentes e parâmetros incompatíveis como falhas do fluxo de trabalho, não como mistérios do modelo.

Fontes

• n8n: Human-in-the-loop para ferramentas — fonte sobre o comportamento de aprovação de ferramentas, canais de aprovação, expressões $tool e orientações para lidar com recusas.
• Documentação do OneMux — documentação do provedor sobre o uso atual da API e detalhes de compatibilidade.
• Guia de início rápido do OneMux — ponto de partida para configurar o endpoint e a autenticação.
• Preços do OneMux — referência de preços atuais a consultar antes da implantação.