Antoine Laurent

Posted on May 15 • Originally published at apidog.com

Comment Déboguer le Protocole Agent-to-Agent (A2A) avec le Débogueur A2A d'Apidog

Si vous construisez des agents IA qui communiquent avec d'autres agents IA, le premier blocage est souvent l'observabilité : difficile de voir exactement ce qu'un agent envoie, reçoit et interprète. Les journaux de console sont incomplets, les onglets réseau masquent souvent les champs structurés, et les scripts de test maison deviennent vite fragiles. Le Débogueur A2A d'Apidog fournit une boucle de test directe pour le protocole Agent2Agent (A2A) : collez une URL de Carte d'Agent, cliquez sur Connecter, envoyez un message, puis inspectez la réponse dans trois vues.

Essayez Apidog aujourd’hui

Ce guide montre comment utiliser le Débogueur A2A, connecter un premier agent, envoyer une requête de test, lire la réponse brute, gérer l'authentification et l'intégrer à vos tests MCP existants dans Apidog. Si vous avez besoin du contexte protocolaire, commencez par le guide MCP vs A2A d'Apidog, puis revenez à cette procédure.

Ce qu'est l'A2A en bref

A2A, pour Agent2Agent, est un protocole ouvert pour la communication entre agents. Il définit comment un agent publie ses capacités via une Carte d'Agent, comment un autre agent s'y connecte, comment les messages et pièces jointes sont échangés, et comment l'état des tâches est rapporté.

Vous pouvez le voir comme une couche de transport standardisée pour les échanges agent-à-agent. Par exemple, un agent LangGraph dans un pipeline de données peut appeler un agent CrewAI géré par une autre équipe sans connaître son implémentation interne.

A2A est différent du MCP, ou Model Context Protocol. Le MCP sert à connecter un agent à des outils, ressources ou prompts. L'A2A sert à connecter des agents entre eux. Pour comparer les deux usages, consultez le comparatif MCP vs A2A.

Ce que permet le Débogueur A2A

Le Débogueur A2A est intégré à Apidog. Il sert à tester un point d'accès A2A avant de l'intégrer dans un workflow multi-agent.

Fonctionnalités principales :

Connexion via Carte d'Agent : collez l'URL de la carte, connectez-vous, puis vérifiez le nom, la description, les capacités, les compétences déclarées et la version du protocole.
Validation rapide du manifeste : si la Carte d'Agent est mal formée, la connexion échoue explicitement, ce qui permet de corriger le manifeste plutôt que de déboguer un faux problème réseau.
Envoi de messages : saisissez du texte, ajoutez des fichiers si l'agent les accepte, et transmettez des métadonnées personnalisées.
Trois vues de réponse : utilisez l'aperçu structuré, le contenu lisible et les données brutes JSON-RPC.
Authentification intégrée : configurez un jeton Bearer, une authentification basique ou une clé API via en-tête personnalisé.
En-têtes personnalisés : ajoutez des valeurs attendues par une passerelle, un proxy ou un middleware.
Historique de session : revenez sur les messages envoyés pendant la session de test.

Vous n'avez pas besoin d'écrire de 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

Avant d'ouvrir le débogueur, préparez ces éléments :

Un client Apidog à jour

Les versions anciennes ne contiennent pas le Débogueur A2A. Si nécessaire, téléchargez Apidog.
Une URL de Carte d'Agent

C'est le point d'entrée standard d'un agent compatible A2A. En local, elle ressemble souvent à ceci :

   http://localhost:3000/.well-known/agent.json

Pour un agent hébergé, utilisez l'URL fournie par votre plateforme ou votre équipe d'infrastructure.

Des identifiants si l'agent est protégé Préparez le jeton Bearer, la clé API ou les identifiants d'authentification basique.

Ensuite :

Ouvrez Apidog.
Accédez au Débogueur A2A.
Collez l'URL de la Carte d'Agent.
Configurez l'authentification si nécessaire.
Cliquez sur Connecter.

Si l'agent répond avec une Carte d'Agent valide, le statut passe à Connecté. Le panneau affiche alors les métadonnées de l'agent : nom, description, capacités, compétences déclarées et version du protocole.

Dépanner une connexion échouée

Si la connexion échoue, vérifiez d'abord ces points :

URL incorrecte ou agent arrêté

Ouvrez l'URL dans un navigateur ou testez-la avec un client HTTP. Vous devez recevoir une charge utile JSON.
Carte d'Agent invalide

Comparez votre manifeste à la spécification A2A sur GitHub.
Authentification requise sur le point de découverte

Certains agents protègent aussi l'URL de la Carte d'Agent. Configurez l'authentification dans Apidog avant de cliquer sur Connecter.

