Outil de découverte · A2A v1.0

Vérifiez les URL de découverte A2A Agent Card

Les clients A2A découvrent un agent en récupérant son Agent Card JSON depuis une URL well-known. Testez les deux conventions de nommage sur un domaine réel et voyez exactement ce que reçoivent les clients.

Construit les deux URL de découverte candidates à partir du même domaine de base.

Récupère le JSON renvoyé et signale le code de statut et le type de contenu.

Analyse la réponse comme JSON d'Agent Card lorsque c'est possible.

Exécute des vérifications de préparation pour les interfaces, skills, fournisseur, modes, capacités et métadonnées de sécurité.

Vérifier un domaine d'agent public

Entrez un domaine de base. Le vérificateur récupère les deux chemins de découverte, analyse le JSON renvoyé, et exécute des vérifications de préparation de l'Agent Card.

Comment fonctionne la découverte

Une seule URL well-known démarre chaque intégration A2A.

Avant qu'un autre agent puisse appeler le vôtre, il récupère l'Agent Card depuis une URI well-known (RFC 8615) sur votre domaine, évalue les skills et les exigences de sécurité, puis appelle l'interface préférée. Si la Agent Card est absente, obsolète ou masquée derrière une redirection, l'intégration échoue avant même de commencer.

Ce site applique ce qu'il vérifie : AgentCard.net publie sa propre Agent Card sur les deux chemins, et l'exemple à droite est le document réel.

Voir notre Agent Card en direct

agentcard.net discovery

GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

Chemins de découverte

Deux conventions, une seule Agent Card.

Ouvrir le validateur complet

Standard A2A v1.0

/.well-known/agent-card.json

L'URI well-known enregistrée par la spécification A2A v1.0. Les nouveaux clients récupèrent d'abord ce chemin ; servez-le avec le type de contenu application/a2a+json.

Ancien (pré-v1.0)

/.well-known/agent.json

Utilisé par les premières implémentations A2A et les exemples de codelabs. De nombreux clients déployés ne vérifient encore que ce chemin, donc servir la même Agent Card ici est une stratégie de transition sûre.

Modèle de publication

Rendez la découverte d'Agent Card résiliente.

Les échecs de découverte sont rarement exotiques : une redirection, une page d'erreur mise en cache, ou un chemin déployé et l'autre oublié. Cette routine de publication maintient les deux conventions servant la même Agent Card à jour.

1
Publier sur le chemin standard
Servez l'Agent Card révisée sur /.well-known/agent-card.json en HTTPS sur le même domaine que le service A2A, avec le type de contenu application/a2a+json.
2
Refléter le chemin ancien
Renvoyez le document identique depuis /.well-known/agent.json tant que d'anciens clients circulent encore — des Agent Cards divergentes sur les deux chemins perturbent le routage.
3
Garder la Agent Card synchronisée
Chaque fois que les endpoints, skills, capacités ou l'authentification changent, mettez à jour la Agent Card, incrémentez son champ version, et redéployez les deux chemins ensemble.
4
Revérifier après chaque changement
Exécutez ce vérificateur après les déploiements, changements DNS, migrations de passerelle ou modifications de marketplace. Les échecs proviennent généralement de redirections, de pages d'erreur HTML, ou d'un chemin oublié.

FAQ

Questions fréquentes sur Well-known Agent JSON

Quoi publier, où le publier, et comment garder les clients des deux conventions fonctionnels.

Quel chemin d'Agent Card well-known dois-je utiliser ?

A2A v1.0 enregistre /.well-known/agent-card.json comme chemin de découverte standard. L'ancien /.well-known/agent.json précède la v1.0 mais est encore vérifié par de nombreux clients déployés, donc publier la même Agent Card sur les deux chemins est le choix pragmatique pendant la transition.

Les deux chemins doivent-ils renvoyer un JSON identique ?

Oui. Renvoyer le même Agent Card public depuis les deux chemins maintient la cohérence pour les clients ne supportant qu'une seule convention. Des documents divergents font paraître l'agent différent selon le chemin récupéré par le client.

Avec quel type de contenu l'Agent Card doit-il être servi ?

La spécification enregistre application/a2a+json pour les Agent Cards. Un simple application/json est largement accepté en pratique, mais un type de contenu HTML est un signe fiable que le chemin renvoie une page d'erreur plutôt que la Agent Card.

L'Agent Card public peut-il masquer des capacités privées ?

Oui. Publiez uniquement des métadonnées sûres pour la découverte dans la Agent Card publique, définissez capabilities.extendedAgentCard sur true, et exposez les skills sensibles via l'opération authentifiée GetExtendedAgentCard.

Pourquoi les vérifications de découverte échouent-elles après un déploiement ?

Les causes habituelles sont des redirections vers une page de connexion ou marketing, des pages HTML 404 renvoyées avec le statut 200, du JSON obsolète mis en cache par un CDN, ou un seul des deux chemins well-known déployé. Le vérificateur signale le code de statut et le type de contenu pour chaque chemin, rendant l'échec visible immédiatement.

Avant de publier

Validez la Agent Card, puis vérifiez les URL.

Faites d'abord passer le JSON dans le validateur complet, publiez-le sur les deux chemins well-known, et confirmez la découverte avec ce vérificateur.

Ouvrir le validateur Générer une Agent Card