Référence de schema · 14 fieldsA2A v1.0
Un Agent Card est le document JSON standardisé qui indique aux clients A2A qui est un agent, où le joindre, ce qu'il peut faire, et comment l'accès est sécurisé. Cette référence couvre chaque champ v1.0 avec les types, exigences, exemples, et les erreurs que les validateurs détectent le plus souvent.
Comment fonctionne la découverte
Un client A2A récupère la Agent Card depuis l'URI well-known, évalue les skills, capacités, et exigences de sécurité par rapport à sa tâche, puis appelle l'interface préférée — la première entrée dans supportedInterfaces. Si capabilities.extendedAgentCard est true, les clients authentifiés peuvent demander une Agent Card plus riche via l'opération GetExtendedAgentCard.
La spécification enregistre /.well-known/agent-card.json comme emplacement standard. Les déploiements v0.x plus anciens utilisaient /.well-known/agent.json, c'est pourquoi notre validateur vérifie les deux.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Référence des champs
Les indicateurs obligatoires suivent les définitions protobuf v1.0 de la spécification officielle. Les liens d'ancrage rendent chaque champ citable depuis les issues, revues, et sorties CI.
Nom lisible par un humain de l'agent.
Affiché dans les listes de marketplace et les interfaces client. Gardez-le court et spécifique — les clients l'utilisent comme étiquette principale lors de la comparaison d'agents candidats.
Erreur courante : Utiliser un nom générique comme « AI Assistant » qui ne donne aux systèmes de routage rien pour différencier.
"name": "Agent de planification d'itinéraire géospatial"
Ce que fait l'agent et quand un autre agent devrait l'appeler.
C'est le principal signal en texte libre pour les intégrateurs humains et les routeurs basés sur LLM décidant si votre agent convient à une tâche. Indiquez le domaine de la tâche, les capacités clés, et les limites.
Erreur courante : Descriptions d'une ligne de moins de 20 caractères. Les routeurs ne peuvent pas faire correspondre ce que vous ne décrivez pas.
"description": "Fournit des services avancés de planification d’itinéraire, d’analyse du trafic et de génération de cartes personnalisées."
Liste ordonnée des endpoints et bindings de protocole. La première entrée est préférée.
Nouveau dans v1.0 : remplace les anciens champs de premier niveau url, preferredTransport, et additionalInterfaces. Chaque entrée déclare son propre url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, ou une URI de binding personnalisée), protocolVersion, et une clé de routage de locataire optionnelle — ainsi un agent peut servir plusieurs versions de protocole et transports simultanément.
Erreur courante : Déclarer un binding que le serveur ne sert pas réellement à cette URL — la spécification exige que chaque entrée soit exacte.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Qui exploite l'agent : organisation et site web.
Signal de confiance pour les marketplaces et audits d'entreprise. v1.0 a renommé le champ name en organization ; url est requis dans l'objet lorsqu'il est présent.
Erreur courante : Utiliser encore provider.name (pré-1.0). Les validateurs lisant les Agent Cards v1.0 ne le reconnaîtront pas.
"provider": {
"organization": "Exemple Géo Services Inc.",
"url": "https://www.examplegeoservices.com"
}La version de l'agent lui-même, pas du protocole.
Permet aux clients de détecter quand une Agent Card a matériellement changé et de réévaluer la compatibilité. Suivez votre propre schéma de version, généralement semver.
Erreur courante : Confondre ceci avec la version du protocole A2A — elle réside maintenant sur chaque entrée supportedInterfaces.
"version": "1.2.0"
Lien vers la documentation lisible par un humain pour l'agent.
Donne aux intégrateurs un endroit pour lire le contrat API complet, les limites de débit, et les conditions qui n'ont pas leur place dans un document de découverte.
Erreur courante : Pointer vers une page d'accueil marketing plutôt que vers la documentation technique.
"documentationUrl": "https://docs.example.com/agent"
Indicateurs de fonctionnalités du protocole : streaming, pushNotifications, extensions, extendedAgentCard.
Les clients NE DOIVENT PAS appeler des fonctionnalités que vous n'avez pas déclarées — les appels de streaming non déclarés renvoient des erreurs. extendedAgentCard : true annonce une Agent Card authentifiée plus riche via l'opération GetExtendedAgentCard. v1.0 a supprimé stateTransitionHistory.
Erreur courante : Déclarer streaming : true alors que le serveur n'a pas d'endpoint de streaming. Les clients l'appelleront et échoueront.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Schémas d'authentification nommés : clé API, authentification HTTP, OAuth 2.0, OpenID Connect, ou TLS mutuel.
Chaque schéma nommé enveloppe un objet de schéma concret (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Les clients découvrent comment s'authentifier à partir d'ici — les identifiants eux-mêmes sont toujours obtenus hors bande.
Erreur courante : Intégrer une véritable clé API ou un jeton dans la Agent Card. Un Agent Card est un document public.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Quels schémas déclarés (et scopes) sont requis pour appeler l'agent.
Chaque entrée associe un nom de schéma de securitySchemes aux scopes dont il a besoin, reflétant le modèle d'exigence de sécurité OpenAPI. Omettez entièrement les deux champs pour les agents intentionnellement publics.
Erreur courante : Déclarer securitySchemes mais sans exigences de security, laissant les clients deviner si l'authentification est appliquée.
"security": [{ "google": ["openid", "profile", "email"] }]Types de médias que l'agent accepte pour toutes les skills.
Types MIME standard comme text/plain, application/json, ou image/png. Les skills individuelles peuvent remplacer avec leurs propres inputModes.
Erreur courante : Omettre le champ. Il est requis en v1.0 — les clients en ont besoin pour façonner les requêtes.
"defaultInputModes": ["application/json", "text/plain"]
Types de médias que l'agent renvoie pour toutes les skills.
Indique aux appelants s'il faut s'attendre à du texte, du JSON structuré, des images, ou des fichiers. Les skills peuvent remplacer par skill avec outputModes.
Erreur courante : Ne lister que text/plain alors que l'agent renvoie en fait des artefacts structurés.
"defaultOutputModes": ["application/json", "image/png"]
Les capacités concrètes dans lesquelles l'agent est susceptible de réussir.
Chaque skill nécessite id, name, description, et tags ; examples, modes par skill, et sécurité par skill sont optionnels. Les skills sont l'unité de découverte — les routeurs font correspondre les tâches à celles-ci, donc limitez chacune à une seule limite de tâche.
Erreur courante : Skills sans tags. Les tags sont devenus obligatoires en v1.0 et pilotent la correspondance au niveau des skills.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Optimiseur d'itinéraire sensible au trafic",
"description": "Calcule les itinéraires de conduite optimaux en utilisant le trafic en temps réel...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Planifiez un itinéraire de A à B en évitant les péages."]
}]Signatures JSON Web prouvant que la Agent Card a été émise par le fournisseur.
Chaque signature porte un en-tête JWS protégé base64url et une valeur de signature, calculés sur la Agent Card canonicalisée RFC 8785 (JCS). Les clients DEVRAIENT vérifier au moins une signature avant de faire confiance à une Agent Card récupérée depuis le web ouvert.
Erreur courante : Signer la carte puis modifier un champ quelconque — même des changements de valeur insignifiants en espaces blancs invalident le JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL vers une icône représentant l'agent.
Utilisé par les catalogues et interfaces client. Servez-la via HTTPS depuis un emplacement stable.
Erreur courante : Lier une icône sur un domaine différent et non fiable qui peut changer sans préavis sous votre annonce.
"iconUrl": "https://agent.example.com/icon.png"
Migration de version
Si votre Agent Card a encore un url ou preferredTransport de premier niveau, elle est antérieure à v1.0. Le validateur signale automatiquement chacun d'eux.
| Champ v0.x | Remplacement v1.0 | Pourquoi ça a changé |
|---|---|---|
| url | supportedInterfaces[0].url | Le endpoint préféré est maintenant simplement la première entrée d'interface. |
| preferredTransport | supportedInterfaces[] ordering | La préférence est exprimée par l'ordre du tableau plutôt que par un champ séparé. |
| additionalInterfaces | supportedInterfaces[] | Toutes les interfaces vivent dans un seul tableau ordonné. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Chaque interface déclare sa propre version de protocole, permettant la prise en charge multi-versions. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Déplacé dans l'objet capabilities ; le RPC a été renommé GetExtendedAgentCard. |
| provider.name | provider.organization | Renommé pour plus de clarté. |
| capabilities.stateTransitionHistory | — removed | Ne fait pas partie de v1.0 ; modélisez un comportement équivalent comme une extension si nécessaire. |
Code passe-partout
Déposez ces interfaces dans un client, serveur, ou vérification CI pour analyser et produire des Agent Cards avec sécurité de type. Elles reflètent les définitions protobuf du dépôt officiel de la spécification, sous la forme JSON camelCase dans laquelle les Agent Cards sont publiées.
Vous construisez plutôt une Agent Card à la main ? Le générateur produit exactement cette forme.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Intégrité
Parce que les Agent Cards sont récupérées depuis le web ouvert, v1.0 formalise la signature : la Agent Card (moins le champ signatures et les valeurs par défaut) est canonicalisée avec RFC 8785 JSON Canonicalization, puis signée comme un JWS. Les clients devraient vérifier au moins une signature — via l'en-tête kid/jku ou un magasin de clés de confiance — avant d'agir sur une Agent Card. Plusieurs signatures prennent en charge la rotation de clés.
Servez la Agent Card sur /.well-known/agent-card.json via HTTPS.
Chaque entrée supportedInterfaces est accessible et parle le binding déclaré.
Les skills ont des tags obligatoires plus des descriptions avec des limites de tâche claires.
Les capabilities déclarées correspondent au serveur — les fonctionnalités non déclarées doivent renvoyer des erreurs, celles déclarées doivent fonctionner.
securitySchemes décrit comment s'authentifier ; aucune information d'identification n'apparaît nulle part dans la Agent Card.
version est incrémenté chaque fois que le contenu de la Agent Card change.
Un agent de support client avec OAuth 2.0, streaming, et notifications push — tous les champs requis présents. Plus de modèles se trouvent dans la bibliothèque d'exemples.
{
"name": "Agent de Support Client",
"description": "Répond aux questions du support client, récupère le contexte de la commande et transmet les problèmes non résolus à une équipe humaine.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Exemple Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Résoudre la demande de support client",
"description": "Classifie une demande d'assistance client, rassemble le contexte nécessaire, propose une résolution et escalade lorsque la confiance est faible.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Aidez-moi à retourner ma commande."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}FAQ
Les changements de version, champs de découverte, et détails de publication qui décident si une Agent Card passe la revue.
v1.0 a consolidé url, preferredTransport, et additionalInterfaces en un seul tableau ordonné supportedInterfaces où chaque entrée déclare son propre url, protocolBinding, et protocolVersion. supportsAuthenticatedExtendedCard est passé à capabilities.extendedAgentCard, provider.name est devenu provider.organization, les tags de skill sont devenus obligatoires, et les signatures de Agent Card JWS ont été formalisées avec la canonicalisation RFC 8785.
Non. Un Agent Card est un document de découverte pour un agent. Il résume l'identité, les interfaces, capacités, skills, modes, fournisseur, et métadonnées de sécurité, tandis qu'un schema d'API complet décrit les formes détaillées de requête et réponse. Il joue le rôle qu'un README ou un aperçu OpenAPI joue pour un service : suffisant pour décider si et comment l'appeler.
name, description, supportedInterfaces, skills (avec tags), defaultInputModes, defaultOutputModes, capabilities, provider, et métadonnées de sécurité. Les systèmes de routage font correspondre les tâches à votre description et vos tags de skill, puis utilisent les interfaces et capacités pour planifier l'appel réel.
Ne publiez que des skills sûres pour la découverte non authentifiée. Si une Agent Card privée plus riche est nécessaire, définissez capabilities.extendedAgentCard sur true et exposez les skills sensibles via l'opération authentifiée GetExtendedAgentCard.
À l'URI well-known https://{votre-domaine}/.well-known/agent-card.json, servi avec le type de contenu application/a2a+json (application/json fonctionne aussi en pratique). Les implémentations antérieures utilisaient /.well-known/agent.json, donc publier les deux pendant la transition est un choix pragmatique.
Mettez le schema au travail
Générez une Agent Card au format v1.0 à partir des détails de votre service, ou collez une Agent Card existante dans le validateur pour voir exactement quels champs nécessitent votre attention.