Crea un flujo de Q&A de documentos en n8n con aprobación humana y una API compatible con OpenAI

La decisión: ¿dónde debe producirse la aprobación?

Para responder preguntas sobre documentos, no añadas aprobación humana únicamente porque haya un modelo de IA. Añádela en el punto en el que el flujo pueda acceder a material sensible o publicar una respuesta que necesite revisión.

Un diseño útil en n8n es:

1. Recibir una pregunta.
2. Pedir a un AI Agent que prepare una solicitud de búsqueda de documentos.
3. Pausar el flujo para obtener aprobación humana antes de ejecutar la herramienta de búsqueda cuando el corpus sea sensible, la consulta pueda exponer material restringido o la búsqueda tenga un coste operativo.
4. Recuperar fragmentos con metadatos de origen.
5. Pedir al modelo que responda únicamente a partir de esos fragmentos.
6. Devolver una respuesta con referencias a las fuentes o enviar el borrador a una segunda etapa de aprobación antes de publicarlo.

Esto separa tres decisiones que suelen confundirse: si la pregunta es aceptable, si la acción de recuperación es aceptable y si la respuesta generada está lista para enviarse.

n8n documenta la revisión humana para herramientas específicas conectadas a un AI Agent. Cuando la revisión está habilitada, el flujo se pausa y un revisor puede aprobar o denegar la llamada a la herramienta propuesta. Consulta la documentación de n8n sobre human-in-the-loop para conocer el comportamiento compatible y los detalles de los canales de aprobación.

Requisitos previos

Necesitas:

• Un flujo de trabajo de n8n con un AI Agent y una conexión a un modelo.
• Una fuente de documentos consultable, como un almacén vectorial, una base de datos o un servicio de búsqueda interno. El conector exacto depende de la aplicación y no está establecido por la página de n8n citada.
• Una herramienta de recuperación que devuelva texto junto con metadatos del documento.
• Un canal de aprobación configurado en n8n. La documentación enumera Chat, Slack, Discord, Telegram, Microsoft Teams, Gmail, WhatsApp Business Cloud, Google Chat y Microsoft Outlook como canales disponibles.
• Acceso a un endpoint de API compatible con OpenAI. OneMux ofrece acceso a modelos de IA líderes mediante una única API compatible con OpenAI; usa la guía de inicio rápido de OneMux y la documentación de la API para consultar las instrucciones actuales sobre el endpoint y la autenticación.

La compatibilidad es condicional. Antes de conectar n8n, confirma que el endpoint seleccionado admite el formato de solicitud, el identificador del modelo, el método de autenticación, el comportamiento de streaming, las llamadas a herramientas y los parámetros que utiliza tu nodo de n8n o tu solicitud HTTP. Este artículo no afirma que se haya probado un modelo concreto de OneMux ni una configuración específica de n8n.

Estructura recomendada del flujo de trabajo en n8n

Crea el flujo como cinco etapas lógicas:

1. Captura y normalización de la pregunta

Usa el punto de entrada de n8n que elijas para recibir una pregunta y normalízala en un objeto pequeño que contenga la pregunta del usuario, el contexto del usuario o del espacio de trabajo y un filtro opcional de ámbito documental.

No introduzcas directamente texto de usuario sin restricciones en una instrucción del sistema. Conserva la pregunta como datos y define por separado el comportamiento del agente. Si el flujo admite límites por tenant o departamento, pásalos a la herramienta de recuperación como campos controlados, en lugar de permitir que el modelo los invente.

2. Añade una herramienta de búsqueda de documentos

Conecta una herramienta de búsqueda al AI Agent. Su entrada debe ser limitada y explícita, por ejemplo:

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

El resultado de búsqueda debe conservar suficientes metadatos para una cita ú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"
}

Los nombres de campo anteriores son un patrón de implementación, no una afirmación sobre un esquema obligatorio de n8n. Adáptalos al conector o servicio que utilices. La propiedad importante es la trazabilidad: el generador de respuestas debe recibir juntos el fragmento y su origen.

3. Añade revisión humana alrededor de la herramienta seleccionada

Abre el panel Tools del AI Agent, busca la sección Human review, elige un canal de aprobación y conecta la herramienta de búsqueda de documentos a ese paso de revisión. Configura las credenciales y los ajustes del canal seleccionado en n8n.

El mensaje dirigido al revisor puede mostrar la acción propuesta y sus parámetros. La documentación de n8n describe las variables $tool.name y $tool.parameters para este fin. Un mensaje práctico sería:

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.

Esto resulta especialmente útil cuando el revisor puede identificar un ámbito de riesgo, como una solicitud que parezca buscar documentos de otro equipo. Para la documentación pública habitual, exigir aprobación en cada búsqueda puede generar fricción innecesaria. En ese caso, mantén la recuperación automática y coloca la aprobación en una herramienta independiente que publique o envíe la respuesta final.

4. Conecta el endpoint de modelos compatible con OpenAI

Configura la capa de modelos utilizando el endpoint y las credenciales documentados por tu proveedor. Con OneMux, empieza por la guía de inicio rápido de OneMux, selecciona un modelo compatible con las capacidades que requiere tu nodo de n8n y verifica el identificador del modelo y los parámetros de la solicitud.

Una estructura de solicitud genérica podría ser la siguiente, pero es ilustrativa y no una receta probada para OneMux:

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?"}
    ]
  }'

