Structured Output Parser dans n8n : obtenir un JSON fiable en sortie d’un AI Agent

Un AI Agent n8n qui doit renvoyer {"categorie": "urgent", "score": 8} répond parfois Voici la classification demandée : {"categorie": "urgent", "score": 8}, ou enveloppe le JSON dans un bloc de code Markdown avec des triples backticks. Le node Set ou Switch placé juste après explose alors avec une erreur de parsing — pas parce que le modèle s’est trompé sur le fond, mais parce qu’il a habillé la bonne réponse d’une phrase de politesse. Le Structured Output Parser existe exactement pour ce problème : il force le format de sortie d’un LLM et refuse ce qui ne colle pas au schéma attendu.

Comment ça marche

Le Structured Output Parser est un sub-node qui se branche sur la connexion ai_outputParser d’un AI Agent ou d’un Basic LLM Chain. Deux effets combinés :

1. Il enrichit automatiquement le prompt envoyé au modèle avec des instructions de formatage précises (« réponds uniquement avec un objet JSON respectant ce schéma… ») — vous n’avez rien à écrire vous-même dans le message système.
2. Il valide la réponse du modèle contre le schéma défini. Si elle correspond, le JSON parsé remplace le texte brut en sortie du node. Si elle ne correspond pas, le node lève une erreur explicite plutôt que de laisser passer un texte inexploitable en aval.

Pour l’utiliser, il faut d’abord activer l’option « Require Specific Output Format » dans les paramètres du node racine (AI Agent ou Basic LLM Chain). C’est cette bascule qui fait apparaître le point de connexion ai_outputParser sur le node — sans elle, impossible de brancher un parser.

Étape 1 — Définir le schéma

Le node propose deux façons de spécifier la structure attendue :

• Generate From JSON Example : vous collez un exemple représentatif, et n8n en déduit le schéma. Le plus rapide pour démarrer :

{
  "categorie": "urgent",
  "score_priorite": 8,
  "resume": "Client mécontent réclamant un remboursement sous 48h"
}

• JSON Schema : vous écrivez le schéma vous-même, utile dès que vous avez besoin de contraintes précises — une énumération de valeurs autorisées, un champ optionnel, un minimum/maximum numérique :

{
  "type": "object",
  "properties": {
    "categorie": {
      "type": "string",
      "enum": ["urgent", "client", "administratif", "newsletter"]
    },
    "score_priorite": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "resume": { "type": "string" }
  },
  "required": ["categorie", "score_priorite", "resume"]
}

Le mode enum est particulièrement utile en aval d’un node Switch : il élimine par construction les variantes orthographiques (« Urgent » vs « urgent » vs « URGENT ») qui font échouer une correspondance exacte de branche.

Besoin d’un tableau d’objets plutôt qu’un seul objet (par exemple une liste de tickets extraits d’un même email) ? Le node voisin Item List Parser couvre ce cas précis, avec le même principe de schéma.

Étape 2 — Le piège des agents qui utilisent des outils

C’est le point que la documentation n8n signale explicitement, et qui piège une bonne partie des workflows : brancher un Structured Output Parser directement sur un AI Agent équipé d’outils (recherche, appel API, lecture de base) est peu fiable en pratique. L’agent alterne des étapes de raisonnement et d’appels d’outils avant sa réponse finale ; ce format intermédiaire ne se marie pas toujours bien avec la validation stricte du parser, et remonte des erreurs comme « Failed to parse agent steps » ou un parser tout simplement ignoré par le node.

Le patron qui fonctionne de façon fiable en production : laisser l’agent répondre librement, en texte naturel, avec ses outils. Puis faire relire cette réponse finale par un second node — un Basic LLM Chain dédié, lui, équipé du Structured Output Parser — dont le seul travail est de reformater le texte de l’agent en JSON conforme. Deux nodes, deux responsabilités : l’agent raisonne et agit, le chain de formatage structure. C’est plus verbeux qu’un seul node, mais nettement plus robuste — et cohérent avec la logique détaillée dans notre guide sur les outils personnalisés d’un AI Agent n8n.

Étape 3 — Auto-fixing Output Parser : rattraper les erreurs de formatage

Même avec un schéma bien écrit, un modèle oublie parfois une accolade fermante, ou glisse une virgule finale invalide. Plutôt que de faire échouer le workflow au premier écart, le node Auto-fixing Output Parser s’intercale : il enveloppe un Structured Output Parser existant et, en cas d’échec de validation, renvoie automatiquement la sortie fautive au LLM accompagnée du message d’erreur, en lui demandant de la corriger — puis revalide.

