Tutoriel JSON Schema Agent Card A2A : nom, capacités, skills, interfaces et endpoint

Pour qui est cette carte

Une Agent Card est la carte de visite publique qu’un serveur A2A accroche à /.well-known/agent-card.json. Le lecteur n’est pas votre modèle. C’est un autre orchestrateur, une passerelle, ou un catalogue interne. La carte répond à trois phrases : qui vous êtes, comment vous joindre, ce que vous prétendez traiter. D’abord name / description / version. Ensuite supportedInterfaces. Puis skills[]. Verser un runbook dans description heurte d’abord le plafond 10 Ko ; la surface de découverte maigrit.

La 1.0 durcit le requis. La table de spec marque name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes et skills comme Yes. Il en manque un : un client 1.0 ne doit pas traiter le fichier comme une carte légale. La 0.3 vivait d’url et protocolVersion au sommet. Un client 1.0 les ignore et lit le tableau d’interfaces. Mélanger les deux jeux : l’extraction catalogue maigrit en silence ; le ticket dit encore « introuvable ».

La carte n’est pas un Plugin Manifest, ni un tools/list MCP. Comment un agent de code fait pousser des skills : l’article Plugin. Comment un hop d’appel vérifie les arguments : MCP et JSON Schema. Aujourd’hui, seulement comment un collègue de côté se décrit. Signatures, cartes étendues et GetExtendedAgentCard viennent après auth. La carte publique doit d’abord nommer les skills.

Identité : name, description, version, provider

name est pour les humains qui scannent un catalogue, pas un nom de service interne. description dit le périmètre et une bordure : ce que vous faites, et ce que vous ne ferez pas. Un spécialiste retours peut écrire « classe les demandes de retour ; n’enregistre pas les remboursements ». Les orchestrateurs décident d’envoyer une Task d’après ce paragraphe, pas d’après le README.

version est la release de cet agent, par exemple 1.0.3. La version de protocole voyage avec l’interface, dans supportedInterfaces[].protocolVersion. Écrire 1.0 aux deux endroits : plus tard on ne sait plus quel côté a bougé. provider est optionnel, mais s’il est là c’est une paire : organization plus url. documentationUrl et iconUrl aussi optionnels ; le long texte va à l’URL docs, pas dans la carte.

S’arrêter après le bloc identité. Sans interfaces, la carte n’est pas appelable. Sans skills, le catalogue ne vous trouve pas. Garder la première des trois phrases courte et vraie, puis remplir les endpoints.

Interfaces : l’endpoint est supportedInterfaces

En 1.0 l’endpoint primaire n’est pas au sommet. supportedInterfaces est un tableau ordonné ; la première entrée est préférée. Chaque item exige url, protocolBinding et protocolVersion. L’url de prod doit être un HTTPS absolu. Les bindings cœur officiels : JSONRPC, GRPC, HTTP+JSON ; la spec laisse la chaîne ouverte pour des extensions. tenant est optionnel — seulement en multi-tenant.

Un agent peut lister trois bindings sur trois URL. Les clients prennent le premier qu’ils parlent, dans l’ordre du tableau. Ne pointez pas les trois vers le même 404 pour faire complet. L’url de sommet 0.3 plus protocolVersion est l’ancien contrat ; la page des changements v1.0 dit qu’ils ne sont plus primaires. S’enregistrer en 1.0 avec l’URL en haut : la validation 1.0 doit échouer, ou l’endpoint primaire est ignoré.

Le tableau d’interfaces décide comment vous parlez, pas ce que vous traitez. JSONRPC sans skills : joignable, pas cherchable. Skills sans interfaces : cherchable, pas de Task. Les deux blocs doivent être là.

Capabilities et MIME par défaut

capabilities est un objet requis en 1.0 ; les booléens dedans sont optionnels : streaming, pushNotifications, extendedAgentCard, plus un tableau extensions. Absent ou false : l’opération correspondante doit échouer, pas réessayer en silence. Ne ramenez pas stateTransitionHistory de 0.3 comme capacité cœur. La table 4.4.3 ne le liste plus.

defaultInputModes et defaultOutputModes sont des tableaux de types média pour chaque skill. Un skill peut surcharger avec inputModes / outputModes. Texte seul : text/plain. JSON en sortie : ajoutez application/json. Un tableau vide est non déclaré ; la validation 1.0 doit échouer. Pas d’extensions de fichier ni d’enums privés.

extendedAgentCard vrai signifie qu’une seconde carte plus riche peut être fetchée après auth. La carte publique doit quand même tenir seule : skills, interfaces, MIME par défaut. Cacher un skill critique seulement sur la carte étendue : les catalogues non authentifiés vous ratent sur la surface de recherche.

skills[] : id, tags, examples