Étape 2 : envoyez un message de test

Une fois connecté, ouvrez l'onglet Messages et envoyez une requête minimale. Commencez simple afin de valider le transport avant de tester la logique métier.

Exemple de message :

Summarize the last three customer feedback notes in our shared knowledge base, then draft a one-paragraph reply for the support team.

Avant de cliquer sur Envoyer, vous pouvez ajouter :

Une pièce jointe

Cliquez sur l'icône de trombone et sélectionnez un fichier. Le débogueur vérifie les types d'entrée déclarés par l'agent et bloque les fichiers non pris en charge avant l'envoi.
Des métadonnées personnalisées

Ajoutez des paires clé-valeur comme :

  priority: high
  tenant: acme-corp
  locale: fr-FR

Ces métadonnées sont intégrées à l'enveloppe de requête A2A. Elles seront visibles par l'agent si son gestionnaire les lit.

Cliquez ensuite sur Envoyer. Apidog construit la structure du message A2A, l'envoie à l'agent et attend la réponse.

Étape 3 : inspectez la réponse

Une réponse A2A peut contenir du texte, du JSON structuré, des références de fichiers, des artefacts ou un mélange de plusieurs formats. Le débogueur expose trois vues complémentaires.

Vue Aperçu

La vue Aperçu affiche les champs structurés sous forme d'arbre. Utilisez-la pour vérifier rapidement :

l'ID de tâche ;
le statut ;
les artefacts ;
les messages intermédiaires ;
l'historique ;
les champs imbriqués.

Vue Contenu

La vue Contenu affiche la partie lisible par un humain. Si l'agent renvoie du texte, c'est généralement cette sortie que vous pourriez afficher dans une interface utilisateur.

Si la réponse contient un artefact structuré avec une partie text/plain, Apidog affiche le texte extrait.

Vue Données brutes

La vue Données brutes affiche la charge utile JSON-RPC complète. C'est la vue à utiliser pour :

vérifier les noms exacts des champs ;
comparer la réponse à la spécification ;
repérer les erreurs d'échappement ;
copier une réponse dans un rapport de bug ;
confirmer si le problème vient du transport ou de la logique de l'agent.

Exemple de réflexe utile : lors du premier test, commencez par les Données brutes, pas par l'aperçu. Vous voyez ainsi exactement ce que l'agent a émis.

Si l'aperçu semble correct mais que le contenu est vide, l'agent renvoie probablement un artefact typé qu'Apidog peut afficher sous forme structurée, mais pas aplatir en texte.

Si les données brutes contiennent une erreur, commencez par le champ :

{
  "error": {
    "message": "..."
  }
}

L'historique de session se trouve dans le panneau de gauche. Chaque message envoyé devient un tour consultable. Cliquez sur Effacer quand vous démarrez un nouveau test afin d'éviter que du contexte obsolète influence l'agent.

Authentification : trois schémas courants

La plupart des points d'accès A2A en production sont protégés. Le débogueur prend en charge les schémas suivants.

Jeton Bearer

Utilisez ce mode pour les agents hébergés ou les environnements protégés par un token.

Dans le panneau d'authentification :

Sélectionnez Jeton Bearer.
Collez le jeton.
Envoyez la requête.

Apidog ajoute l'en-tête suivant à chaque requête :

Authorization: Bearer sk-agent-7f3e9a...

Authentification basique

Utilisez ce mode pour des agents internes ou des systèmes hérités protégés par nom d'utilisateur et mot de passe.

Dans Apidog :

Sélectionnez Authentification basique.
Saisissez le nom d'utilisateur.
Saisissez le mot de passe.

Apidog calcule automatiquement l'en-tête Authorization: Basic ... encodé en base64.

Clé API via en-tête personnalisé

Certains agents attendent un en-tête non standard, par exemple :

X-Agent-Key: your-api-key

Dans ce cas :

Ouvrez la section En-têtes.
Ajoutez le nom de l'en-tête.
Ajoutez sa valeur.
Relancez la connexion ou le message.

Le même mécanisme fonctionne pour des en-têtes de passerelle, des identifiants de locataire, des jetons CSRF ou des signatures de requête.

Pour aller plus loin sur la gestion des secrets côté agents, consultez le guide des identifiants d'agent IA d'Apidog.

En-têtes personnalisés ou métadonnées : lequel utiliser ?

Deux mécanismes permettent d'ajouter du contexte à une requête A2A, mais ils ne se situent pas au même niveau.

Canal	Où cela réside	Utilisation
En-têtes personnalisés	En-têtes HTTP	Authentification de passerelle, observabilité, `X-Request-Id`, feature flags
Métadonnées	Charge utile du message A2A	Contexte lu par l'agent : priorité, locataire, locale