À retenir avant de l’activer partout par réflexe :

• Chaque correction consomme un appel LLM supplémentaire — un coût et une latence à ajouter dans le budget du workflow (voir notre guide pour suivre le coût des appels IA).
• C’est un filet de rattrapage pour des erreurs de formatage, pas pour des erreurs de contenu : si le modèle invente une catégorie hors de l’enum, l’Auto-fixing Parser peut corriger la syntaxe, mais ne corrige pas un raisonnement métier faux.

Les erreurs qui font perdre une soirée

• JSON emballé dans un bloc Markdown : le modèle répond ```json\n{...}\n``` au lieu du JSON brut. Le Structured Output Parser gère nativement la plupart de ces cas, mais un système message qui précise explicitement « réponds uniquement en JSON brut, sans bloc de code » réduit encore les échecs.
• Guillemets ou backticks piégés dans une valeur texte : un champ resume contenant lui-même des caractères JSON spéciaux non échappés casse le parsing. Demandez au modèle d’éviter les caractères spéciaux dans les champs texte libres, ou validez côté node Code en aval.
• {{ $json.champ }} qui renvoie toujours la même valeur : dans un sub-node comme le Structured Output Parser, une expression ne s’évalue qu’une fois, sur le premier item du lot — pas item par item comme sur un node racine. Si le schéma doit varier selon l’item, construisez-le en amont dans un node Code.
• Parser branché mais ignoré : vérifiez que « Require Specific Output Format » est bien coché sur le node racine — un parser connecté sans cette option activée n’est tout simplement pas pris en compte.

Où ça sert concrètement : le schéma réel d'un workflow FlowKit

Deux workflows du Pack Inbox IA (79 €) reposent sur ce node. Voici le schéma tel qu'il figure dans le fichier livré du workflow Tri d'emails par IA, node « Format de sortie », mode de schéma manuel :

{
  "type": "object",
  "properties": {
    "categorie": {
      "type": "string",
      "enum": ["urgent", "client", "administratif", "newsletter"],
      "description": "Catégorie unique de l'email"
    },
    "resume": {
      "type": "string",
      "description": "Résumé factuel de l'email en 1 à 2 phrases, en français"
    },
    "expediteur_important": {
      "type": "boolean",
      "description": "true si l'expéditeur est un client, partenaire, administration ou personne identifiée"
    }
  }
}

Trois choix à retenir, qui valent pour vos propres schémas :

• un enum plutôt qu'un texte libre pour la catégorie : le Switch qui suit compare des chaînes exactes, et « Urgent » ou « urgente » casseraient le routage. Le prompt répète d'ailleurs la consigne (« en minuscules, sans accent, sans variante ») ;
• une description par champ : c'est le seul endroit où le modèle apprend ce que vous attendez, elle fait partie du prompt ;
• un booléen pour une décision oui/non, plutôt qu'un « oui »/« non » textuel à reparser.

Le second workflow, Priorisation d'urgence des emails, applique le même principe avec un autre schéma : score (entier de 1 à 5, bornes minimum/maximum), raison et action_suggeree, tous trois requis. Les scores ≥ 4 déclenchent une alerte Slack, le reste part dans une file d'attente pour le digest.

La recherche va dans le même sens : Geng, Josifoski, Peyrard et West ont montré à EMNLP 2023 (« Grammar-Constrained Decoding for Structured NLP Tasks without Finetuning » — voir l'étude) que contraindre la sortie d'un modèle par une grammaire formelle améliore nettement les tâches de sortie structurée, sans réentraînement. Le Structured Output Parser n'impose pas une grammaire au décodage comme dans l'étude, mais il poursuit le même but côté workflow : un format qu'on vérifie au lieu de l'espérer.

Une fois ce verrou en place, le reste du workflow — Switch, écriture Supabase, notification Slack — peut faire une confiance totale au format de ce qui arrive en entrée. C’est ce genre de détail, invisible tant que ça marche et bloquant dès que ça casse en production, qui sépare un prototype IA d’un workflow qu’on peut laisser tourner sans surveillance. Si vous voulez vérifier que cette fiabilité tient dans la durée, notre guide sur les Evaluations n8n montre comment construire un jeu de test qui détecte une régression de format avant qu’un client ne la découvre à votre place. Et si ce que votre LLM lit provient de contrats ou de rapports, notre guide du RAG sur des PDF avec n8n couvre l'étage d'extraction en amont de ce parseur.