Chaque skill exige id, name, description et tags. id est une clé programmatique stable et courte — pas d’espaces. name est pour les humains. description pose les bornes I/O ; ce n’est toujours pas un schéma d’arguments. tags est un tableau de chaînes requis en 1.0, pour le catalogue et l’orchestrateur. Google Registry indexe aussi les tags. Vide ou omis : le fichier peut parser, personne ne vous trouve.

examples sont des prompts ou scènes optionnels pour les humains, pas du JSON Schema. La 1.0 ne traite pas inputSchema comme contrat de skill. D’anciennes implémentations accrochent encore un schéma ; indice OK, contrat tools/call non. En face, un agent opaque ; vous envoyez une Task. Le fragment 0.3 du site qui met inputSchema sur un skill est l’ancien contrat. Ne le copiez pas dans une nouvelle carte.

Ne découpez pas les skills par nom de fonction interne. Un skill est un type de travail qu’un orchestrateur déléguerait. Un spécialiste retours peut exposer classify-return et check-window — pas « lire la table », « écrire un log », « envoyer un mail » comme trois termes de recherche. Ci-dessous une carte 1.0 commitable. Parsez-la, puis le schéma officiel.

{
  "name": "Returns Specialist",
  "description": "Classifies return requests and checks the return window. Does not post refunds.",
  "version": "1.0.3",
  "provider": {
    "organization": "Example Commerce",
    "url": "https://commerce.example.com"
  },
  "documentationUrl": "https://docs.example.com/returns-agent",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/returns/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    },
    {
      "url": "https://agents.example.com/returns/a2a/json",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "classify-return",
      "name": "Classify a return",
      "description": "Decide whether a request is a return, exchange, or warranty claim.",
      "tags": ["returns", "classify", "commerce"],
      "examples": ["This jacket arrived damaged. Is it a return or a warranty claim?"]
    },
    {
      "id": "check-window",
      "name": "Check return window",
      "description": "Say whether the purchase is still inside the return window.",
      "tags": ["returns", "policy", "deadline"],
      "examples": ["Order 8841 was delivered on 2026-08-02. Can they still return it?"]
    }
  ]
}

Ce qui ne doit pas entrer dans une carte 1.0

Gardez au moins un négatif : url encore au sommet, un skill sans tags, plus un inputSchema façon MCP. La validation 1.0 doit échouer. Si la CI écrase 0.3 et 1.0 en un « check agent générique », vous êtes plus sales que le client. Le Registry choisit les règles selon la version déclarée et ne fetch pas un schéma au chargement.

{
  "name": "Returns Specialist",
  "description": "Classifies return requests.",
  "version": "1.0.3",
  "url": "https://agents.example.com/returns/a2a",
  "protocolVersion": "1.0",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/returns/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {
    "streaming": true,
    "stateTransitionHistory": true
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "classify-return",
      "name": "Classify a return",
      "description": "Decide the request type.",
      "inputSchema": {
        "type": "object",
        "required": ["orderId"],
        "properties": {
          "orderId": { "type": "string" }
        }
      }
    }
  ]
}

securitySchemes et les exigences de sécu sont une couche optionnelle. Une carte publique peut partir sans signatures. signatures sont du JWS ; la marche de vérif est l’article pratique. Retenez : une signature ne remplace pas tags. Une carte honnête avec un vrai skill bat une jolie carte à tableau de skills vide. skills reste un tableau requis — zéro item seulement si vous n’en avez vraiment aucun.

Ne copiez pas les champs Plugin fermés, les chemins SKILL.md ni les tools[].name MCP dans la Card. Trois JSON disent « capacité » ; le traitement d’échec diffère. Une Card pourrie est un échec de découverte.

Dans le navigateur :Formateur JSON pour voir si la carte parse ;Validateur JSON Schema pour 1.0 supportedInterfaces et skills[].tags ;JSON Diff pour attraper url de sommet / tags manquants entre carte commitée et négatif. Rien ne quitte la machine. Pour aller plus loin :aperçu Agent Registry, et A2A vs MCP. La marche de découverte est l’article suivant.

Liés : Google Agent Registry, A2A vs MCP, MCP et JSON Schema.

FAQ

À retenir et suite

En 2026 une Agent Card A2A se plie en une table requise : trois champs d’identité, un tableau d’interfaces, un objet capabilities, des MIME par défaut, des skills avec tags. Les orchestrateurs lisent ces champs, pas votre slide d’archi.

Ordre : une carte 1.0 légale ; la première interface est un vrai endpoint ; chaque skill a des tags non vides ; parse et schéma dans JSONVue. Comment le catalogue consomme la carte : l’article d’avant. Les hops : le suivant. Signatures et checklist : plus tard.