Flujo de aprobación humana en n8n con una API compatible con OpenAI y validación mediante JSON Schema

La decisión: aprobar la acción, no solo la extracción

En facturas, tickets de soporte, formularios y solicitudes entrantes, la parte arriesgada a menudo no es extraer los campos. Es lo que ocurre después: crear un registro de cliente, cambiar un estado, enviar un mensaje externo o eliminar datos.

Por eso, un diseño sólido en n8n utiliza tres controles:

1. Extracción: una API compatible con OpenAI devuelve datos estructurados.
2. Validación: n8n comprueba que los datos cumplen un JSON Schema.
3. Aprobación: un AI Agent de n8n puede llamar a una herramienta relevante solo después de que una persona lo apruebe.

Así, los datos con un formato incorrecto no llegan al revisor y la ejecución aprobada permanece separada de la salida del modelo.

OneMux proporciona acceso a modelos de IA líderes mediante una única API compatible con OpenAI. Puedes utilizarlo como ruta de acceso al modelo si el endpoint y el modelo seleccionado documentan compatibilidad con el formato de solicitud y los parámetros que requiere tu configuración de n8n. En este artículo no se afirma que la integración entre OneMux y n8n se haya probado.

Requisitos previos

Necesitas:

• Una instancia de n8n con acceso a los nodos HTTP Request, Code y, cuando corresponda, AI Agent.
• Un canal de aprobación compatible con tu configuración de n8n, como n8n Chat, Slack, Telegram, correo electrónico u otro canal documentado.
• Acceso a una API compatible con OpenAI. Si utilizas OneMux, empieza con la guía de inicio rápido de OneMux y confirma el endpoint actual, el método de autenticación, los identificadores de modelo y los parámetros de solicitud compatibles en la documentación de OneMux.
• Un JSON Schema que describa el objeto que quieres extraer.
• Una herramienta de destino, como una actualización de CRM o una acción para enviar mensajes, que no deba ejecutarse sin revisión humana.

No des por hecho que todos los endpoints compatibles con OpenAI admiten todas las funciones de salida estructurada. Verifica la compatibilidad con response_format, JSON Schema, llamadas a herramientas y el modelo concreto que selecciones. El directorio de modelos de OneMux puede ayudarte a revisar las opciones de modelos disponibles, pero por sí solo no demuestra la compatibilidad con una configuración específica de nodos de n8n.

Flujo de n8n recomendado

Un flujo práctico puede utilizar estos nodos:

1. Webhook u otro activador recibe el texto de origen.
2. HTTP Request envía el texto al endpoint del modelo compatible.
3. Code analiza y valida el objeto devuelto.
4. IF dirige los resultados no válidos a una ruta de error o corrección manual.
5. AI Agent recibe el objeto validado y tiene acceso a una herramienta relevante.
6. Revisión humana pausa el flujo antes de que se ejecute esa herramienta.
7. Herramienta aprobada escribe el registro o envía el mensaje.

La solicitud de extracción debe pedir únicamente los campos que necesita tu flujo de trabajo. Un ejemplo compacto de esquema para una solicitud de soporte podría ser el siguiente:

{
  "$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"
    }
  }
}

Configura la solicitud compatible con OpenAI

En el nodo HTTP Request, utiliza la URL base y las instrucciones de autenticación de la documentación del proveedor. No codifiques una URL específica del proveedor a menos que la hayas verificado para tu cuenta y región.

La estructura de solicitud siguiente es ilustrativa. La aceptación de response_format y de su estructura de JSON Schema depende del endpoint, el modelo y la configuración de n8n que elijas.

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

El ejemplo utiliza deliberadamente un ID de modelo de marcador de posición. Selecciona un modelo documentado como compatible con el endpoint que hayas elegido. Si no está disponible la salida estricta mediante JSON Schema, utiliza un modo JSON compatible solo si tu ruta de validación puede rechazar de forma segura las respuestas que no cumplan el esquema. El modo JSON por sí solo no equivale a la validación mediante esquema.

Valida la respuesta antes de la ejecución

