Qu’est-ce que Structured Output ? Pourquoi AI Agent en a besoin ? JSON Schema et JSON ordinaire

La spécification actuelle de JSON Schema est la version 2020-12. Ce détail suffit à rappeler qu’un schéma n’est pas une simple préférence de format : c’est une version de contrat que vos outils doivent comprendre et valider. La spécification officielle de JSON Schema distingue donc clairement la description des données et les données elles-mêmes. (json-schema.org)

Symptôme : votre modèle renvoie un JSON lisible, mais les champs changent, les types dérivent ou les outils reçoivent des paramètres inattendus. Solution la plus rapide : utilisez le JSON ordinaire pour une réponse destinée à être lue, le JSON mode pour une contrainte de syntaxe limitée, et Structured Output avec JSON Schema dès qu’un programme doit consommer la réponse de manière prévisible.

Qui doit lire cet article ?

Si vous débutez dans le développement d’applications d’IA, vous y trouverez la distinction entre trois notions souvent confondues. Si vous développez une API, une interface ou un workflow, vous pourrez choisir le niveau de contrainte adapté. Enfin, si vous concevez un AI Agent, l’objectif est de séparer clairement les paramètres d’outils, les états intermédiaires et la réponse finale.

Le vrai problème n’est pas le JSON, mais le contrat de consommation

Prenons une extraction de facture. Une consigne demande au modèle de retourner un objet JSON contenant un fournisseur, une date et un total. Le premier résultat peut ressembler à ceci :

{
  "supplier": "Atelier Sonore",
  "date": "2026-08-18",
  "total": 1280.50
}

Le deuxième résultat reste du JSON valide, mais modifie les conventions :

{
  "vendor_name": "Atelier Sonore",
  "invoice_date": "18 août 2026",
  "amount": "1 280,50 €"
}

Pour un lecteur humain, les deux objets sont compréhensibles. Pour votre base de données, votre interface ou votre automatisation, ils ne sont pas équivalents. Trois problèmes apparaissent immédiatement :

• Dérive des champs : supplier, vendor_name et provider peuvent désigner la même information sans être interchangeables dans votre code.
• Dérive des types : un montant numérique peut devenir une chaîne avec symbole monétaire, ce qui casse un calcul ou un tri.
• Dérive des valeurs : un statut libre comme paid, payé, completed ou settled complique les règles métier.

À cela s’ajoutent des coûts moins visibles. Votre équipe doit écrire des convertisseurs, maintenir des tests pour plusieurs variantes, traiter les réponses incomplètes et analyser des erreurs qui ne viennent pas forcément du modèle, mais du contrat implicite entre le modèle et votre application.

Dans un projet audio ou vidéo, le même problème se produit lorsqu’un AI Agent doit décrire un fichier média. Une réponse humaine peut indiquer qu’une piste est « probablement stéréo » ou que le fichier semble « suffisamment propre ». Une chaîne de postproduction, elle, attend plutôt des propriétés identifiables : nombre de canaux, durée, codec, fréquence d’échantillonnage, niveau de confiance et action recommandée. Le format ne suffit pas ; il faut une structure exploitable.

JSON ordinaire, JSON mode et Structured Output : que choisissez-vous ?

Le terme « JSON » décrit une syntaxe de données. Il autorise des objets, des tableaux, des chaînes, des nombres, des booléens et la valeur nulle, mais il ne dit pas à lui seul quels champs votre application doit recevoir.

Un JSON ordinaire peut être obtenu en demandant simplement au modèle de répondre avec un objet JSON. C’est souvent suffisant pour un prototype, une démonstration ou une réponse que vous inspecterez manuellement. En revanche, la consigne ne constitue pas un contrat de validation robuste.

Le JSON mode vise généralement à forcer une sortie syntaxiquement valide. Dans la documentation d’API, ce mode est présenté comme une ancienne méthode de génération d’objets JSON ; il ne remplace pas une définition précise des propriétés attendues. La référence officielle sur les formats de réponse JSON recommande l’usage d’un format fondé sur json<em>schema lorsque celui-ci est disponible. (platform.openai.com)

