Schema referentie · 14 fieldsA2A v1.0
Een Agent Card is het gestandaardiseerde JSON-document dat A2A-clients vertelt wie een agent is, waar deze te bereiken is, wat deze kan doen, en hoe toegang wordt beveiligd. Deze referentie behandelt elk v1.0-veld met typen, vereisten, voorbeelden, en de fouten die validators het vaakst opsporen.
Hoe discovery werkt
Een A2A-client haalt de Agent Card op van de well-known URI, evalueert skills, capabilities, en beveiligingsvereisten tegen zijn taak, en roept dan de voorkeursinterface aan — de eerste vermelding in supportedInterfaces. Als capabilities.extendedAgentCard true is, kunnen geauthenticeerde clients een rijkere Agent Card aanvragen via de operatie GetExtendedAgentCard.
De specificatie registreert /.well-known/agent-card.json als de standaardlocatie. Oudere v0.x-implementaties gebruikten /.well-known/agent.json, daarom controleert onze validator beide.
# 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" }
],
...
}Veldreferentie
Verplichte vlaggen volgen de v1.0 protobuf-definities in de officiële specificatie. Ankerlinks maken elk veld citeerbaar vanuit issues, reviews, en CI-uitvoer.
Door mensen leesbare naam van de agent.
Wordt getoond in marketplace-vermeldingen en client-UI's. Houd het kort en specifiek — clients gebruiken het als primair label bij het vergelijken van kandidaat-agenten.
Veelgemaakte fout: Een generieke naam zoals "AI Assistant" gebruiken die routingsystemen niets geeft om op te onderscheiden.
"name": "GeoSpatial Routeplanner-agent"
Wat de agent doet en wanneer een andere agent hem zou moeten aanroepen.
Dit is het belangrijkste vrijetekstsignaal voor zowel menselijke integratoren als LLM-gebaseerde routers die beslissen of jouw agent bij een taak past. Vermeld het taakdomein, kernvaardigheden, en grenzen.
Veelgemaakte fout: Beschrijvingen van één regel onder de 20 tekens. Routers kunnen niet matchen wat je niet beschrijft.
"description": "Biedt geavanceerde routeplanning, verkeersanalyse en diensten voor het genereren van aangepaste kaarten."
Geordende lijst van endpoints en protocolbindingen. De eerste vermelding heeft de voorkeur.
Nieuw in v1.0: vervangt de oude top-level velden url, preferredTransport, en additionalInterfaces. Elke vermelding declareert zijn eigen url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, of een aangepaste binding-URI), protocolVersion, en een optionele tenant-routeersleutel — zodat één agent meerdere protocolversies en transporten tegelijk kan bedienen.
Veelgemaakte fout: Een binding declareren die de server op die URL feitelijk niet bedient — de specificatie vereist dat elke vermelding accuraat is.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Wie de agent beheert: organisatie en website.
Vertrouwenssignaal voor marketplaces en bedrijfsaudits. v1.0 heeft het veld name hernoemd naar organization; url is verplicht binnen het object indien aanwezig.
Veelgemaakte fout: Nog steeds provider.name gebruiken (van vóór v1.0). Validators die v1.0-Agent Card lezen zullen het niet herkennen.
"provider": {
"organization": "Voorbeeld Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}De versie van de agent zelf, niet van het protocol.
Stelt clients in staat te detecteren wanneer een Agent Card materieel is veranderd en compatibiliteit opnieuw te evalueren. Volg je eigen releaseschema, doorgaans semver.
Veelgemaakte fout: Dit verwarren met de A2A-protocolversie — die zich nu op elke supportedInterfaces-vermelding bevindt.
"version": "1.2.0"
Link naar door mensen leesbare documentatie voor de agent.
Geeft integratoren een plek om het volledige API-contract, snelheidslimieten, en voorwaarden te lezen die niet in een discovery-document thuishoren.
Veelgemaakte fout: Verwijzen naar een marketing-homepage in plaats van technische documentatie.
"documentationUrl": "https://docs.example.com/agent"
Protocolfunctie-vlaggen: streaming, pushNotifications, extensions, extendedAgentCard.
Clients MOGEN GEEN functies aanroepen die je niet hebt gedeclareerd — niet-gedeclareerde streaming-aanroepen retourneren fouten. extendedAgentCard: true kondigt een rijkere geauthenticeerde Agent Card aan via de operatie GetExtendedAgentCard. v1.0 heeft stateTransitionHistory verwijderd.
Veelgemaakte fout: streaming: true declareren terwijl de server geen streaming-endpoint heeft. Clients zullen het aanroepen en falen.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Benoemde authenticatieschema's: API-sleutel, HTTP-authenticatie, OAuth 2.0, OpenID Connect, of wederzijdse TLS.
Elk benoemd schema omhult één concreet schema-object (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Clients ontdekken hier hoe te authenticeren — de credentials zelf worden altijd out-of-band verkregen.
Veelgemaakte fout: Een daadwerkelijke API-sleutel of token in de Agent Card insluiten. Een Agent Card is een openbaar document.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Welke gedeclareerde schema's (en scopes) vereist zijn om de agent aan te roepen.
Elke vermelding koppelt een schemanaam uit securitySchemes aan de scopes die het nodig heeft, wat het OpenAPI-beveiligingsvereistepatroon weerspiegelt. Laat beide velden volledig weg voor bewust openbare agenten.
Veelgemaakte fout: securitySchemes declareren maar zonder security-vereisten, waardoor clients moeten raden of authenticatie wordt afgedwongen.
"security": [{ "google": ["openid", "profile", "email"] }]Mediatypen die de agent accepteert over alle skills.
Standaard MIME-typen zoals text/plain, application/json, of image/png. Individuele skills kunnen overschrijven met hun eigen inputModes.
Veelgemaakte fout: Het veld weglaten. Het is verplicht in v1.0 — clients hebben het nodig om verzoeken vorm te geven.
"defaultInputModes": ["application/json", "text/plain"]
Mediatypen die de agent retourneert over alle skills.
Vertelt aanroepers of ze proza, gestructureerde JSON, afbeeldingen, of bestanden moeten verwachten. Skills kunnen per skill overschrijven met outputModes.
Veelgemaakte fout: Alleen text/plain vermelden terwijl de agent in werkelijkheid gestructureerde artefacten retourneert.
"defaultOutputModes": ["application/json", "image/png"]
De concrete vaardigheden waarin de agent waarschijnlijk zal slagen.
Elke skill vereist id, name, description, en tags; examples, modi per skill, en beveiliging per skill zijn optioneel. Skills zijn de discovery-eenheid — routers matchen taken ertegen, dus beperk elke skill tot één taakgrens.
Veelgemaakte fout: Skills zonder tags. Tags werden verplicht in v1.0 en sturen matching op skillniveau aan.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Verkeersbewuste route-optimalisatie",
"description": "Berekent optimale rijroutes met behulp van realtime verkeer...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Plan een route van A naar B en vermijd tol."]
}]JSON Web Signatures die bewijzen dat de Agent Card is uitgegeven door de provider.
Elke handtekening bevat een base64url-beveiligde JWS-header en handtekeningwaarde, berekend over de RFC 8785 (JCS)-gecanoniseerde Agent Card. Clients ZOUDEN ten minste één handtekening moeten verifiëren voordat ze een Agent Card vertrouwen die van het open web is opgehaald.
Veelgemaakte fout: De kaart ondertekenen en vervolgens een willekeurig veld bewerken — zelfs onbeduidende waardewijzigingen in witruimte maken de JWS ongeldig.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL naar een icoon dat de agent vertegenwoordigt.
Gebruikt door catalogi en client-UI's. Serveer het via HTTPS vanaf een stabiele locatie.
Veelgemaakte fout: Een icoon koppelen op een ander, onbetrouwbaar domein dat achter je vermelding om kan veranderen.
"iconUrl": "https://agent.example.com/icon.png"
Versiemigratie
Als je Agent Card nog steeds een top-level url of preferredTransport heeft, dateert deze van vóór v1.0. De validator markeert elk van deze automatisch.
| v0.x-veld | v1.0-vervanging | Waarom het veranderde |
|---|---|---|
| url | supportedInterfaces[0].url | Het voorkeursendpoint is nu simpelweg de eerste interface-vermelding. |
| preferredTransport | supportedInterfaces[] ordering | Voorkeur wordt uitgedrukt door array-volgorde in plaats van een apart veld. |
| additionalInterfaces | supportedInterfaces[] | Alle interfaces bevinden zich in één geordende array. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Elke interface declareert zijn eigen protocolversie, wat multi-versie-ondersteuning mogelijk maakt. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Verplaatst naar het capabilities-object; de RPC werd hernoemd naar GetExtendedAgentCard. |
| provider.name | provider.organization | Hernoemd voor duidelijkheid. |
| capabilities.stateTransitionHistory | — removed | Geen onderdeel van v1.0; modelleer equivalent gedrag indien nodig als een extensie. |
Boilerplate
Zet deze interfaces in een client, server, of CI-check om Agent Cards met typeveiligheid te parseren en produceren. Ze weerspiegelen de protobuf-definities in de officiële specificatie-repository, in de camelCase JSON-vorm waarin Agent Card worden gepubliceerd.
Bouw je in plaats daarvan een Agent Card met de hand? De generator produceert precies deze vorm.
// 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> }Integriteit
Omdat Agent Cards van het open web worden opgehaald, formaliseert v1.0 ondertekening: de Agent Card (minus het signatures-veld en standaardwaarden) wordt gecanoniseerd met RFC 8785 JSON Canonicalization, en vervolgens ondertekend als een JWS. Clients zouden ten minste één handtekening moeten verifiëren — via de kid/jku-header of een vertrouwde sleutelopslag — voordat ze op basis van een Agent Card handelen. Meerdere handtekeningen ondersteunen sleutelrotatie.
Serveer de Agent Card op /.well-known/agent-card.json via HTTPS.
Elke supportedInterfaces-vermelding is bereikbaar en spreekt de gedeclareerde binding.
Skills hebben verplichte tags plus beschrijvingen met duidelijke taakgrenzen.
Gedeclareerde capabilities komen overeen met de server — niet-gedeclareerde functies moeten fouten retourneren, gedeclareerde moeten werken.
securitySchemes beschrijft hoe te authenticeren; nergens in de Agent Card verschijnen credentials.
version wordt verhoogd telkens wanneer de Agent Card verandert.
Een klantenondersteuningsagent met OAuth 2.0, streaming, en pushmeldingen — alle verplichte velden aanwezig. Meer patronen staan in de voorbeeldbibliotheek.
{
"name": "Klantenondersteuningsagent",
"description": "Beantwoordt vragen over klantenondersteuning, haalt de bestelcontext op en escaleert onopgeloste problemen naar een menselijk team.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Voorbeeld 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": "Klantondersteuningsverzoek oplossen",
"description": "Classificeert een verzoek om klantenondersteuning, verzamelt de benodigde context, stelt een oplossing voor en escaleert wanneer het vertrouwen laag is.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Help mij mijn bestelling terug te sturen."
]
}
],
"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"
]
}
]
}Veelgestelde vragen
De versiewijzigingen, discovery-velden, en publicatiedetails die bepalen of een Agent Card de review doorstaat.
v1.0 heeft url, preferredTransport, en additionalInterfaces geconsolideerd in één geordende supportedInterfaces-array waarin elke vermelding zijn eigen url, protocolBinding, en protocolVersion declareert. supportsAuthenticatedExtendedCard verhuisde naar capabilities.extendedAgentCard, provider.name werd provider.organization, skill-tags werden verplicht, en JWS-Agent Card werden geformaliseerd met RFC 8785-canonisering.
Nee. Een Agent Card is een discovery-document voor een agent. Het vat identiteit, interfaces, capabilities, skills, modi, provider, en beveiligingsmetadata samen, terwijl een volledig API-schema gedetailleerde verzoek- en antwoordvormen beschrijft. Het speelt de rol die een README of OpenAPI-overzicht speelt voor een service: genoeg om te beslissen of en hoe je het aanroept.
name, description, supportedInterfaces, skills (met tags), defaultInputModes, defaultOutputModes, capabilities, provider, en beveiligingsmetadata. Routingsystemen matchen taken tegen je description en skill-tags, en gebruiken vervolgens interfaces en capabilities om de daadwerkelijke aanroep te plannen.
Publiceer alleen skills die veilig zijn voor niet-geauthenticeerde discovery. Als een rijkere private Agent Card nodig is, stel capabilities.extendedAgentCard in op true en stel gevoelige skills bloot via de geauthenticeerde operatie GetExtendedAgentCard.
Op de well-known URI https://{jouw-domein}/.well-known/agent-card.json, geserveerd met content type application/a2a+json (application/json werkt in de praktijk ook). Eerdere implementaties gebruikten /.well-known/agent.json, dus het publiceren van beide tijdens de overgang is een pragmatische keuze.
Zet het schema aan het werk
Genereer een v1.0-vormige Agent Card op basis van je servicedetails, of plak een bestaande Agent Card in de validator om precies te zien welke velden aandacht nodig hebben.