2026 AI Agent : toute la sortie est un JSON invalide ? Localiser le problème dans le flux de données

August 20, 2026 · Agent IA · ~ 16 min de lecture

Ce guide aide les développeurs backend, les ingénieurs responsables d’agents à plusieurs étapes et les équipes d’exploitation à localiser une sortie JSON invalide sans accuser automatiquement le modèle. La méthode suit le trajet complet, de l’entrée contractuelle au retour du résultat, avec une grille de décision, une liste de contrôle, deux tableaux comparatifs et des cas de validation applicative.

Le point de départ : un JSON invalide n’est pas encore un diagnostic

Un contrat JSON Schema peut déclarer $schema, des propriétés obligatoires et des contraintes de type, tandis que la documentation officielle de JSON Schema distingue plusieurs versions de la spécification. Cette simple différence suffit à créer un premier point de rupture : un agent peut produire une réponse apparemment correcte, mais refusée par le validateur ou par la plateforme avant même l’appel de l’outil.

La conclusion opérationnelle est donc la suivante : pour résoudre une erreur JSON d’AI Agent, il ne faut pas relancer immédiatement le modèle. Il faut suivre le flux entrée contractuelle → génération du modèle → réponse API → parsing et validation → exécution de l’outil → retour du résultat. Si une sortie structurée stricte est disponible, elle doit être activée en premier, mais elle ne remplace jamais les contrôles métier de l’application.

Cette méthode concerne principalement trois profils :

les développeurs backend qui voient apparaître des erreurs de parsing ou des paramètres incomplets ;
les ingénieurs qui maintiennent des agents à plusieurs étapes et perdent des appels ou leur contexte ;
les équipes d’exploitation qui doivent relier une erreur de production à une requête, une version d’interface et un résultat d’exécution.

Les équipes qui cherchent uniquement à améliorer la formulation d’un prompt ne trouveront pas ici une solution suffisante : un prompt mieux écrit ne corrige ni un schéma incompatible, ni un identifiant d’appel supprimé par le middleware.

Commencer par figer le contrat d’entrée

Avant d’examiner la sortie du modèle, il faut prouver que le contrat envoyé à la plateforme est accepté. Cette étape est souvent négligée, car l’équipe regarde le message d’erreur final produit par son propre parseur.

Le contrat doit être conservé dans les journaux sous sa forme réellement transmise, et non sous la forme lisible présente dans le dépôt. Les points suivants méritent une vérification systématique :

l’URI $schema correspond-elle à la convention réellement comprise par le validateur ?
les mots-clés employés appartiennent-ils au sous-ensemble pris en charge par l’interface choisie ?
les champs marqués obligatoires sont-ils toujours renseignés dans les données attendues ?
les références imbriquées, les unions de types et les contraintes de format sont-elles acceptées ?
le SDK transforme-t-il le schéma avant l’envoi ?
le nom de l’outil et celui de l’opération correspondent-ils exactement ?

Le guide de base de JSON Schema et de la déclaration $schema rappelle pourquoi cette déclaration ne doit pas être traitée comme un simple commentaire. Elle donne au validateur le contexte nécessaire pour interpréter le document. Dans une chaîne composée de plusieurs services, l’absence de version explicite peut conduire à des comportements différents entre le poste de développement, le serveur d’intégration et la production.

La correction doit être progressive. L’équipe commence par un objet minimal comprenant un seul champ simple, vérifie son acceptation, puis réintroduit les champs obligatoires, les tableaux, les contraintes de format et les références. Si l’échec apparaît après une seule modification, la zone responsable est isolée sans modifier simultanément le prompt et le code d’exécution.

Rappel d’exploitation : un schéma accepté par un validateur local n’est pas nécessairement accepté par l’API du modèle. Il faut tester les deux contrats séparément et conserver le schéma envoyé dans chaque requête.

Distinguer refus, troncature et génération mal formée

Une application qui envoie directement le contenu textuel au parseur mélange plusieurs incidents qui exigent pourtant des traitements différents. Une réponse refusée n’est pas un JSON mal formé, et une réponse interrompue par une limite de longueur ne doit pas être réparée comme une simple virgule manquante.

Le service d’orchestration doit d’abord examiner les métadonnées de réponse :

état global de la requête ;
motif d’arrêt ;
présence d’un refus ;
erreur de longueur ou de quota ;
contenu réellement reçu ;
mode de transmission, notamment flux continu ou réponse complète.

Pour les réponses diffusées progressivement, la référence officielle des événements de refus en flux montre qu’un refus peut être transmis comme un état distinct des fragments de contenu. Le parseur ne doit donc pas attendre un objet JSON si l’API signale une autre branche de réponse.