Structured Output ajoute un schéma à la génération. Le modèle ne reçoit plus seulement l’instruction « produis du JSON », mais une description des champs, des types, des valeurs possibles et parfois des contraintes supplémentaires. Certaines plateformes annoncent une adhérence stricte à un sous-ensemble de JSON Schema ; vous devez donc vérifier les mots-clés réellement pris en charge au lieu de supposer que toute la spécification est disponible.

Le point décisif est donc le consommateur. Si une personne lit la réponse, imposer un Schema peut ajouter de la complexité sans bénéfice. Si une base, un outil ou un composant logiciel la consomme, l’absence de contrat devient rapidement plus coûteuse que la contrainte.

Le JSON Schema est-il une donnée ou une règle ?

JSON Schema est lui-même écrit en JSON, mais il décrit une autre donnée. La documentation officielle de JSON Schema le présente comme un document qui décrit des valeurs JSON, tandis que l’objet envoyé ou reçu par votre application constitue l’instance à valider. (json-schema.org)

Vous pouvez y définir :

• un champ title de type chaîne ;
• un champ duration de type nombre ;
• une propriété tracks de type tableau ;
• une liste limitée par enum ;
• des propriétés obligatoires avec required ;
• l’acceptation ou le refus de propriétés supplémentaires ;
• des valeurs nulles lorsqu’un résultat est réellement inconnu.

Le Schema ne garantit donc pas que le modèle a correctement identifié la durée d’une vidéo. Il garantit seulement, selon le niveau de prise en charge de l’API et le contrôle effectué, que la réponse respecte la forme demandée. Cette distinction doit apparaître dans vos tests et dans vos messages d’erreur.

Première étape : réserver la contrainte aux données qui seront réellement consommées

Commencez par cartographier la sortie, avant de choisir la technologie.

1. Identifiez le lecteur de la réponse. Est-ce un utilisateur, une base de données, une file de messages, un composant d’interface ou un outil ?
2. Listez les champs indispensables. Séparez les propriétés nécessaires à l’exécution des informations seulement utiles à l’affichage.
3. Fixez les types et les unités. Une durée doit-elle être exprimée en secondes numériques, en millisecondes ou sous forme de texte ?
4. Définissez les valeurs indéterminées. Préférez une valeur nulle contrôlée à une invention silencieuse du modèle.
5. Écrivez les règles métier hors du Schema. Le Schema peut exiger un identifiant ou une valeur parmi plusieurs choix ; il ne sait pas si cet identifiant existe réellement dans votre système.
6. Validez la réponse côté serveur. Ne laissez pas le modèle décider seul qu’un objet est acceptable.
7. Versionnez le contrat. Un changement de propriété peut affecter une application mobile, un tableau de bord ou un workflow déjà déployé.
8. Préparez un retour lisible. Si la sortie structurée échoue, l’utilisateur doit recevoir une explication ou un texte de secours, pas uniquement une trace technique.

Pour une extraction de métadonnées vidéo, par exemple, vous pouvez demander format, duration<em>seconds, audio</em>channels et needs<em>transcoding. La valeur needs</em>transcoding: true ne doit toutefois déclencher aucune conversion avant que votre serveur ait vérifié le fichier, les droits d’accès, les limites de stockage et les règles du projet.

Pourquoi Tool Calling exige-t-il deux contrôles distincts ?

Dans un AI Agent, les paramètres d’outil doivent généralement être structurés, car le serveur doit savoir quel nom de fonction appeler et quels arguments lui transmettre. Les documentations officielles décrivent les paramètres d’outils à l’aide d’un objet JSON Schema, notamment pour définir les entrées attendues. La documentation officielle sur les outils et leurs schémas d’entrée illustre cette séparation entre le choix de l’outil, ses arguments et son exécution. (docs.anthropic.com)

Mais une structure correcte ne signifie pas qu’il faut exécuter l’action. Il faut distinguer :

