AI Observabilité de l'agent pour les défaillances de l'outil: un test à cinq couches

Un agent AI peut échouer à utiliser un outil même lorsque son modèle est réactif, son processus est en vie et que l'appel à l'outil apparaît dans une trace. Le défaut pratique pour l'observabilité de l'agent AIZ est donc de tester un appel d'outil dans cinq couches ordonnées: transport, protocole, autorisation, exécution et résultat. Arrêtez à la première couche échouée. Cette règle transforme une alerte ambiguë outil indisponible en réparation limitée, et empêche une enveloppe de réponse verte d'être confondue avec le travail livré. Ce guide applique la règle aux outils de style MCP sur HTTP et JSON RPC, mais la forme de diagnostic fonctionne également pour les outils REST personnalisés et les adaptateurs de commandes locales. L'objectif n'est pas de recueillir chaque demande ou charge utile. Il s'agit de conserver la moindre preuve nécessaire pour répondre: où s'est arrêté l'appel, quelle autorité est requise et le résultat promis a t il atteint sa destination? Commencez par la première couche ratée Un seul compteur tool call failed s'écroule avec des défaillances qui nécessitent des réponses incompatibles. Une erreur DNS peut justifier une nouvelle tentative de connectivité limitée. Un jeton expiré peut justifier une mise à jour. Le champ d'application manquant nécessite une personne ou un administrateur; réessayer le même jeton est un gaspillage. Une réponse d'outil valide sans modification de fichier, de ticket, de message ou de base de données nécessite une enquête sur les résultats, pas une réparation de transport. Utilisez cette priorité: Couche Les preuves minimales Exemples d'échecs La prochaine étape raisonnable Transports résultat de la connexion, statut HTTP, temps écoulé Échec DNS, connexion refusée, HTTP 503 vérifier la disponibilité; réessayer uniquement dans le cadre d'un budget fixe Protocole ID de demande, méthode, code d'erreur JSON RPC Manque de méthode 32601 , paramètres invalides 32602 renouveler la découverte ou réparer le contrat de demande Autorisation Statut HTTP, erreur d'auteur désinfectée, portée requise 401 invalid token , 403 insufficient scope renouveler une fois ou demander à l'autorité manquante L'exécution état du résultat de l'outil, délai, verdict du schéma de sortie MCP isError: true , délais, sortie structurée déformée inspecter la mise en œuvre ou l'entrée de l'outil Le résultat vérificateur de destination et fraîcheur La réponse dit "créééé", mais l'artefact est absent. vérifier la destination; ne pas déclarer l'achèvement L'ordre compte. Si la résolution DNS a échoué, l'autorisation et le résultat sont unobserved , pas échoué. L'émission de cinq échecs pour une pause précoce gonfle le nombre d'incidents et envoie les intervenants vers des preuves qui n'ont jamais existé. Gardez l'échec du protocole séparé de l'échec de l'outil L'invocation de l'outil MCP utilise tools/call , tandis que la définition de l'outil porte un inputSchema et peut porter un outputSchema . Le Spécifications des outils MCP actuel affiche également un résultat d'outil avec isError: false . Ce sont des points de contrôle distincts: le client peut atteindre le serveur, échanger une réponse JSON RPC valide, et recevoir toujours une défaillance au niveau de l'outil. Le JSON RPC rend explicite la distinction extérieure. Son Specifications 2.0 se réserve 32601 pour Methode non trouvé et 32602 pour Invalid paramètres; une réponse d'erreur contient error , tandis qu'une réponse réussie contient result . Un JSON RPC result ne prouve que l'échange de protocoles a été achevé. Il ne prouve pas que l'outil a accepté l'opération, que sa sortie structurée correspond au schéma annoncé ou que l'effet secondaire externe existe. Enregistrer la limite sans stocker des arguments sensibles: Cet événement omet délibérément le jeton porteur, les arguments des outils, le corps de réponse, le texte du billet et les chemins absolus. Identificateurs de hachage ou de carte lorsque des joints croisés sont nécessaires. Une trace d'identification n'est utile que si le dossier médical peut encore expliquer la première couche ratée et le verdict final lorsque la trace brute n'est pas disponible. Ne réessayez pas un problème d'autorité comme si c'était une perte de paquets L'autorisation mérite sa propre couche car 401 et 403 impliquent des actions différentes. Le Spécification de l'autorisation de MCP exige que les clients gèrent le 401 Unauthorized et décrit la découverte de ressources protégées via le WWW Authenticate . Il recommande également des orientations sur la portée afin que le client puisse connaître l'autorité requise pour la demande en cours. RFC 6750 définit invalid token pour un jeton porteur expiré, révoqué, malformé ou autrement non valide et l'associe à HTTP 401. Il définit insufficient scope pour un jeton qui manque de privilèges requis et l'associe à HTTP 403. Cela donne à un opérateur une règle de décision sûre: 1. Pour invalid token , essayez le chemin de rafraîchissement configuré une fois. Si le certificat de réapprovisionnement échoue, arrêtez et faites apparaître le titulaire du certificat de réapprovisionnement. 2. Pour le insufficient scope , ne faites pas de boucle. Indiquer la portée requise si le serveur la fournit et demander une autorisation explicite. 3. Ne mettez jamais le jeton, le jeton de rafraîchissement, l'en tête d'autorisation ou le défi brut dans la télémétrie à usage général. Cette distinction empêche également un schéma d'automatisation dommageable: l'élargissement des autorisations chaque fois qu'un appel à l'outil échoue. Un incident de connectivité ne doit pas devenir une escalade de privilèges, et un déni de portée ne doit pas être "fixé" en passant silencieusement à une carte de crédit plus puissante. Reproduire l'écart entre le faux succès Le dispositif d'accompagnement contient huit appels synthétiques: deux erreurs de transport, une erreur de méthode JSON RPC, deux erreurs d'autorisation, une erreur d'exécution de l'outil, un faux succès et une livraison vérifiée. Exécutez le classifiateur dans le répertoire des objets: Le résultat décisif est: Trois appels ont rapporté une enveloppe de résultats, mais un seul a produit un résultat vérifié par la destination. Une enveloppe portait une erreur d'exécution; une autre prétendait avoir réussi alors que son artefact promis était absent. Les résultats du protocole de comptage rapportent un taux de réussite de 37,5%. Les résultats vérifiés sont comptabilisés à 12,5%. La différence ne résulte pas d'un score de détecteur ou d'un jugement LLM: elle résulte d'une modification du critère d'achèvement. L'appareil est intentionnellement déterministe. Les systèmes réels ajoutent de l'ambiguïté: une API de billet peut engager un enregistrement et un temps d'arrêt avant de renvoyer son identifiant; une recherche de destination peut être obsolète; une clé d'idempotence peut permettre une requête de réconciliation sécurisée. Marquez ces affaires uncertain . Ne réessayez pas d'appeler à un effet secondaire avant de savoir si la première tentative a été commise. Transformer les preuves en règle de fonctionnement Instrument un événement de santé par tentative d'exploitation de l'outil, lié à la course de propriété. Conservez la première couche échouée, le code désinfecté, la fraîcheur des preuves, réessayez le propriétaire et le vérificateur de résultats. Ensuite, appliquez quatre commandes: Alerte sur les incidents de groupe, pas sur chaque tentative. Cinq appels qui ne répondent pas à la même carte d'identité expirée sont un incident de l'autorité. Les caps sont réessayés par couche. Les défaillances de transport peuvent recevoir des retours limités; les défaillances de protocole et de portée nécessitent généralement un contrat ou un changement humain. Distinguer l'attente de la traînée. Un appel en attente d'un flux OAuth approuvé ne fait pas de progrès, mais ce n'est pas une boucle d'exécution. L'incident ne doit être effacé qu'après que la couche défaillante ait passé and et que le résultat prévu soit observé. Une commande réussie est une activité, pas une récupération. La ligne utile du tableau de bord est donc petite: agent affecté, première couche ratée, impact, temps de preuve, confiance, nombre de répétitions, autorité requise et résultat du vérificateur. Les traces brutes peuvent rester un exercice. Il s'agit de la santé de l'agent opérationnel, pas d'une obligation de remplacer le temps d'exécution ou de router chaque demande de modèle à travers une nouvelle passerelle. Il y a aussi une limite difficile. Tous les résultats ne disposent pas d'un vérificateur déterministe. Un fichier peut être vérifié par voie et digestion; un billet par ID stable; un déploiement par point d'extrémité santé et révision. La recherche est bonne peut nécessiter une rubrique ou un examen humain. Étiquettez la méthode et la confiance à côté du verdict au lieu de convertir les preuves manquantes en preuves saines. Sidewisp est actuellement en préversion privée. Ses adaptateurs de surveillance de la production et son exécution de récupération ne sont généralement pas expédiés. La direction prévue est une couche de santé à côté des temps d'exécution existants qui sépare la facilité d'accès, le progrès, l'accès aux outils et les résultats vérifiés tout en maintenant les humains sous contrôle. Si ce modèle d'exploitation correspond à vos agents, rejoindre la prévisualisation privée. Les sources Modèle de protocole contextuel: outils, version de spécifications 2025 11 25 Modèle de protocole contextuel: autorisation, version de spécifications 2025 11 25 JSON RPC 2.0 spécification RFC 6750, OAuth 2.0 Utilisation des jetons porteurs