La même règle s’applique à Structured Output. La documentation officielle sur Structured Outputs doit être consultée pour le comportement exact de l’interface utilisée, mais l’architecture applicative doit conserver trois chemins séparés :

réponse exploitable : validation syntaxique, validation de schéma, puis validation métier ;
réponse refusée : message contrôlé, aucune exécution d’outil, conservation du motif ;
réponse interrompue ou incomplète : diagnostic de longueur ou de transport, sans tentative de réparation silencieuse.

Une relance automatique n’est acceptable que pour une erreur explicitement transitoire, avec une limite, une temporisation et une corrélation de tentative. Elle ne doit pas masquer un schéma rejeté ou un refus reproductible. Sinon, le système augmente le bruit des journaux et peut déclencher plusieurs opérations identiques si une exécution a déjà commencé.

Aligner Structured Output, JSON Schema et le validateur applicatif

Structured Output et JSON Schema ne constituent pas une garantie unique répartie automatiquement sur toute la chaîne. Le premier encadre la génération selon les capacités de la plateforme ; le second décrit le contrat de données ; le validateur de l’application décide enfin si la charge reçue est acceptable pour le domaine métier.

Une incompatibilité typique apparaît lorsque le schéma est enrichi avec des constructions valables dans l’écosystème JSON Schema, mais absentes du sous-ensemble accepté par l’API. Les types et limites documentés pour Structured Output doivent être comparés au schéma réel, en particulier pour les objets imbriqués, les énumérations, les tableaux et les contraintes de format. La documentation consacrée à la validation et aux erreurs doit également guider la distinction entre échec de validation côté service et réponse invalide côté application.

La liste de contrôle suivante permet de réduire rapidement le périmètre :

[ ] le schéma exact de la requête est archivé ;
[ ] la version du validateur est inscrite dans le journal ;
[ ] le dialecte et les formats activés sont connus ;
[ ] le schéma minimal passe dans l’API et dans le validateur local ;
[ ] le schéma complet est testé avec des données valides et invalides ;
[ ] le SDK ne retire pas les champs obligatoires ;
[ ] le message d’erreur de validation est conservé sans être remplacé par « JSON invalide ».

Un modèle peut produire une structure conforme tout en sélectionnant une valeur inadaptée. Par exemple, une chaîne représentant un identifiant peut respecter type: string alors que cet identifiant n’existe pas. Une sortie structurée doit donc être considérée comme la première barrière, pas comme une autorisation d’exécuter.

Vérifier les paramètres avant de laisser l’outil agir

Le Function Calling transporte une intention d’appel et des arguments structurés ; il ne vérifie pas à lui seul la réalité des ressources. La documentation officielle du processus de Function Calling décrit le cycle dans lequel l’application reçoit un appel, exécute la fonction, puis renvoie le résultat. L’équipe doit compléter ce cycle par une validation côté serveur.

Un champ manquant se recherche à trois endroits distincts :

dans le schéma déclaré ;
dans les arguments reçus après décodage ;
dans la fonction qui convertit ces arguments vers le système cible.

Si le champ est absent dès la réponse, le problème concerne la génération ou le contrat. S’il est présent dans la réponse mais disparaît dans le journal de l’outil, le middleware ou le sérialiseur est probablement responsable. S’il arrive jusqu’à la fonction mais devient vide après conversion, la cause se trouve dans le mapping applicatif.

Les contrôles métier doivent couvrir au minimum :

existence de la ressource demandée ;
autorisation du compte à agir sur cette ressource ;
cohérence entre les champs liés ;
plage acceptable pour les quantités, dates ou chemins ;
idempotence de l’opération ;
environnement cible, notamment test ou production.

Cette séparation est particulièrement importante dans les usages audio, vidéo et design. Un chemin de fichier peut être syntaxiquement correct mais inaccessible au processus, un identifiant de piste peut exister dans un projet mais pas dans sa version exportée, et une opération de rendu peut être valide dans un environnement de test mais interdite sur une machine de production. Le JSON ne peut pas résoudre ces écarts.

Restaurer l’état lors des appels à plusieurs étapes

Dans un agent à plusieurs étapes, le défaut visible peut apparaître au moment du second appel alors que la perte s’est produite lors du retour du premier outil. L’application doit comparer le message envoyé au modèle avec le message reçu de l’outil, en vérifiant les identifiants, le nom de l’opération, les arguments d’origine et le résultat.

Les erreurs fréquentes sont les suivantes :

suppression de l’identifiant d’appel lors d’une conversion de format ;
remplacement du message d’outil par un résumé textuel ;
mélange de deux conventions de rôle ;
oubli d’un résultat lorsque plusieurs appels sont traités en parallèle ;
reconstruction de l’historique à partir d’un objet partiel ;
réutilisation d’un identifiant pour deux tentatives.

