Workflow n8n avec validation humaine, API compatible OpenAI et validation JSON Schema

Le choix : approuver l’action, pas seulement l’extraction

Pour les factures, tickets d’assistance, formulaires et demandes entrantes, l’extraction des champs n’est souvent pas l’étape la plus risquée. Le risque réside dans ce qui suit : créer une fiche client, modifier un statut, envoyer un message externe ou supprimer des données.

Un workflow n8n robuste repose donc sur trois étapes de contrôle :

1. Extraction : une API compatible OpenAI retourne des données structurées.
2. Validation : n8n vérifie que les données sont conformes à un JSON Schema.
3. Approbation : un AI Agent n8n ne peut appeler un outil aux conséquences importantes qu’après l’approbation d’une personne.

Cette approche évite de soumettre des données mal formées au réviseur et sépare l’exécution approuvée de la sortie du modèle.

OneMux donne accès à des modèles d’IA de premier plan via une API compatible OpenAI unique. Vous pouvez l’utiliser comme voie d’accès aux modèles si la documentation de l’endpoint et du modèle sélectionné confirme la prise en charge du format de requête et des paramètres nécessaires à votre configuration n8n. Cet article n’affirme pas que l’intégration entre OneMux et n8n a été testée.

Prérequis

Vous aurez besoin des éléments suivants :

• Une instance n8n donnant accès aux nœuds HTTP Request, Code et, le cas échéant, AI Agent.
• Un canal d’approbation pris en charge par votre configuration n8n, comme n8n Chat, Slack, Telegram, email ou un autre canal documenté.
• Un accès à une API compatible OpenAI. Si vous utilisez OneMux, commencez par le guide de démarrage rapide OneMux et vérifiez l’endpoint actuel, la méthode d’authentification, les identifiants de modèles et les paramètres de requête pris en charge dans la documentation OneMux.
• Un JSON Schema décrivant l’objet que vous souhaitez extraire.
• Un outil de destination, par exemple une action de mise à jour d’un CRM ou d’envoi de message, qui ne doit pas s’exécuter sans validation humaine.

Ne supposez pas que tous les endpoints compatibles OpenAI prennent en charge toutes les fonctionnalités de sortie structurée. Vérifiez la prise en charge de response_format, de JSON Schema, des appels d’outils et du modèle précis que vous sélectionnez. Le répertoire des modèles OneMux peut vous aider à examiner les modèles disponibles, mais il ne prouve pas à lui seul la prise en charge d’une configuration particulière de nœud n8n.

Workflow n8n recommandé

Un workflow pratique peut utiliser les nœuds suivants :

1. Webhook ou un autre déclencheur reçoit le texte source.
2. HTTP Request envoie le texte à l’endpoint du modèle compatible.
3. Code analyse et valide l’objet retourné.
4. IF dirige les résultats non valides vers un parcours d’erreur ou de correction manuelle.
5. AI Agent reçoit l’objet validé et a accès à un outil aux conséquences importantes.
6. Human review met le workflow en pause avant l’exécution de cet outil.
7. Approved tool écrit l’enregistrement ou envoie le message.

La requête d’extraction ne doit demander que les champs nécessaires à votre workflow. Voici à quoi pourrait ressembler un exemple de schéma compact pour une demande d’assistance :

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

Configurer la requête compatible OpenAI

Dans le nœud HTTP Request, utilisez l’URL de base et les instructions d’authentification fournies dans la documentation du fournisseur. Ne codez pas en dur une URL propre à un fournisseur sans l’avoir vérifiée pour votre compte et votre région.

La structure de requête ci-dessous est donnée à titre d’exemple. L’acceptation de response_format et de sa structure JSON Schema dépend de l’endpoint, du modèle et de la configuration n8n choisis.

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

L’exemple utilise volontairement un identifiant de modèle fictif. Sélectionnez un modèle dont la documentation confirme la compatibilité avec l’endpoint choisi. Si la sortie JSON Schema stricte n’est pas disponible, n’utilisez un mode JSON pris en charge que si votre parcours de validation peut rejeter de manière fiable les réponses non conformes. Le mode JSON seul n’équivaut pas à une validation de schéma.

Valider la réponse avant l’exécution