Règle pratique :

si un proxy inverse, une passerelle API ou un middleware doit lire la valeur, utilisez un en-tête ;
si le gestionnaire de tâche de l'agent doit lire la valeur, utilisez les métadonnées.

Beaucoup de bugs du type “l'agent ignore mon indice” viennent d'une confusion entre ces deux couches.

Débogueur A2A vs test de serveur MCP dans Apidog

Apidog propose à la fois un débogueur A2A et un flux de test MCP. Les deux outils ciblent des protocoles différents.

Outil	Protocole	Ce que vous testez	Quand l'utiliser
Débogueur A2A	Agent2Agent	Connectivité, échange de messages, statut de tâche	Quand des agents appellent d'autres agents
Test de serveur MCP	Model Context Protocol	Appels d'outils, accès aux ressources, modèles de prompts	Quand un serveur MCP expose des outils ou ressources à un agent

En résumé :

le MCP permet à un agent d'accéder à des systèmes externes ;
l'A2A permet à un agent de parler à un autre agent.

Si vous hésitez entre les deux, le guide MCP vs A2A clarifie les cas d'usage.

Pour la partie MCP du workflow, le manuel de test de serveur MCP couvre les tests manuels et automatisés dans Apidog. Dans la pratique, de nombreuses équipes utilisent les deux : A2A pour la coordination entre agents, MCP pour l'accès aux outils.

Boucle de débogage recommandée

Quand un agent “ne répond pas comme prévu”, évitez de tout déboguer en même temps. Isolez d'abord le transport, puis la logique.

Procédure :

Ouvrez le Débogueur A2A.
Connectez-vous à l'agent.
Vérifiez que la Carte d'Agent expose bien la compétence attendue.
Envoyez le message le plus simple possible qui devrait déclencher cette compétence.
Commencez avec du texte brut uniquement.
Ajoutez les fichiers et les métadonnées seulement après validation du chemin texte.
Lisez d'abord les Données brutes.
Vérifiez si la réponse contient les champs attendus.
Si un champ manque, cherchez côté code de l'agent.
Si la réponse est bien formée mais incorrecte, cherchez côté prompt, modèle ou logique métier.

Cette approche reprend le même principe que dans l'article Comment tester les agents IA qui appellent vos API : valider le câblage avant de déboguer le raisonnement.

Où l'intégrer dans votre workflow IA

Les systèmes multi-agents rendent le trafic agent-à-agent aussi important que le trafic API classique. L'article Les agents IA sont les nouveaux consommateurs d'API explique pourquoi il faut traiter ce trafic comme un cas d'usage de premier niveau.

Le guide Concevoir des API pour les agents IA détaille aussi ce qui change quand le consommateur d'une API est un agent piloté par LLM plutôt qu'un développeur humain.

Le Débogueur A2A se place au même niveau que le débogueur visuel client MCP d'Apidog. Dans les deux cas, l'objectif est de rendre visible un trafic souvent caché dans les SDK d'agents.

Le workflow devient :

connecter l'agent ;
envoyer une requête minimale ;
inspecter la réponse brute ;
corriger le contrat, les métadonnées ou le code ;
répéter avant la mise en production.

Apidog est gratuit à télécharger, et le Débogueur A2A est inclus dans le client standard.

Questions fréquentes

Le Débogueur A2A est-il gratuit ?

Oui. Il est fourni avec le client Apidog standard. Téléchargez Apidog, puis ouvrez le panneau latéral dans une version récente du client.

Fonctionne-t-il avec des agents écrits dans n'importe quel framework ?

Oui, tant que l'agent expose une Carte d'Agent A2A valide. Le protocole est agnostique au framework. Des agents LangGraph, CrewAI, AutoGen, Python ou Go personnalisés peuvent donc être testés s'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 une conservation longue durée, copiez la sortie 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 le débogueur 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 les vues Aperçu et 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 les métadonnées et les 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 sont lus par la passerelle, le proxy ou le middleware.
Les métadonnées sont lues par le gestionnaire de tâche de l'agent.

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 tester un agent hébergé sur un autre réseau ?

Oui, si le chemin réseau est ouvert. Le débogueur effectue des requêtes HTTPS sortantes comme un client HTTP classique. Si votre agent est derrière un VPN, activez ce VPN avant de tester.

Où signaler des bugs ou demander des fonctionnalités ?

Utilisez le canal de feedback d'Apidog pour les demandes liées au produit. Pour les sujets de spécification, le référentiel GitHub du protocole A2A est l'endroit où suivre l'évolution du protocole.

Essayez maintenant

Prenez 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 quelques minutes.