Un mardi après-midi, après douze tours de débogage, mon agent affirmait que l’endpoint /users répondait en 47 secondes. La vraie valeur était 47 millisecondes.

Essayez Apidog aujourd’hui

Je traquais ce bug depuis deux jours. J’avais ajouté des logs au serveur MCP, relu les réponses du modèle token par token, modifié l’invite système, comparé plusieurs hypothèses. Rien ne pointait clairement vers la cause.

Ce que je n’avais pas encore fait : ouvrir la trace d’exécution réelle et regarder l’échange exact entre le modèle et l’outil.

C’est là que l’Apidog AI Agent Debugger m’a fait gagner du temps. En douze minutes, le bug était identifié.

Le bug que je traquais

La configuration était simple :

• un agent basé sur gpt-5.5
• un serveur MCP écrit rapidement
• un outil exposé : get_response_time(endpoint)
• une invite système courte
• une invite utilisateur : Quelle est la vitesse du endpoint /users ?

L’agent répondait vite, avec assurance, mais faux.

Exemples de réponses observées :

• Le endpoint répond en 47 secondes.
• Environ 0,05 seconde.
• La performance est acceptable.

Le problème avec le débogage d’agents, c’est que l’erreur peut se trouver à plusieurs endroits :

1. l’invite système
2. le choix du modèle
3. la définition de l’outil
4. les paramètres envoyés à l’outil
5. la réponse retournée par l’outil
6. l’interprétation de cette réponse par le modèle

Un log serveur ne montre généralement qu’une partie de cette chaîne.

Ce que montre réellement le panneau Traces

Le débogueur Apidog s’organise en trois panneaux :

• Sessions, à gauche
• Tours, au centre
• Traces, à droite

Cliquez sur une session, puis sur un tour : le panneau Traces affiche l’arbre d’exécution complet.

Vous voyez notamment :

• l’invite système reçue par le modèle
• l’invite utilisateur reçue par le modèle
• le nom de l’outil appelé
• les paramètres envoyés à l’outil, au format JSON
• la réponse retournée par l’outil, au format JSON
• la réponse finale du modèle
• les temps, tokens et coûts associés au tour

Dans ma session défaillante, l’appel d’outil était correct :

get_response_time(endpoint="/users")

Le modèle avait choisi le bon outil avec le bon argument.

Puis j’ai ouvert le résultat de l’outil :

{
  "value": 47,
  "p95": 89,
  "samples": 1240
}

Le pipeline de métriques renvoyait une valeur en millisecondes. Le modèle a supposé des secondes.

Le bug n’était donc pas dans l’appel MCP. Il était dans la forme de la donnée retournée et dans l’absence d’instruction explicite sur les unités.

La correction a pris six lignes

J’ai modifié la réponse du serveur MCP pour rendre les unités explicites :