Les réponses des fournisseurs peuvent placer le contenu généré dans différents champs. Examinez une réponse réelle dans n8n avant d’écrire l’analyseur. Le nœud Code suivant suppose que le modèle a retourné une chaîne JSON dans message.content ; adaptez le chemin à la réponse que vous recevez réellement.

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

Pour une utilisation en production, remplacez cette vérification légère par un validateur JSON Schema maintenu, lorsque votre déploiement n8n le permet. Le schéma de la requête et celui appliqué lors de la validation doivent être versionnés ensemble. Ajoutez une version de schéma à la sortie si les systèmes en aval doivent distinguer les révisions.

Ajouter une approbation humaine à l’outil de l’AI Agent

Utilisez l’objet validé comme contexte pour un AI Agent. Donnez à l’Agent un outil aux fonctions précisément délimitées, comme CreateSupportTicket, plutôt qu’un accès étendu à la base de données. Configurez la validation humaine pour cet outil dans le Tools Panel de l’AI Agent.

La documentation n8n indique qu’un workflow se met en pause lorsqu’un Agent tente d’utiliser un outil nécessitant une validation. Un réviseur peut approuver l’appel, ce qui permet à l’outil de s’exécuter avec les paramètres proposés, ou le refuser, ce qui annule l’action. n8n prend en charge plusieurs canaux d’approbation, dont son interface de chat intégrée et des intégrations telles que Slack, Telegram, Discord, Teams, email, WhatsApp, Google Chat et Outlook email. Consultez la documentation officielle n8n sur la validation humaine des outils pour connaître les étapes de configuration actuelles et les détails des canaux.

Un message d’approbation utile doit présenter l’action et les paramètres proposés :

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

La documentation source indique que $tool.name et $tool.parameters sont disponibles dans ce contexte de validation. Veillez à ce que le message reste lisible et incluez la demande d’origine ou une référence de ticket lorsque les réviseurs ont besoin de contexte supplémentaire.

Le prompt système de votre Agent doit également expliquer le comportement attendu lors de la validation :

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.

Limites et dépannage

Le modèle retourne du Markdown ou du texte supplémentaire

Vérifiez si l’endpoint prend en charge les paramètres de sortie structurée que vous avez envoyés. Si ce n’est pas le cas, supprimez les paramètres non pris en charge, rendez l’instruction plus précise et conservez la validation du nœud Code comme contrôle obligatoire. N’envoyez jamais un objet non validé à l’outil d’écriture.

n8n ne trouve pas le champ de réponse attendu

Examinez la sortie de HTTP Request et mettez à jour l’analyseur. Les API compatibles OpenAI peuvent partager des conventions de requête tout en différant dans les détails de leurs réponses et les paramètres pris en charge.

La demande d’approbation est trop vague

Utilisez un outil au périmètre limité et incluez $tool.name ainsi que $tool.parameters dans le message d’approbation. Ne demandez pas à un réviseur d’approuver une instruction opaque comme « traiter cette demande ».

Un appel d’outil refusé provoque une boucle

Ajoutez au prompt système de l’Agent un comportement explicite en cas de refus et configurez le workflow pour que ce refus mette fin au parcours d’action ou le dirige vers une demande de clarification. La documentation n8n recommande d’expliquer quels outils nécessitent une approbation et comment l’Agent doit réagir à un refus.

Les réviseurs approuvent des données incorrectes

La validité du schéma ne prouve pas l’exactitude sémantique. Présentez ensemble l’extrait source, les champs extraits et l’action envisagée. Pour les workflows à fort impact, demandez à un réviseur de confirmer indépendamment les champs sensibles.

Conclusion

Pour l’extraction structurée avec n8n, le modèle le plus sûr n’est pas de « laisser le modèle écrire directement ». Extrayez les données dans un objet contraint, validez-le, puis placez une approbation humaine avant l’outil qui agit sur le monde extérieur. Une API compatible OpenAI peut simplifier l’accès aux modèles, tandis que n8n fournit les contrôles d’orchestration et d’approbation. Avec OneMux, utilisez l’endpoint compatible et les paramètres de modèle documentés, vérifiez la configuration dans votre propre environnement et considérez toute fonctionnalité de sortie structurée non prise en charge comme une raison d’arrêter le processus ou de recourir à un parcours de réponse validé séparément.