Les règles d’état varient selon l’interface utilisée. Il faut donc suivre la documentation officielle de l’API concernée, sans transposer automatiquement le format d’un fournisseur à un autre. Le fonctionnement des outils dans la spécification MCP impose lui aussi d’examiner le nom de l’outil, sa description, son schéma d’entrée et le résultat retourné, plutôt que de réduire l’échange à une chaîne JSON isolée. La spécification générale de MCP sert de référence lorsque plusieurs composants doivent partager le même contrat.

Pour les incidents complexes, une trace de corrélation doit relier la requête initiale, chaque appel d’outil, chaque retour et l’action finale. Sans cette continuité, le journal montre seulement que « l’étape suivante a échoué », sans révéler si le contexte a été supprimé par le client, le serveur d’outils ou la couche de stockage.

Questions fréquentes de diagnostic

Pourquoi l’AI Agent renvoie-t-il toujours un JSON invalide ?

Il faut d’abord comparer le contenu brut reçu et les métadonnées de réponse. Si la plateforme indique un refus ou une interruption, le parseur ne doit pas être appelé. Si le contenu est bien reçu, l’équipe vérifie ensuite les caractères ajoutés par un modèle de présentation, les fragments de flux concaténés dans le mauvais ordre et l’écart entre le schéma envoyé et le validateur local. Cette séquence évite de modifier inutilement le prompt.

Comment retrouver un champ absent dans un appel de fonction ?

Le champ doit être suivi du schéma jusqu’au serveur d’outil. L’équipe capture le schéma transmis, les arguments bruts, l’objet après décodage et la charge utile avant exécution. Une comparaison différentielle montre si l’omission vient du modèle, du SDK ou du code de conversion. Si le champ est obligatoire mais qu’une valeur par défaut est appliquée silencieusement, cette transformation doit également être journalisée.

Pourquoi une sortie structurée échoue-t-elle encore ?

Une sortie structurée peut être refusée à cause d’une contrainte non supportée ou interrompue avant sa fin. Elle peut aussi être conforme au schéma mais inutilisable pour le métier. Le traitement correct consiste à séparer le statut de la réponse, la validation JSON, la validation du schéma et la validation métier. Chacune doit produire un code d’erreur différent, afin que les tableaux de bord ne regroupent pas des incidents de nature opposée.

Comment conserver le contexte après le retour d’un outil ?

L’application doit conserver l’identifiant d’appel et réinjecter le résultat dans la structure attendue par l’interface, sans le convertir en simple note libre. Un test minimal avec un seul outil permet de vérifier le cycle complet. Ensuite, l’équipe ajoute les appels parallèles, la persistance et les reprises. Si le défaut n’apparaît qu’après une reprise, la comparaison des historiques avant et après stockage révèle généralement le champ supprimé.

Un JSON valide peut-il déclencher une mauvaise opération ?

Oui, car la syntaxe ne vérifie ni les permissions ni la disponibilité d’une ressource. Un validateur métier doit contrôler l’existence, les relations entre champs, les limites autorisées et l’environnement ciblé. Pour une opération destructive ou coûteuse, l’application peut demander une confirmation indépendante du modèle. Le résultat de l’outil doit enfin être validé, car une requête acceptée ne garantit pas son exécution effective.

Choisir la bonne branche de correction

La grille suivante sert à décider quelle action effectuer avant toute nouvelle tentative. Elle évite de traiter chaque incident par une relance générique.

Symptôme observé	Vérification prioritaire	Action recommandée	Relance automatique
Contrat refusé avant génération	Version, sous-ensemble, références et complexité du schéma	Réduire le schéma au minimum, puis réintroduire les contraintes	Non
Refus explicite	État de refus et contenu réellement disponible	Informer l’appelant et interrompre l’outil	Non, sauf nouvelle demande contrôlée
Réponse interrompue	Motif d’arrêt, limite de longueur et fragments reçus	Marquer la réponse incomplète et reprendre selon une stratégie dédiée	Seulement si l’erreur est transitoire
JSON décodable mais non conforme	Validateur et version du dialecte	Corriger le contrat ou le mapping	Non
Paramètres conformes mais inutilisables	Existence, permission et cohérence métier	Bloquer l’outil et retourner une erreur explicite	Non
Résultat perdu à l’étape suivante	Identifiant, historique et message d’outil	Restaurer le cycle d’état et tester un cas minimal	Non

La frontière entre « retryable » et « non-retryable » doit être codée, non déduite d’un texte d’erreur approximatif. Une panne réseau momentanée peut justifier une reprise bornée ; un champ obligatoire absent, un schéma rejeté ou une permission insuffisante exige une correction ou une remontée d’incident.