Las respuestas de los proveedores pueden colocar el contenido generado en campos diferentes. Inspecciona una respuesta real en n8n antes de escribir el analizador. El siguiente nodo Code presupone que el modelo devolvió una cadena JSON en message.content; ajusta la ruta para que coincida con la respuesta que recibas realmente.

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 producción, sustituye esta comprobación ligera por un validador de JSON Schema mantenido, siempre que tu implementación de n8n lo permita. El esquema de la solicitud y el esquema aplicado durante la validación deben versionarse conjuntamente. Añade una versión del esquema a la salida si los sistemas posteriores necesitan distinguir entre revisiones.

Añade aprobación humana a la herramienta del AI Agent

Utiliza el objeto validado como contexto para un AI Agent. Proporciona al Agent una herramienta definida de forma limitada, como CreateSupportTicket, en lugar de un acceso amplio a la base de datos. Configura la revisión humana para esa herramienta seleccionada en el Tools Panel del AI Agent.

La documentación de n8n indica que el flujo se pausa cuando un Agent intenta utilizar una herramienta que requiere revisión. Un revisor puede aprobar la llamada, lo que permite que la herramienta se ejecute con la entrada propuesta, o rechazarla, cancelando la acción. n8n admite varios canales de aprobación, incluidos su interfaz de chat integrada e integraciones como Slack, Telegram, Discord, Teams, correo electrónico, WhatsApp, Google Chat y Outlook email. Consulta la documentación oficial de n8n sobre human-in-the-loop para conocer los pasos de configuración y los detalles de los canales actuales.

Un mensaje de aprobación útil debe mostrar la acción y los parámetros propuestos:

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

La documentación de origen identifica $tool.name y $tool.parameters para este contexto de revisión. Mantén el mensaje legible e incluye la solicitud original o una referencia al ticket cuando los revisores necesiten contexto adicional.

El prompt del sistema de tu Agent también debe explicar el comportamiento durante la revisión:

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.

Limitaciones y resolución de problemas

El modelo devuelve Markdown o texto adicional

Comprueba si el endpoint admite los parámetros de salida estructurada que has enviado. Si no los admite, elimina los parámetros no compatibles, refuerza la instrucción y mantén la validación del nodo Code como un control obligatorio. Nunca envíes un objeto no validado a la herramienta de escritura.

n8n no encuentra el campo de respuesta esperado

Inspecciona la salida de HTTP Request y actualiza el analizador. Las API compatibles con OpenAI pueden compartir convenciones de solicitud y, al mismo tiempo, diferir en los detalles de respuesta y los parámetros compatibles.

La solicitud de aprobación es demasiado vaga

Utiliza una herramienta con un alcance limitado e incluye $tool.name y $tool.parameters en el mensaje de aprobación. No pidas a un revisor que apruebe una instrucción opaca como «procesa esta solicitud».

Una llamada a una herramienta rechazada provoca un bucle

Añade un comportamiento explícito para los rechazos al prompt del sistema del Agent y configura el flujo para que un rechazo finalice la ruta de acción o la dirija a una solicitud de aclaración. La documentación de n8n recomienda explicar qué herramientas requieren aprobación y cómo debe responder el Agent ante un rechazo.

Los revisores aprueban datos incorrectos

La validez del esquema no demuestra la corrección semántica. Muestra juntos el fragmento de origen, los campos extraídos y la acción prevista. En flujos de alto impacto, exige que un revisor confirme de forma independiente los campos sensibles.

Conclusión

El patrón más seguro de n8n para la extracción estructurada no consiste en «dejar que el modelo escriba directamente». Extrae los datos a un objeto restringido, valídalo y coloca la aprobación humana delante de la herramienta que modifica el mundo exterior. Una API compatible con OpenAI puede simplificar el acceso a los modelos, mientras que n8n proporciona controles de orquestación y aprobación. Con OneMux, utiliza el endpoint compatible y los parámetros del modelo documentados, verifica la configuración en tu propio entorno y considera las funciones de salida estructurada no compatibles como un motivo para detenerte o recurrir a una ruta de respuesta validada por separado.