Sustituye la URL de marcador de posición, la gestión de la clave y el ID del modelo por los valores de la documentación actual del proveedor. No expongas las credenciales en las exportaciones del flujo de trabajo ni en los mensajes de aprobación visibles para el usuario. Si el nodo de modelos de n8n espera un parámetro que el endpoint no admite, usa una configuración compatible o un diseño basado en HTTP Request únicamente cuando se cumplan tus requisitos de seguridad y análisis de respuestas.

5. Exige atribución en el prompt de respuesta

Proporciona al modelo los fragmentos recuperados dentro de un contexto claramente delimitado y exige una cita para cada afirmación sustancial. Por ejemplo:

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 }}

La sintaxis exacta de las expresiones depende de cómo los nodos anteriores de n8n estructuren los datos. Trata este prompt como un patrón, no como una exportación de flujo lista para usar.

Diseño de la aprobación: recuperación frente a publicación

Hay dos puntos de aprobación razonables:

También puedes usar ambos puntos en flujos de alto riesgo. La documentación de n8n indica que la revisión puede aplicarse a todas las herramientas conectadas a un AI Agent o solo a herramientas seleccionadas, lo que permite este diseño selectivo. También señala que la aprobación puede realizarse mediante un canal diferente al de la interacción principal; por ejemplo, un chat orientado al usuario puede combinarse con la aprobación del revisor en Slack.

Prompt del sistema y comportamiento ante denegaciones

Indica al agente qué herramientas requieren aprobación y qué significa una denegación. Si un revisor deniega la búsqueda, el agente no debe repetir silenciosamente la misma llamada con una redacción distinta ni afirmar que encontró evidencia. Debe explicar que la búsqueda solicitada no fue aprobada y ofrecer una alternativa más limitada y permitida cuando exista.

Una política concisa es:

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.

Esto sigue las directrices documentadas de n8n de incluir en el prompt del sistema el comportamiento de las herramientas y de la revisión humana para que el agente pueda gestionar adecuadamente las llamadas rechazadas.

Solución de problemas y limitaciones

La solicitud de aprobación no incluye contexto útil

Comprueba que las entradas de la herramienta utilicen campos explícitos y que el mensaje de revisión incluya $tool.name y $tool.parameters. Evita ocultar el ámbito importante dentro de una cadena opaca.

Faltan las citas

Inspecciona el resultado de recuperación antes de que llegue al modelo. Si un nodo de asignación elimina el título, la URL, la página, la sección o los identificadores del fragmento, el modelo no puede reconstruirlos de forma fiable. Indica también al modelo que rechace las afirmaciones no respaldadas.

El endpoint rechaza la solicitud

Verifica la URL base, la cabecera de autenticación, el ID del modelo, la compatibilidad con llamadas a herramientas, los límites de contexto y los nombres de los parámetros. Compatible con OpenAI no significa idéntico: la compatibilidad debe comprobarse tanto con el formato de solicitud de n8n como con la API documentada por el proveedor.

La denegación produce una respuesta extraña

Añade una política explícita para las denegaciones al prompt del sistema y prueba las rutas de aprobación y denegación. n8n documenta la aprobación y la cancelación como resultados distintos; tu flujo debe gestionar ambos, en lugar de asumir que la herramienta siempre se ejecuta.

El flujo de trabajo es demasiado lento

Usa revisión selectiva en lugar de aprobar todas las búsquedas de bajo riesgo. Mantén la aprobación para la recuperación o publicación de contenido sensible y mide el efecto operativo en tu propio entorno. No presupongas la velocidad del modelo, la calidad de recuperación ni la latencia de aprobación sin realizar pruebas.

Planificación de costes y operaciones

OneMux es relevante aquí como vía de acceso a modelos, no como sustituto de los controles de flujo de n8n. Revisa los precios actuales de OneMux antes de elegir un modelo y ten en cuenta el uso de entrada y salida, el volumen de recuperación, los intentos de aprobación repetidos y los posibles costes del servicio de búsqueda de documentos. El precio aplicable depende del modelo seleccionado y de las condiciones publicadas vigentes; este artículo no asigna una tarifa ni promete ahorros.

Para consultar el contexto de visibilidad del gasto y selección de modelos, explora el catálogo de modelos de OneMux. Condiciona la elección del modelo a las capacidades que realmente necesita tu flujo, especialmente la salida estructurada o las llamadas a herramientas.

Conclusión

Un flujo sólido de Q&A de documentos en n8n no es simplemente un agente conectado a un modelo. Es una cadena controlada: recuperar fragmentos autorizados, conservar sus metadatos, exigir revisión en el límite adecuado de la herramienta y generar una respuesta que cite únicamente la evidencia recibida.

Usa n8n para la orquestación y la aprobación humana, y evalúa OneMux como una vía práctica de acceso a modelos compatible con OpenAI cuando su endpoint y sus parámetros documentados coincidan con tu diseño. Empieza con un corpus pequeño, prueba las rutas aprobadas y denegadas, y trata las afirmaciones no respaldadas, las citas ausentes y los parámetros incompatibles como fallos del flujo, no como misterios del modelo.

Fuentes

• n8n: Human-in-the-loop for tools — fuente sobre el comportamiento de aprobación de herramientas, los canales de aprobación, las expresiones $tool y las directrices para gestionar denegaciones.
• Documentación de OneMux — documentación del proveedor sobre el uso actual de la API y los detalles de compatibilidad.
• Guía de inicio rápido de OneMux — punto de partida para configurar el endpoint y la autenticación.
• Precios de OneMux — referencia de precios actuales que conviene consultar antes del despliegue.