Un mardi après-midi. Douze tours plus tard dans une session de débogage, et l'agent me disait avec assurance que notre endpoint /users répondait en quarante-sept secondes. Le vrai chiffre était quarante-sept millisecondes.
Je traquais ce bug depuis deux jours. Chaque fois que j'ajoutais une instruction print au serveur MCP, la réponse de l'agent se décalait juste assez pour me faire croire que j'avançais. Chaque fois que je réécrivais l'invite système, la réponse semblait plus plausible. Rien de tout cela n'était juste.
Ce que je n'avais pas fait, jusqu'à cet après-midi, c'était d'ouvrir la trace d'exécution réelle et de regarder ce qui était passé entre le modèle et l'outil. C'est à cela que sert l'Apidog AI Agent Debugger. Je l'avais installé trois semaines plus tôt et je l'avais oublié. Il m'a fallu douze minutes pour trouver le bug.
C'est ce qui m'a surpris.
Le bug que je traquais
La configuration était simple. Un agent basé sur GPT-5.5. Un serveur MCP que j'avais écrit en un week-end, exposant un outil get_response_time(endpoint) qui interrogeait notre pipeline de métriques. Une invite système d'environ quarante mots. L'invite utilisateur : « Quelle est la vitesse du endpoint /users ? »
L'agent a répondu rapidement. Il a répondu avec assurance. Il a répondu faux, à chaque fois, de différentes manières. Parfois « le endpoint répond en 47 secondes. » Parfois « environ 0,05 seconde. » Une fois, de manière mémorable, « la performance est acceptable. »
J'avais fait ce que l'on fait habituellement. Ajouté des logs au serveur MCP. Lu la réponse du modèle token par token. Comparé les invites système. Juré. J'avais trois fenêtres de terminal ouvertes et une page Notion d'hypothèses échouées le mardi matin.
Le problème avec le débogage des agents est que le bug se trouve rarement là où vous regardez en premier. Il peut se trouver dans l'invite système, dans le choix du modèle, dans la définition de l'outil, dans les paramètres que le modèle a transmis à l'outil, dans les données que l'outil a renvoyées, ou dans la façon dont le modèle a interprété ces données. Six endroits. Un log de console ne vous en montre qu'un.
Ce que le panneau Traces montre réellement
Le débogueur Apidog s'ouvre en trois colonnes. Les sessions à gauche. Les tours au milieu. Les traces à droite. Cliquez sur n'importe quelle session et la colonne du milieu vous montrera le dialogue : message utilisateur, réponse du modèle, appel d'outil, retour d'outil, prochaine réponse du modèle. Cliquez sur n'importe quel tour et la colonne de droite se développera pour afficher l'arbre d'exécution complet en dessous.
L'arbre d'exécution est la partie qui me manquait. Chaque étape, dans l'ordre :
- Invite système telle que reçue par le modèle
- Invite utilisateur telle que reçue par le modèle
- Nom et paramètres de l'appel d'outil, au format JSON, exactement tels que le modèle les a émis
- Charge utile du résultat de l'outil, au format JSON, exactement telle que l'outil l'a renvoyée
- Réponse du modèle, avec les temps et les tokens pour le tour
J'ai ouvert la session défaillante. L'appel d'outil semblait correct : get_response_time(endpoint="/users"). Le modèle avait choisi le bon outil avec le bon argument.
Ensuite, j'ai développé le résultat de l'outil.
{"value": 47, "p95": 89, "samples": 1240}
C'était ça. Le pipeline de métriques renvoyait la valeur en millisecondes. Le modèle a supposé des secondes. 47 est devenu « 47 secondes » via une hallucination confiante qui n'a pas pris la peine de remettre en question l'unité. L'outil était correct. Le modèle était faux. Mon invite système n'avait aucune instruction sur les unités, et la réponse de l'outil n'avait aucune annotation d'unité.
Douze minutes après l'ouverture du débogueur. Deux jours que j'incriminais l'invite système.
La correction a pris six lignes
J'ai changé deux choses. Dans le serveur MCP, j'ai mis à jour la forme de la réponse :
{
"value": { "amount": 47, "unit": "ms" },
"p95": { "amount": 89, "unit": "ms" },
"samples": 1240
}
Puis j'ai ajouté une phrase à l'invite système : « Les résultats des outils renvoient les unités explicitement. Lisez-les attentivement. »
J'ai exécuté la même invite /users trois fois de plus. Trois sessions différentes sur le panneau de gauche. Toutes les trois ont correctement renvoyé « le endpoint répond à environ 47 ms » avec une ventilation milliseconde-à-percentile dans le raisonnement du modèle. Le coût en tokens était dix-huit pour cent inférieur à mes exécutions défaillantes, probablement parce que le modèle ne générait pas de prose de récupération autour de ses propres mauvaises hypothèses.
J'ai exécuté la même invite sur Claude Opus 4.7 dans une deuxième session, côte à côte. Même résultat, deux fois le coût, légèrement plus verbeux. Je savais quel modèle allait partir en production.
C'est la partie de l'outil qui m'a valu mon respect. Pas la découverte de bugs, ce que tout bon débogueur devrait faire. Mais la comparaison de modèles, exécutée sur des configurations identiques avec des métriques récapitulatives dans le panneau de gauche : nombre de tours, nombre d'étapes, temps, tokens, dollars. J'avais fait cette comparaison dans une feuille Google pendant six mois. Maintenant, c'était trois clics.
Ce que je faisais mal
L'idée simpliste est que l'AI Agent Debugger est un outil de logging. Ce n'est pas le cas. Les outils de logging vous montrent ce qui s'est passé. Le débogueur vous montre ce que le modèle et l'outil ont réellement échangé, ce qui est une couche différente.
Si vous écrivez des agents et que vous faites ce que je faisais, c'est-à-dire lire la sortie du modèle et deviner la cause des échecs, voici ce que je voudrais contester. Vous ne déboguez pas l'agent. Vous déboguez votre hypothèse sur l'agent. Ce sont des choses différentes, et seule l'une d'elles vous mène à une solution.
Ce que j'avais refusé d'intégrer pendant six mois, c'est que l'agent est un système fermé entre le modèle, l'invite, les outils et les réponses des outils. Le bug réside toujours dans l'un de ces quatre éléments. Si vous pouvez voir les quatre en même temps, vous pouvez trouver le bug en douze minutes. Sinon, vous pouvez le traquer pendant une semaine.
L'autre chose que le débogueur a révélée, à laquelle je ne m'attendais pas, était le non-déterminisme de mon propre agent. J'ai exécuté la même invite cinq fois après la correction, juste pour confirmer. Trois exécutions ont appelé get_response_time une fois. Deux exécutions l'ont appelé deux fois, la deuxième fois avec le chemin du endpoint dans une casse différente. Mon schéma d'outil était sensible à la casse. Je ne l'avais pas remarqué car tous mes cas de test défaillants utilisaient la minuscule. C'était un deuxième bug que j'aurais livré sans le voir.
L'analyse multi-exécutions est la fonctionnalité que j'utiliserai le plus à l'avenir. Cliquez sur Exécuter cinq fois. Regardez le panneau des sessions. Tout ce qui varie d'une exécution à l'autre est un endroit où votre agent est fragile.
Essayez par vous-même : un guide complet d'installation
Si vous souhaitez la même configuration que celle que j'utilisais pendant la chasse aux bugs, voici le chemin depuis une installation fraîche jusqu'à une session de débogage en cours. Cinq écrans, dans l'ordre.
Étape 1 : Créer une nouvelle session de débogage d'agent
Ouvrez Apidog et cliquez sur AI Agent Debugger dans la barre d'onglets supérieure. La section supérieure de la page configure le modèle et l'état d'exécution.
- Choisissez le fournisseur de modèle à gauche (OpenAI, Anthropic et autres)
- Choisissez le modèle spécifique au milieu, par exemple
gpt-5.5 - L'URL de base se remplit automatiquement une fois le fournisseur sélectionné, aucune saisie manuelle n'est nécessaire
- Cliquez sur Exécuter pour démarrer une session
Étape 2 : Configurer les invites
L'onglet Invites comporte deux zones de saisie.
- Invite système : définit le rôle, les objectifs, les contraintes et les règles d'utilisation des outils de l'agent
- Invite utilisateur : l'entrée de test pour cette session, par exemple « Qu'est-ce qu'Apidog ? »
Cliquez sur Exécuter en haut à droite lorsque les deux sont définis. Si vous souhaitez que le champ de saisie soit effacé automatiquement après chaque exécution, cochez Effacer après envoi.
Étape 3 : Configurer les outils
L'onglet Outils répertorie tout ce que l'agent peut appeler au moment de l'exécution. Le nombre sur l'onglet est le décompte actuel des outils disponibles ou configurés.
Les outils intégrés sont livrés avec le débogueur. Activez-les ou désactivez-les selon les besoins.
| Outil | Ce qu'il fait |
|---|---|
bash |
Exécute des commandes dans une session shell persistante |
web_fetch |
Récupère du contenu web et le convertit en Markdown, texte ou HTML |
read |
Lit des fichiers texte, image ou PDF |
edit |
Applique des remplacements de chaînes précis aux fichiers |
write |
Crée ou écrase des fichiers |
grep |
Recherche du contenu de fichier avec des expressions régulières |
glob |
Trouve des fichiers en utilisant des motifs glob |
kill_shell |
Réinitialise la session shell actuelle |
Les outils MCP ajoutent des systèmes externes ou des capacités personnalisées via des serveurs MCP. Trois méthodes de connexion :
- STDIO : lance un processus de serveur MCP local
- HTTP : se connecte à un serveur MCP qui prend en charge le HTTP Streamable
- SSE : se connecte à un serveur MCP basé sur les Server-Sent Events
Les serveurs MCP qui nécessitent une authentification acceptent les en-têtes de requête ou les flux OAuth 2.0. Une fois la connexion établie, choisissez les outils que le serveur expose à l'agent.
Étape 4 : Configurer les compétences, l'authentification et les paramètres du modèle
Trois onglets plus petits complètent la configuration.
- Compétences : flux de travail réutilisables pour l'agent. Utile pour les flux de travail de projet fixes, les spécifications d'opérations de tâches courantes et la réduction du texte long répétitif dans les invites système. Les compétences sont chargées au besoin pendant l'exécution.
- Authentification : identifiants requis par les services de modèle ou les services MCP.
- Paramètres : paramètres d'exécution du modèle tels que Température, Max Tokens et Top P. Les paramètres pris en charge varient selon le fournisseur, alors vérifiez ce que votre modèle accepte réellement.
Étape 5 : Lire les trois panneaux
Après avoir cliqué sur Exécuter, la session que vous venez de créer apparaît dans le panneau de gauche. Chaque session affiche un résumé sur une ligne :
Session 3
1 tour · 1 étape · 10s · 3.1k tokens · $0.02
gpt-5.5
- Panneau Sessions (gauche) : historique de chaque exécution avec des métriques récapitulatives
- Panneau Tours (milieu) : chaque tour de dialogue utilisateur/modèle. Cliquez sur un tour pour charger ses détails d'exécution à droite.
- Panneau Traces (droite) : la chaîne d'exécution complète de l'agent dans l'ordre, y compris les invites système et utilisateur, chaque appel de modèle, le processus de pensée du modèle s'il l'expose, les appels d'outils MCP et les exécutions de compétences personnalisées, les paramètres d'entrée de l'outil, les résultats, le temps consommé, les messages d'erreur et la sortie finale.
Lorsqu'un appel d'outil échoue ou que le modèle renvoie une exception, l'étape défaillante est juste là dans le panneau Traces, avec ses entrées et sorties visibles. Pas besoin de fouiller les logs.
Étape 6 : Comparer les performances du modèle
Même invite, même configuration d'outil, modèle différent. Chaque exécution crée une nouvelle session, et le panneau de gauche vous permet de les comparer côte à côte.
Métriques utiles à comparer :
- Nombre d'étapes d'exécution pour la même tâche
- Quel modèle choisit les outils avec plus de précision
- Quel modèle a un temps de réponse plus faible
- Quel modèle maintient la consommation de tokens et le coût plus prévisibles
Le point à retenir
Deux jours de débogage se sont transformés en un après-midi, et je n'ai pas appris la leçon sur le bug. Je l'ai apprise sur l'outillage. La raison pour laquelle je cherchais la mauvaise solution était que les outils que j'utilisais ne me montraient pas ce que j'avais besoin de voir. J'avais une sortie de modèle et une sortie d'outil, et aucun cadre partagé pour les examiner ensemble. Le cadre partagé est tout l'intérêt.
Si vous avez écrit plus d'un agent et que vous n'avez pas encore ouvert l'AI Agent Debugger d'Apidog, le prochain agent que vous livrerez aura un bug qui se trouve entre le modèle et l'outil. Vous y passerez une semaine. Vous rédigerez une page Notion d'hypothèses échouées. Le bug sera exactement là où le débogueur vous l'aurait montré dès le premier jour.
Téléchargez Apidog et ouvrez-le sur le prochain agent qui vous donne une mauvaise réponse avec une voix confiante. Douze minutes. Quarante-sept millisecondes, pas quarante-sept secondes.
La référence complète des fonctionnalités, y compris la configuration du transport MCP et la disponibilité des plans, se trouve dans Apidog AI Agent Debugger : disponibilité, couverture et configuration.