1. Validation de forme : les champs sont présents et leurs types correspondent.
2. Validation métier : la ressource existe, l’état est compatible et les valeurs sont acceptables.
3. Validation d’autorisation : l’utilisateur, le rôle ou le service possède le droit d’effectuer l’action.
4. Validation opérationnelle : les limites de débit, le budget, la disponibilité et l’idempotence sont respectés.

Un modèle peut donc produire :

{
  "tool": "create_render_job",
  "project_id": "proj_784",
  "format": "prores",
  "duration_seconds": 720
}

Cet objet peut respecter votre Schema et rester dangereux ou inexécutable. Le projet peut ne pas appartenir à l’utilisateur, le format peut ne pas être autorisé ou la durée peut dépasser les limites de votre infrastructure. Structured Output réduit l’ambiguïté de transmission ; il ne remplace pas votre couche d’autorisation.

Attention : ne placez pas dans le Schema des données que le modèle ne devrait jamais contrôler, comme un rôle administrateur, une limite budgétaire finale ou une décision d’autorisation. Ces informations doivent venir de votre serveur et non de la sortie générée.

Comment construire une interface dynamique sans bloquer les évolutions ?

Les interfaces générées à partir de structures sont particulièrement intéressantes pour les formulaires de production, les fiches de projet, les cartes de montage ou les tableaux de suivi. Un AI Agent peut retourner une liste de composants, leurs libellés, leurs options et leurs valeurs initiales. Votre application transforme ensuite cette réponse en interface.

Le danger apparaît lors de la modification du contrat. Renommer thumbnail<em>url en preview</em>url, rendre obligatoire une propriété auparavant facultative ou supprimer une valeur d’énumération peut casser le client sans modifier une seule ligne de son code.

Conservez donc une version explicite du Schema, fournissez des valeurs par défaut et distinguez les champs obligatoires des champs décoratifs. Pour une interface, vous pouvez aussi prévoir un comportement de repli : si un composant inconnu est reçu, le client l’ignore et affiche le texte explicatif associé au lieu de bloquer toute la page.

Les plateformes ne prennent pas nécessairement en charge l’intégralité des mots-clés JSON Schema. La documentation officielle de l’API concernée doit être consultée avant de concevoir un contrat complexe ; par exemple, la documentation de sortie structurée de Gemini précise que son mode structuré utilise un sous-ensemble de JSON Schema et liste les types et propriétés supportés. (ai.google.dev)

Dans un Agent multi-étapes, la structure doit distinguer l’état et la réponse finale

Oui pour les événements que vos programmes doivent traiter, mais pas nécessairement pour chaque phrase destinée à l’utilisateur.

Un workflow multi-étapes peut produire plusieurs catégories de données :

• un identifiant d’appel d’outil ;
• le nom de l’outil sélectionné ;
• les arguments validés ;
• le résultat renvoyé par le service ;
• l’état courant du workflow ;
• l’action suivante ;
• une réponse finale lisible.

Les événements internes doivent être suffisamment structurés pour être journalisés, rejoués et corrélés. Un tool<em>call</em>id, par exemple, sert à associer une demande à son résultat. Un état comme waiting<em>for</em>approval doit être distingué de completed, même si le texte affiché à l’utilisateur reste naturel.

En revanche, vous n’avez pas besoin de transformer la totalité de l’explication en objet rigide. Vous pouvez retourner un contrat mixte :

{
  "status": "completed",
  "result": {
    "approved": false,
    "reason_code": "missing_source"
  },
  "message": "Le rendu ne peut pas démarrer, car la piste source est absente."
}

Le champ result sert au programme ; message sert à l’utilisateur. Évitez également d’exiger que le modèle expose un raisonnement interne détaillé sous forme de JSON. Ce que votre système doit stocker, c’est la décision observable, les entrées utilisées, les appels d’outils et les erreurs contrôlables — pas une prétendue transcription complète de la réflexion du modèle.

Le tableau de décision pour votre prochain projet

