Schema-Referenz · 14 fieldsA2A v1.0
Eine Agent Card ist das standardisierte JSON-Dokument, das A2A-Clients mitteilt, wer ein Agent ist, wo er erreichbar ist, was er kann, und wie der Zugriff gesichert ist. Diese Referenz behandelt jedes v1.0-Feld mit Typen, Anforderungen, Beispielen, und den Fehlern, die Validatoren am häufigsten erkennen.
Wie Discovery funktioniert
Ein A2A-Client ruft die Agent Card von der well-known URI ab, bewertet Skills, Capabilities, und Sicherheitsanforderungen anhand seiner Aufgabe, und ruft dann die bevorzugte Schnittstelle auf — den ersten Eintrag in supportedInterfaces. Wenn capabilities.extendedAgentCard true ist, können authentifizierte Clients über die Operation GetExtendedAgentCard eine reichhaltigere Agent Card anfordern.
Die Spezifikation registriert /.well-known/agent-card.json als Standardort. Ältere v0.x-Deployments verwendeten /.well-known/agent.json, weshalb unser Validator beide prüft.
# 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" }
],
...
}Feldreferenz
Pflichtkennzeichnungen folgen den v1.0-Protobuf-Definitionen in der offiziellen Spezifikation. Anker-Links machen jedes Feld aus Issues, Reviews, und CI-Ausgaben zitierbar.
Menschenlesbarer Name des Agenten.
Wird in Marketplace-Listen und Client-UIs angezeigt. Halte ihn kurz und spezifisch — Clients verwenden ihn als primäres Label beim Vergleich von Kandidatenagenten.
Häufiger Fehler: Einen generischen Namen wie „AI Assistant“ zu verwenden, der Routing-Systemen nichts zum Unterscheiden gibt.
"name": "GeoSpatial Routenplaner-Agent"
Was der Agent tut und wann ein anderer Agent ihn aufrufen sollte.
Dies ist das wichtigste Freitextsignal sowohl für menschliche Integratoren als auch für LLM-basierte Router, die entscheiden, ob dein Agent zu einer Aufgabe passt. Nenne die Aufgabendomäne, Kernfähigkeiten, und Grenzen.
Häufiger Fehler: Einzeilige Beschreibungen unter 20 Zeichen. Router können nicht zuordnen, was du nicht beschreibst.
"description": "Bietet erweiterte Routenplanung, Verkehrsanalyse und benutzerdefinierte Kartenerstellungsdienste."
Geordnete Liste von Endpunkten und Protokollbindungen. Der erste Eintrag wird bevorzugt.
Neu in v1.0: ersetzt die alten Top-Level-Felder url, preferredTransport, und additionalInterfaces. Jeder Eintrag deklariert seine eigene url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, oder eine benutzerdefinierte Binding-URI), protocolVersion, und einen optionalen Tenant-Routing-Schlüssel — sodass ein Agent mehrere Protokollversionen und Transporte gleichzeitig bedienen kann.
Häufiger Fehler: Eine Bindung zu deklarieren, die der Server unter dieser URL tatsächlich nicht bereitstellt — die Spezifikation verlangt, dass jeder Eintrag korrekt ist.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Wer den Agenten betreibt: Organisation und Website.
Vertrauenssignal für Marketplaces und Unternehmensaudits. v1.0 hat das Feld name in organization umbenannt; url ist innerhalb des Objekts erforderlich, wenn vorhanden.
Häufiger Fehler: Weiterhin provider.name (vor v1.0) zu verwenden. Validatoren, die v1.0-Agent Card lesen, erkennen es nicht.
"provider": {
"organization": "Beispiel Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Die Version des Agenten selbst, nicht des Protokolls.
Ermöglicht Clients zu erkennen, wenn sich eine Agent Card wesentlich geändert hat, und die Kompatibilität neu zu bewerten. Folge deinem eigenen Release-Schema, typischerweise semver.
Häufiger Fehler: Dies mit der A2A-Protokollversion zu verwechseln — die befindet sich jetzt in jedem supportedInterfaces-Eintrag.
"version": "1.2.0"
Link zu menschenlesbarer Dokumentation für den Agenten.
Gibt Integratoren einen Ort, um den vollständigen API-Vertrag, Ratenbegrenzungen, und Bedingungen zu lesen, die nicht in ein Discovery-Dokument gehören.
Häufiger Fehler: Auf eine Marketing-Homepage statt auf technische Dokumentation zu verweisen.
"documentationUrl": "https://docs.example.com/agent"
Protokoll-Feature-Flags: streaming, pushNotifications, extensions, extendedAgentCard.
Clients DÜRFEN KEINE Features aufrufen, die du nicht deklariert hast — nicht deklarierte Streaming-Aufrufe geben Fehler zurück. extendedAgentCard: true kündigt eine reichhaltigere authentifizierte Agent Card über die Operation GetExtendedAgentCard an. v1.0 hat stateTransitionHistory entfernt.
Häufiger Fehler: streaming: true zu deklarieren, wenn der Server keinen Streaming-Endpunkt hat. Clients werden ihn aufrufen und scheitern.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Benannte Authentifizierungsschemata: API-Schlüssel, HTTP-Auth, OAuth 2.0, OpenID Connect, oder gegenseitiges TLS.
Jedes benannte Schema umschließt ein konkretes Schema-Objekt (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Clients erfahren von hier, wie sie sich authentifizieren — die Credentials selbst werden immer außerhalb dieses Kanals beschafft.
Häufiger Fehler: Einen tatsächlichen API-Schlüssel oder Token in die Agent Card einzubetten. Eine Agent Card ist ein öffentliches Dokument.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Welche deklarierten Schemata (und Scopes) zum Aufrufen des Agenten erforderlich sind.
Jeder Eintrag ordnet einen Schemanamen aus securitySchemes den benötigten Scopes zu, in Anlehnung an das OpenAPI-Sicherheitsanforderungsmuster. Lasse beide Felder für bewusst öffentliche Agenten vollständig weg.
Häufiger Fehler: securitySchemes zu deklarieren, aber keine security-Anforderungen, sodass Clients raten müssen, ob Auth erzwungen wird.
"security": [{ "google": ["openid", "profile", "email"] }]Medientypen, die der Agent über alle Skills hinweg akzeptiert.
Standard-MIME-Typen wie text/plain, application/json, oder image/png. Einzelne Skills können mit eigenen inputModes überschreiben.
Häufiger Fehler: Das Feld wegzulassen. Es ist in v1.0 erforderlich — Clients benötigen es, um Anfragen zu gestalten.
"defaultInputModes": ["application/json", "text/plain"]
Medientypen, die der Agent über alle Skills hinweg zurückgibt.
Sagt Aufrufern, ob sie Fließtext, strukturiertes JSON, Bilder, oder Dateien erwarten sollen. Skills können pro Skill mit outputModes überschreiben.
Häufiger Fehler: Nur text/plain aufzulisten, wenn der Agent tatsächlich strukturierte Artefakte zurückgibt.
"defaultOutputModes": ["application/json", "image/png"]
Die konkreten Fähigkeiten, bei denen der Agent wahrscheinlich erfolgreich ist.
Jede Skill erfordert id, name, description, und tags; examples, Modi pro Skill, und Sicherheit pro Skill sind optional. Skills sind die Discovery-Einheit — Router gleichen Aufgaben gegen sie ab, also grenze jede auf eine einzige Aufgabengrenze ein.
Häufiger Fehler: Skills ohne Tags. Tags wurden in v1.0 erforderlich und treiben das Matching auf Skill-Ebene an.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Verkehrsbewusster Routenoptimierer",
"description": "Berechnet optimale Fahrtrouten anhand des Echtzeitverkehrs ...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Planen Sie eine Route von A nach B und vermeiden Sie Mautgebühren."]
}]JSON Web Signatures, die beweisen, dass die Agent Card vom Provider ausgestellt wurde.
Jede Signatur trägt einen base64url-geschützten JWS-Header und einen Signaturwert, berechnet über die RFC-8785-kanonisierte (JCS) Agent Card. Clients SOLLTEN mindestens eine Signatur verifizieren, bevor sie einer aus dem offenen Web abgerufenen Agent Card vertrauen.
Häufiger Fehler: Die Karte zu signieren und dann ein beliebiges Feld zu bearbeiten — selbst für Leerzeichen unwesentliche Wertänderungen machen die JWS ungültig.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL zu einem Icon, das den Agenten repräsentiert.
Wird von Katalogen und Client-UIs verwendet. Stelle es über HTTPS von einem stabilen Ort bereit.
Häufiger Fehler: Ein Icon auf einer anderen, nicht vertrauenswürdigen Domain zu verlinken, die sich unter deinem Listing ändern kann.
"iconUrl": "https://agent.example.com/icon.png"
Versionsmigration
Wenn deine Agent Card noch eine Top-Level url oder preferredTransport hat, stammt sie aus der Zeit vor v1.0. Der Validator markiert jedes davon automatisch.
| v0.x-Feld | v1.0-Ersatz | Warum es sich geändert hat |
|---|---|---|
| url | supportedInterfaces[0].url | Der bevorzugte Endpunkt ist jetzt einfach der erste Interface-Eintrag. |
| preferredTransport | supportedInterfaces[] ordering | Präferenz wird durch die Array-Reihenfolge statt durch ein separates Feld ausgedrückt. |
| additionalInterfaces | supportedInterfaces[] | Alle Schnittstellen befinden sich in einem einzigen geordneten Array. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Jede Schnittstelle deklariert ihre eigene Protokollversion, was Multi-Version-Support ermöglicht. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | In das capabilities-Objekt verschoben; der RPC wurde in GetExtendedAgentCard umbenannt. |
| provider.name | provider.organization | Zur Klarheit umbenannt. |
| capabilities.stateTransitionHistory | — removed | Nicht Teil von v1.0; modelliere bei Bedarf äquivalentes Verhalten als Erweiterung. |
Boilerplate
Füge diese Interfaces in einen Client, Server, oder CI-Check ein, um Agent Cards typsicher zu parsen und zu erzeugen. Sie spiegeln die Protobuf-Definitionen im offiziellen Spezifikations-Repository, in der camelCase-JSON-Form, in der Agent Card veröffentlicht werden.
Baust du stattdessen eine Agent Card von Hand? Der Generator erzeugt genau diese Form.
// 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> }Integrität
Da Agent Cards aus dem offenen Web abgerufen werden, formalisiert v1.0 die Signierung: die Agent Card (abzüglich des signatures-Feldes und Standardwerte) wird mit RFC 8785 JSON Canonicalization kanonisiert und dann als JWS signiert. Clients sollten mindestens eine Signatur verifizieren — über den kid/jku-Header oder einen vertrauenswürdigen Schlüsselspeicher — bevor sie auf Basis einer Agent Card handeln. Mehrere Signaturen unterstützen Schlüsselrotation.
Stelle die Agent Card unter /.well-known/agent-card.json über HTTPS bereit.
Jeder supportedInterfaces-Eintrag ist erreichbar und spricht die deklarierte Bindung.
Skills haben erforderliche Tags plus Beschreibungen mit klaren Aufgabengrenzen.
Deklarierte Capabilities stimmen mit dem Server überein — nicht deklarierte Features müssen Fehler zurückgeben, deklarierte müssen funktionieren.
securitySchemes beschreibt, wie authentifiziert wird; nirgendwo in der Agent Card erscheinen Credentials.
version wird erhöht, wann immer sich der Agent Card ändert.
Ein Kundensupport-Agent mit OAuth 2.0, Streaming, und Push-Benachrichtigungen — alle erforderlichen Felder vorhanden. Weitere Muster gibt es in der Beispielbibliothek.
{
"name": "Kundensupport-Agent",
"description": "Beantwortet Fragen des Kundensupports, ruft den Bestellkontext ab und leitet ungelöste Probleme an ein menschliches Team weiter.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Beispiel 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": "Lösen Sie die Kundensupportanfrage",
"description": "Klassifiziert eine Kundensupportanfrage, sammelt den erforderlichen Kontext, schlägt eine Lösung vor und eskaliert, wenn das Vertrauen gering ist.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Helfen Sie mir, meine Bestellung zurückzugeben."
]
}
],
"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
Die Versionsänderungen, Discovery-Felder, und Veröffentlichungsdetails, die darüber entscheiden, ob eine Agent Card die Prüfung besteht.
v1.0 hat url, preferredTransport, und additionalInterfaces in ein einziges geordnetes supportedInterfaces-Array konsolidiert, in dem jeder Eintrag seine eigene url, protocolBinding, und protocolVersion deklariert. supportsAuthenticatedExtendedCard wurde zu capabilities.extendedAgentCard verschoben, provider.name wurde zu provider.organization, Skill-Tags wurden erforderlich, und JWS-Agent Card wurden mit RFC-8785-Kanonisierung formalisiert.
Nein. Eine Agent Card ist ein Discovery-Dokument für einen Agenten. Sie fasst Identität, Schnittstellen, Capabilities, Skills, Modi, Provider, und Sicherheitsmetadaten zusammen, während ein vollständiges API-Schema detaillierte Anfrage- und Antwortformen beschreibt. Sie spielt die Rolle, die ein README oder eine OpenAPI-Übersicht für einen Dienst spielt: genug, um zu entscheiden, ob und wie man ihn aufruft.
name, description, supportedInterfaces, skills (mit Tags), defaultInputModes, defaultOutputModes, capabilities, provider, und Sicherheitsmetadaten. Routing-Systeme gleichen Aufgaben mit deiner description und deinen Skill-Tags ab und verwenden dann Schnittstellen und Capabilities, um den tatsächlichen Aufruf zu planen.
Veröffentliche nur Skills, die für nicht authentifizierte Discovery sicher sind. Wenn eine reichhaltigere private Agent Card benötigt wird, setze capabilities.extendedAgentCard auf true und stelle sensible Skills über die authentifizierte Operation GetExtendedAgentCard bereit.
Unter der well-known URI https://{deine-domain}/.well-known/agent-card.json, bereitgestellt mit dem Content-Type application/a2a+json (application/json funktioniert in der Praxis ebenfalls). Frühere Implementierungen verwendeten /.well-known/agent.json, daher ist es während der Übergangszeit eine pragmatische Wahl, beide zu veröffentlichen.
Nutze das Schema
Generiere eine v1.0-förmige Agent Card aus deinen Servicedetails, oder füge eine bestehende Agent Card in den Validator ein, um genau zu sehen, welche Felder Aufmerksamkeit benötigen.