Si vous construisez des agents IA qui communiquent avec d'autres agents IA, vous avez déjà rencontré le même obstacle que tout le monde : il n'y a pas de moyen clair d'inspecter ce qu'un agent envoie à un autre. Les journaux de console mentent, les onglets réseau masquent les champs structurés, et les scripts de test sur mesure se détériorent rapidement. Le Débogueur A2A d'Apidog résout ce problème pour le protocole Agent2Agent (A2A). Collez une URL de Carte d'Agent, cliquez sur Connecter, envoyez un message, et lisez la réponse sous trois vues.
Ce guide explique ce que fait le Débogueur A2A, comment connecter votre premier agent, à quoi ressemblent la requête et la réponse en coulisses, et comment il s'intègre aux outils de test de serveur MCP existants d'Apidog. Si vous avez d'abord besoin du contexte du protocole en amont, Apidog propose une lecture plus approfondie sur MCP vs A2A qui se marie bien avec cet article.
Ce qu'est l'A2A (en un paragraphe)
A2A, abréviation d'Agent2Agent, est un protocole ouvert pour la communication inter-agents. Il définit comment un agent annonce ses capacités (la Carte d'Agent), comment un autre agent s'y connecte, comment les messages et les pièces jointes sont échangés, et comment le statut des tâches est rapporté. Considérez-le comme le HTTP pour le trafic d'agent à agent : une spécification légère et neutre vis-à-vis des fournisseurs qui permet à un agent LangGraph de votre pipeline de données d'interroger un agent CrewAI appartenant à une autre équipe sans que l'une ou l'autre partie ne connaisse les détails internes de l'autre.
Il est distinct du MCP (Model Context Protocol), qui consiste à donner à un agent unique l'accès à des outils et des ressources. L'A2A concerne la communication entre agents. Le comparatif MCP vs A2A est la lecture la plus claire sur la différence.
Ce que vous offre le débogueur A2A
Le débogueur A2A est intégré à Apidog. C'est un environnement de travail visuel pour tester les points d'accès A2A avant de les intégrer dans un flux de travail de production. Caractéristiques clés :
- Connexion de la Carte d'Agent. Collez une URL, cliquez sur Connecter, visualisez le nom de l'agent, sa description, ses capacités, ses compétences déclarées et la version du protocole. Si la carte est mal formée, la connexion échoue de manière explicite afin que vous puissiez corriger le manifeste plutôt que de chercher des problèmes fantômes.
- Envoi de messages. Composez du texte brut, joignez des fichiers (si les types d'entrée déclarés de l'agent les prennent en charge), et ajoutez des paires clé-valeur de métadonnées personnalisées.
- Trois vues de réponse. La vue Aperçu affiche la sortie structurée, la vue Contenu montre la charge utile lisible par l'homme, et la vue Données brutes décharge le JSON complet lorsque vous avez besoin de vérifier les noms de champs ou les caractères d'échappement.
- Authentification. Jeton Bearer, Authentification basique et Clé API via des en-têtes personnalisés, le tout dans l'interface utilisateur.
- En-têtes personnalisés. Ajoutez l'authentification de passerelle, les paramètres métier ou tout autre middleware que votre point d'accès A2A attend.
- Historique de session. Chaque message que vous envoyez est conservé dans un journal de session. Effacez-le lorsque vous démarrez un nouveau test.
Vous n'écrivez aucune commande curl. Apidog gère l'enveloppe JSON-RPC, le streaming SSE (lorsque l'agent le prend en charge) et l'analyse de la réponse.
Étape 1 : Connectez-vous à votre premier agent A2A
Vous avez besoin de trois choses avant d'ouvrir le débogueur :
- Apidog installé et mis à jour. La dernière version du client est requise ; les versions antérieures ne comprennent pas le débogueur A2A. Téléchargez Apidog si vous ne l'avez pas déjà.
- Une URL de Carte d'Agent. C'est le point d'entrée canonique pour tout agent conforme A2A. Pour le développement local, elle ressemble généralement à
http://localhost:3000/.well-known/agent.json; pour les agents hébergés, votre fournisseur de plateforme vous fournira le chemin. - Identifiants (si l'agent les requiert). Jeton Bearer, clé API ou authentification basique.
Ouvrez Apidog, accédez à la page du débogueur A2A et collez l'URL de la Carte d'Agent en haut. Cliquez sur Connecter. Si l'agent répond avec une Carte d'Agent valide, le statut passe à Connecté et le panneau se remplit avec les métadonnées de l'agent : nom, description, capacités, compétences déclarées, version du protocole.
En cas d'échec, les causes les plus courantes sont :
- L'URL est incorrecte ou l'agent ne fonctionne pas. Ouvrez l'URL dans un navigateur pour confirmer qu'une charge utile JSON est renvoyée.
- La Carte d'Agent manque de champs obligatoires. Comparez-la à la spécification du protocole A2A sur GitHub.
- L'agent attend une authentification sur le point de découverte. Ajoutez l'authentification dans Apidog avant de cliquer sur Connecter.
Étape 2 : Envoyez un message de test
Une fois connecté, ouvrez l'onglet Messages. Tapez une invite comme vous le feriez dans n'importe quelle interface de chat. Par exemple :
Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.
Ajouts facultatifs avant d'appuyer sur Envoyer :
- Pièce jointe. Cliquez sur le trombone et sélectionnez un fichier. Le débogueur vérifie les types d'entrée déclarés de l'agent et rejette les types de fichiers non pris en charge à l'avance, afin de ne pas gaspiller un aller-retour avec un code 415.
- Métadonnées personnalisées. Ajoutez des paires clé-valeur comme
priority: highoutenant: acme-corp. Celles-ci sont intégrées à l'enveloppe de la requête A2A et sont visibles par l'agent si son gestionnaire les lit.
Cliquez sur Envoyer. Apidog enveloppe votre invite dans la structure du message A2A, l'envoie à l'agent et attend la réponse.
Étape 3 : Lisez la réponse avec trois vues
Les réponses A2A peuvent être des chaînes de caractères simples, du JSON structuré, des références de fichiers, ou un mélange. Le débogueur vous offre trois angles de vue sur la même charge utile :
- Aperçu. Apidog affiche les champs structurés sous forme d'arbre. Utile lorsque l'agent renvoie des objets imbriqués (ID de tâche, statut, artefacts, historique).
- Contenu. Le corps lisible par l'homme. Si l'agent a renvoyé du texte, c'est ce que vous montrerez à un utilisateur. S'il a renvoyé un artefact structuré avec une partie
text/plain, c'est le texte extrait. - Données brutes. La charge utile JSON-RPC complète. C'est ce qu'il faut copier dans un rapport de bogue lorsque quelque chose ne va pas, et ce qu'il faut comparer à la spécification lorsque vous vérifiez la conformité.
Basculez entre les trois vues. Si l'Aperçu semble correct mais que le Contenu est vide, l'agent renvoie probablement un artefact typé qu'Apidog peut afficher mais qu'il ne sait pas comment aplatir. Si les Données brutes affichent un code d'erreur, l'agent a rejeté la requête et le message dans error.message est votre point de départ.
L'historique de session se trouve dans le panneau de gauche. Chaque envoi devient un tour auquel vous pouvez revenir. Cliquez sur Effacer lorsque vous démarrez un nouveau test et que vous ne voulez pas que du contexte obsolète perturbe l'agent.
Authentification : trois schémas courants
La plupart des points d'accès A2A en production sont protégés par un certain type d'authentification. Le débogueur gère d'emblée trois schémas :
Jeton Bearer
Le schéma le plus courant pour les agents hébergés. Dans le panneau d'authentification, sélectionnez Jeton Bearer et collez le jeton. Apidog ajoute Authorization: Bearer <token> à chaque requête.
Authorization: Bearer sk-agent-7f3e9a...
Authentification basique
Pour les agents protégés par un nom d'utilisateur et un mot de passe (courant avec les systèmes internes/hérités). Sélectionnez Authentification basique, entrez les deux valeurs, et Apidog calcule l'en-tête Authorization: Basic ... encodé en base64.
Clé API via un en-tête personnalisé
Lorsque l'agent attend un nom d'en-tête non standard comme X-Agent-Key, accédez à la section En-têtes et ajoutez-le manuellement. Le même flux s'applique pour tout en-tête spécifique à la passerelle (jetons CSRF, ID de locataire, signatures de requête).
Pour une réflexion à plus long terme sur l'hygiène des identifiants d'agent, le guide des identifiants d'agent IA d'Apidog couvre ce qu'il faut renouveler, ce qu'il faut cibler et ce qu'il ne faut jamais commettre.
En-têtes personnalisés et métadonnées : quand utiliser quoi
Deux emplacements contiennent des données "extra" sur une requête A2A. Ils semblent similaires mais se situent à des couches différentes :
| Canal | Où cela réside | Utilisation |
|---|---|---|
| En-têtes personnalisés | En-têtes de requête HTTP | Authentification de passerelle, observabilité (X-Request-Id), indicateurs de fonctionnalité |
| Métadonnées | Charge utile du message A2A | Contexte par message lu par l'agent (priorité, locataire, locale) |
Règle générale : si votre proxy inverse ou votre passerelle API a besoin de le voir, placez-le dans les en-têtes. Si le gestionnaire de tâches de l'agent en a besoin, placez-le dans les métadonnées. Les mélanger est la principale source de bugs du type "pourquoi l'agent a-t-il ignoré mon indice".
Débogueur A2A vs test de serveur MCP dans Apidog
Apidog propose à la fois un débogueur A2A et un flux de test MCP. Ce sont des outils différents pour des protocoles différents :
| Outil | Protocole | Tests | Utilisation |
|---|---|---|---|
| Débogueur A2A | Agent2Agent | Connectivité, échange de messages, statut de la tâche | Lors de la construction de systèmes multi-agents où les agents appellent d'autres agents |
| Test de serveur MCP | Model Context Protocol | Appels d'outils, accès aux ressources, modèles d'invite | Lors de la construction d'un serveur MCP qui expose des outils/ressources à un agent |
Si vous n'êtes pas sûr de ce dont vous avez besoin, le guide MCP vs A2A vous aide à prendre une décision. En bref : le MCP est ce qu'un agent utilise pour accéder aux systèmes externes. L'A2A est ce qu'un agent utilise pour parler à un autre agent.
Pour la partie MCP du flux de travail, le manuel de test du serveur MCP couvre les chemins manuels et automatisés dans Apidog. De nombreuses équipes finissent par utiliser les deux interfaces car les systèmes d'agents réels combinent la coordination A2A avec l'accès aux outils MCP.
Un modèle de débogage courant : le cycle complet d'une tâche
Lorsque vous êtes bloqué sur "l'agent ne répond pas comme je l'attends", suivez ce cycle :
- Ouvrez le débogueur A2A.
- Connectez-vous à l'agent. Confirmez que la Carte d'Agent affiche la compétence que vous attendez.
- Envoyez le plus petit message possible qui devrait déclencher cette compétence. Utilisez d'abord du texte brut ; ajoutez des fichiers et des métadonnées seulement après que le chemin de texte fonctionne.
- Lisez les Données brutes, et non l'Aperçu, la première fois. Vous voulez voir exactement ce que l'agent a émis.
- Si la réponse manque un champ que vous attendez, c'est un problème dans le code de l'agent, pas dans le transport.
- Si la réponse est bien formée mais incorrecte, c'est un problème d'invite ou de modèle, et vous avez déjà isolé le transport de la logique.
C'est la même boucle d'isolation-avant-culpabilité que celle que l'article Comment tester les agents IA qui appellent vos API applique au côté API. Même principe : confirmez le câblage d'abord, puis déboguez le cerveau.
Où cela s'intègre dans votre flux de travail IA
Les systèmes multi-agents sont la manière dont une grande partie du travail sérieux en IA sera livrée en 2026. L'article Les agents IA sont les nouveaux consommateurs d'API présente l'argumentation pour traiter le trafic des agents comme une priorité. Le suivi Concevoir des API pour les agents IA couvre les changements dans votre contrat API lorsque le consommateur est un agent piloté par LLM plutôt qu'un développeur humain.
Le débogueur A2A se situe au même niveau que le débogueur visuel client MCP d'Apidog. Les deux visent à vous donner une fenêtre sur le trafic qui est autrement caché à l'intérieur des SDK d'agents. Vous connectez votre agent, vous pouvez voir ce qu'il fait, vous corrigez les bugs avant qu'ils n'atteignent la production.
Apidog est gratuit à télécharger et le débogueur A2A est inclus avec le client standard ; pas de licence séparée, pas de plan séparé.
Questions fréquentes
Le débogueur A2A est-il gratuit ?
Oui. Il est fourni avec le client Apidog standard. Téléchargez Apidog et le débogueur A2A apparaîtra dans le panneau latéral une fois que vous utiliserez une version suffisamment récente.
Fonctionne-t-il avec des agents écrits dans n'importe quel framework ?
Il fonctionne avec tout agent exposant une Carte d'Agent A2A valide. Le protocole est agnostique au framework, donc LangGraph, CrewAI, AutoGen, et les agents Python ou Go personnalisés fonctionnent tous tant qu'ils respectent la spécification A2A.
Puis-je enregistrer les sessions pour les rejouer plus tard ?
Les sessions persistent tant que le débogueur est ouvert. Pour un stockage à long terme, copiez la sortie des Données brutes et enregistrez-la dans vos artefacts de test ; l'exportation complète des sessions est prévue sur la feuille de route.
Comment gère-t-il les réponses en streaming ?
Lorsque l'agent prend en charge le streaming SSE (selon la spécification A2A), le débogueur lit les morceaux au fur et à mesure de leur arrivée et met à jour l'Aperçu et le Contenu en temps réel. Les Données brutes affichent la réponse assemblée lorsque le flux se ferme.
Quelle est la différence entre le champ de métadonnées et la section des en-têtes ?
Les en-têtes sont au niveau HTTP ; les métadonnées sont au niveau du message A2A. Les en-têtes atteignent la passerelle et le proxy inverse ; les métadonnées atteignent le gestionnaire de tâches de l'agent. Voir le tableau plus haut dans cet article.
Apidog enregistre-t-il les réponses de l'agent sur ses serveurs ?
Non. Apidog fonctionne comme un client local. Le trafic entre votre machine et l'agent ne transite pas par l'infrastructure Apidog.
Puis-je utiliser le débogueur A2A pour tester un agent hébergé sur un réseau différent ?
Oui, tant que le chemin réseau est ouvert. Le débogueur effectue des requêtes HTTPS sortantes comme le ferait n'importe quel client HTTP. Si votre agent est derrière un VPN, vous devrez activer ce VPN.
Où puis-je signaler des bugs ou demander des fonctionnalités ?
Le canal de feedback d'Apidog est la voie principale ; le référentiel GitHub du protocole A2A est l'endroit où la spécification en amont évolue, donc les demandes de niveau spécification y ont leur place.
Essayez maintenant
Choisissez l'agent A2A le plus simple auquel vous avez accès. Si vous n'en avez pas encore, les implémentations de référence A2A incluent un serveur d'exemple que vous pouvez exécuter localement en moins de cinq minutes. Collez l'URL de sa Carte d'Agent dans le débogueur A2A d'Apidog, envoyez un message "bonjour", et regardez les trois vues de réponse se remplir. C'est la plus petite boucle de bout en bout, et à partir de là, vous pouvez passer à de véritables invites, des pièces jointes et des flux de travail multi-agents.
Associez le débogueur à Apidog pour le reste de votre travail API et MCP, et vous disposez d'une interface unique pour les trois protocoles sur lesquels fonctionnent les systèmes d'agents : HTTP, MCP et A2A.
bouton