Organiser le journal qui permet réellement de reproduire

Le dernier contrôle porte sur la qualité de la preuve. Un message « parsing failed » ne permet pas de distinguer un problème d’API, de validation ou d’outil. Une trace utile doit rester exploitable tout en protégeant les données sensibles.

La liste suivante peut servir de base à un événement de journalisation :

[ ] identifiant de corrélation et identifiant de tentative ;
[ ] horodatage et étape du flux ;
[ ] modèle, interface et version du SDK ;
[ ] empreinte du schéma et version du validateur ;
[ ] entrée désensibilisée ou référence vers une copie protégée ;
[ ] réponse brute désensibilisée ;
[ ] état de réponse et motif d’arrêt ;
[ ] erreur syntaxique ou erreur de schéma ;
[ ] arguments transmis à l’outil ;
[ ] résultat de validation métier ;
[ ] résultat réel de l’exécution ;
[ ] décision de reprise, d’abandon ou d’escalade.

La désensibilisation doit être déterministe : les identifiants peuvent être remplacés par des valeurs stables, les jetons supprimés et les chemins privés rendus génériques, tout en conservant les relations entre champs. Une équipe ne doit pas publier dans un ticket d’incident la charge utile complète d’un compte ou d’un projet audio simplement parce qu’elle cherche une virgule fautive.

Pour isoler la cause, il faut réduire le cas à une seule requête, un seul schéma, un seul outil et un résultat prévisible. Le test est ensuite répété avec la version exacte du modèle, de l’interface et du validateur utilisés en production. Ce n’est qu’après cette reproduction que le correctif doit être généralisé aux scénarios parallèles, aux reprises et aux charges vidéo ou design plus volumineuses.

Comparer une correction locale avec un environnement Mac isolé

Option	Pertinente lorsque	Limite principale	Contrôle à prévoir
Poste de développement existant	Le défaut est reproductible avec une petite charge et sans dépendance matérielle	L’environnement peut différer de la production et les essais peuvent perturber le poste	Versions, variables et données de test
Machine de production	L’incident dépend d’un accès ou d’un fichier réellement présent	Risque d’exécuter un outil ou de modifier un état réel	Copie désensibilisée et mode lecture seule
Environnement Mac loué avec nuvcloud	Il faut isoler une reproduction temporaire, tester une chaîne distante ou réunir des outils audio, vidéo ou design	Il faut vérifier les accès réseau, les permissions et les dépendances avant l’essai	Journal de corrélation, durée d’accès et destruction des données
Achat d’un Mac dédié	L’équipe maintient durablement une charge stable avec besoin d’accès physique	Coût initial, maintenance et capacité inutilisée hors période de test	Inventaire, mises à jour et séparation des comptes

Le choix ne dépend donc pas du seul fait qu’un JSON soit invalide. Une machine locale reste préférable lorsque l’incident nécessite un périphérique physique, une charge permanente ou un accès direct à des données qui ne peuvent pas sortir du site. À l’inverse, une reproduction temporaire gagne à être isolée lorsque l’équipe doit comparer plusieurs versions, protéger le poste de travail principal ou offrir un environnement contrôlé à un développeur distant. Le centre d’aide de nuvcloud peut être consulté pour vérifier les conditions d’accès et les limites opérationnelles avant de déplacer un scénario de test.

Finir par un cas minimal, pas par une nouvelle boucle de reprises

Un agent qui renvoie du JSON invalide n’est pas nécessairement un modèle défaillant. Le défaut peut se trouver dans le contrat, le statut de réponse, le découpage en flux, le validateur, la conversion des paramètres, l’autorisation de l’outil ou la restitution de l’historique. La correction prioritaire consiste à identifier l’étape exacte, à conserver la preuve et à appliquer une branche de traitement adaptée.

L’approche actuelle — relancer l’agent, concaténer la réponse et espérer que le parseur accepte le résultat — présente trois défauts : elle masque la cause racine, elle peut répéter une opération déjà exécutée et elle rend les incidents impossibles à comparer entre versions. Pour une équipe qui doit reproduire une panne dans un contexte audio, vidéo ou design, elle ajoute en outre le risque de mélanger les fichiers de test avec les données de production.

Un environnement Mac temporaire fourni par nuvcloud devient alors une option plus propre lorsque l’objectif est d’isoler une chaîne de reproduction, de comparer les versions d’un outil ou de laisser une équipe distante travailler sans modifier le poste principal. Il ne remplace pas un Mac acheté pour une charge stable ni une infrastructure locale soumise à des contraintes matérielles, mais il offre un cadre distinct pour transformer les journaux en cas minimal vérifiable. La présentation de nuvcloud permet de situer ce type d’usage avant de choisir l’environnement adapté.