Utilisez cette règle avant d’intégrer une contrainte de sortie :

• Vous écrivez pour une personne : choisissez le langage naturel, éventuellement accompagné de quelques métadonnées.
• Vous échangez entre services avec une faible criticité : un JSON ordinaire validé peut suffire.
• Vous extrayez des champs fixes pour une base ou un traitement automatique : utilisez Structured Output avec JSON Schema si l’API le prend en charge.
• Vous préparez des paramètres de Tool Calling : imposez un Schema strict, puis appliquez validation métier et autorisation côté serveur.
• Vous construisez une interface dynamique : utilisez une structure versionnée, des champs optionnels et un mécanisme de repli.
• Vous orchestrez plusieurs étapes : structurez les événements et l’état ; gardez la réponse finale hybride lorsque l’utilisateur a besoin d’une explication.

Pour les traitements batch, ajoutez une phase d’évaluation avant la mise en production. Réutilisez exactement la même tâche d’extraction avec une réponse naturelle, une consigne JSON, le JSON mode et Structured Output. Comparez les erreurs de parsing, les champs absents, les types incorrects, les valeurs inventées et les changements de version du Schema. Les résultats doivent être enregistrés avec le modèle, l’interface utilisée et la date du test, car les garanties et les compatibilités évoluent.

L’approche est également utile dans un environnement Mac distant lorsque vous développez une application audio, vidéo ou graphique qui combine génération de métadonnées, prévisualisation et exécution d’outils. Si votre équipe doit tester plusieurs clients ou scripts, consultez le centre d’aide de kvmboot pour organiser l’accès à l’environnement de travail et clarifier les étapes d’exploitation. Pour comprendre le cadre de service avant de planifier un essai, la page présentation de kvmboot constitue un point de départ plus pertinent qu’une comparaison de performances isolée.

Les vérifications à effectuer avant la mise en production

Avant de considérer Structured Output comme terminé, vérifiez les points suivants :

• Le Schema décrit-il uniquement les données réellement consommées ?
• Les champs obligatoires sont-ils justifiés par une règle métier ?
• Les dates, montants, durées et unités sont-ils normalisés ?
• Les propriétés supplémentaires sont-elles acceptées, ignorées ou refusées ?
• La plateforme prend-elle en charge les mots-clés utilisés ?
• Une réponse de refus, d’erreur ou d’interruption possède-t-elle un chemin de traitement ?
• Les paramètres d’outil sont-ils contrôlés après génération ?
• L’autorisation est-elle calculée par votre serveur ?
• Les versions de Schema sont-elles traçables dans les journaux ?
• Le client possède-t-il un texte de repli lorsque la structure ne peut pas être rendue ?

Si vous répondez « non » à l’une de ces questions, le problème n’est pas nécessairement l’absence de Structured Output. Il peut venir d’un Schema trop ambitieux, d’une responsabilité placée au mauvais endroit ou d’un contrat qui mélange données générées et décisions de sécurité.

Pour un prototype de texte, imposer un Schema à chaque réponse peut ralentir le développement et compliquer inutilement l’expérience. Pour une extraction récurrente, un Agent qui appelle des outils ou un workflow qui déclenche des actions, rester sur du JSON ordinaire finit souvent par déplacer le coût vers les tests, les correctifs et les incidents.

Si votre solution actuelle dépend de scripts locaux hétérogènes, de machines partagées ou d’un environnement difficile à reproduire, vous rencontrez probablement trois limites concrètes : versions d’outils différentes, accès distant irrégulier et absence de nœud stable pour les essais automatisés. Une location ponctuelle d’un environnement Mac avec kvmboot peut alors être plus cohérente pour valider vos sorties structurées, tester vos interfaces audio ou vidéo et documenter votre workflow avant un déploiement plus durable. Ce choix ne remplace pas un serveur dédié pour une charge continue ni une machine physique lorsque des périphériques locaux sont indispensables ; il convient surtout lorsque vous avez besoin d’un environnement temporaire, contrôlable et reproductible pour vos validations.