{
  "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 relancé la même invite trois fois.

Résultat : les trois sessions ont correctement répondu que l’endpoint répondait à environ 47 ms.

Le coût en tokens était aussi inférieur à mes exécutions précédentes, probablement parce que le modèle ne générait plus de texte pour compenser ses propres hypothèses incorrectes.

J’ai ensuite exécuté la même configuration avec Claude Opus 4.7 dans une autre session. Même résultat, coût plus élevé, réponse plus verbeuse. La comparaison était visible directement dans le panneau des sessions : tours, étapes, temps, tokens et coût.

Ce que je faisais mal

Je traitais le débogueur comme un outil de logging. Ce n’est pas seulement ça.

Un log vous montre ce qui s’est passé dans votre code. Le débogueur vous montre ce que le modèle et les outils ont réellement échangé.

Si vous regardez uniquement la sortie du modèle et que vous devinez la cause, vous ne déboguez pas l’agent. Vous déboguez votre hypothèse sur l’agent.

Un agent est un système composé de quatre éléments :

• le modèle
• l’invite
• les outils
• les réponses des outils

Le bug se trouve souvent à l’intersection de ces éléments.

Le débogueur m’a aussi montré un autre problème : le non-déterminisme de mon agent.

Après la correction, j’ai exécuté la même invite cinq fois :

• trois exécutions ont appelé get_response_time une seule fois
• deux exécutions l’ont appelé deux fois
• dans ces deux cas, le chemin du endpoint utilisait une casse différente

Mon schéma d’outil était sensible à la casse. Je ne l’avais pas vu, car mes tests manuels utilisaient toujours /users en minuscules.

Le test multi-exécutions est donc devenu une étape de validation : exécuter plusieurs fois la même invite, puis repérer ce qui varie.

Guide d’installation et de débogage

Voici le flux complet pour reproduire une session de débogage avec Apidog.

Étape 1 : Créer une session de débogage d’agent

Ouvrez Apidog, puis cliquez sur AI Agent Debugger dans la barre d’onglets supérieure.

Configurez ensuite le modèle :

• choisissez le fournisseur de modèle
• choisissez le modèle spécifique, par exemple gpt-5.5
• vérifiez que l’URL de base est remplie automatiquement
• cliquez sur Exécuter pour démarrer une session

Étape 2 : Configurer les invites

Dans l’onglet Invites, renseignez :

• Invite système : rôle, objectifs, contraintes et règles d’utilisation des outils
• Invite utilisateur : entrée de test pour la session

Exemple d’invite utilisateur :

Quelle est la vitesse du endpoint /users ?

Cliquez ensuite sur Exécuter.

Si vous voulez vider automatiquement le champ après chaque exécution, activez Effacer après envoi.

Étape 3 : Configurer les outils

L’onglet Outils liste les capacités que l’agent peut appeler pendant l’exécution.

Les outils intégrés peuvent être activés ou désactivés selon le besoin.

Pour connecter des systèmes externes ou vos propres outils, utilisez des serveurs MCP.

Méthodes de connexion disponibles :

• STDIO : lance un processus de serveur MCP local
• HTTP : se connecte à un serveur MCP compatible HTTP Streamable
• SSE : se connecte à un serveur MCP basé sur Server-Sent Events

Les serveurs MCP nécessitant une authentification peuvent utiliser des en-têtes de requête ou OAuth 2.0.

Une fois la connexion établie, sélectionnez les outils exposés que l’agent peut utiliser.

Étape 4 : Configurer les compétences, l’authentification et les paramètres

Trois onglets complètent la configuration.

Compétences

Les Compétences sont des flux de travail réutilisables pour l’agent.

Elles sont utiles pour :

• éviter de répéter de longues instructions dans l’invite système
• définir des workflows projet
• formaliser des tâches récurrentes
• charger des instructions seulement quand elles sont nécessaires

Authentification

L’onglet Authentification contient les identifiants requis par les services de modèle ou les services MCP.

Paramètres

L’onglet Paramètres permet d’ajuster les paramètres d’exécution du modèle, par exemple :

• température
• max tokens
• top P

Les paramètres disponibles dépendent du fournisseur et du modèle utilisé.

Étape 5 : Lire les trois panneaux

Après avoir cliqué sur Exécuter, une nouvelle session apparaît dans le panneau de gauche.

Exemple de résumé :

Session 3
1 tour · 1 étape · 10s · 3.1k tokens · $0.02
gpt-5.5

Les panneaux se lisent ainsi :

• Sessions : historique des exécutions avec métriques récapitulatives
• Tours : échanges utilisateur/modèle pour chaque session
• Traces : chaîne d’exécution complète, dans l’ordre

Le panneau Traces est le plus important pour déboguer.

Il permet de vérifier :

• l’invite système réellement envoyée
• l’invite utilisateur
• les appels de modèle
• les appels d’outils MCP
• les paramètres d’entrée des outils
• les résultats retournés
• les erreurs
• le temps consommé
• la sortie finale

Lorsqu’un appel d’outil échoue ou qu’une exception est renvoyée, l’étape fautive apparaît directement dans la trace, avec ses entrées et sorties.

Étape 6 : Comparer les modèles

Pour comparer deux modèles, gardez la même configuration :

• même invite système
• même invite utilisateur
• mêmes outils
• mêmes paramètres, si possible

Puis changez uniquement le modèle.

Chaque exécution crée une nouvelle session, ce qui permet de comparer dans le panneau gauche :

• nombre d’étapes nécessaires
• qualité du choix d’outil
• temps de réponse
• consommation de tokens
• coût
• stabilité entre plusieurs exécutions

C’est utile pour décider quel modèle passer en production, surtout si plusieurs modèles produisent une réponse correcte mais avec des coûts ou des comportements différents.

Le point à retenir

Le bug n’était pas dans mon endpoint. Il n’était pas non plus dans le serveur MCP. Il était dans le contrat implicite entre l’outil et le modèle : une valeur numérique sans unité.

La correction a été simple, mais seulement après avoir vu l’échange exact entre le modèle et l’outil.

Si vous construisez des agents, ajoutez cette vérification à votre workflow :

1. exécuter l’invite
2. ouvrir la trace
3. vérifier l’appel d’outil
4. vérifier les paramètres
5. vérifier la réponse JSON
6. vérifier l’interprétation du modèle
7. relancer plusieurs fois pour détecter les variations

Téléchargez Apidog et utilisez-le sur le prochain agent qui répond avec assurance mais incorrectement.

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.