A2A Agent Card JSON Schema: Name, Fähigkeiten, Skills, Interfaces und Endpoint definieren

Für wen diese Karte ist

Eine Agent Card ist die öffentliche Visitenkarte, die ein A2A-Server unter /.well-known/agent-card.json aufhängt. Der Leser ist nicht euer eigenes Modell, sondern ein anderer Orchestrator, ein Gateway oder ein Katalog in der Org. Die Karte beantwortet drei Sätze: wer ihr seid, wie man euch erreicht, was ihr behauptet zu tun. Erstens: name / description / version. Zweitens: supportedInterfaces. Drittens: skills[]. Ein Runbook in description trifft zuerst die 10KB-Grenze; die Entdeckungsfläche wird dünner.

Version 1.0 macht Pflicht hart. Die Spectabelle markiert name, description, supportedInterfaces, version, capabilities, defaultInputModes, defaultOutputModes und skills als Yes. Fehlt eins, darf ein 1.0-Client die Datei nicht als legale Karte lesen. 0.3 lebte von Top-Level-url und protocolVersion. Ein 1.0-Client ignoriert sie und liest das Interface-Array. Mischt ihr beide Feldsätze, wird die Katalogextraktion still dünner; das Ticket sagt weiter „nicht gefunden“.

Die Karte ist kein Plugin Manifest und kein MCP-tools/list. Wie ein Coding-Agent Skills wachsen lässt, steht im Plugin-Text. Wie ein Call-Hop Argumente prüft: MCP und JSON Schema. Heute nur, wie ein seitlicher Kollege sich beschreibt. Signaturen, erweiterte Karten und GetExtendedAgentCard kommen nach Auth. Die öffentliche Karte muss Skills zuerst nennen.

Identität: name, description, version, provider

name ist für Menschen, die einen Katalog scannen, kein interner Dienstname. description nennt Scope und Grenze: was ihr tut, und was nicht. Ein Retouren-Spezialist darf schreiben „klassifiziert Retouren; bucht keine Erstattungen“. Orchestratoren entscheiden anhand dieses Absatzes, nicht anhand eurer README, ob sie einen Task schicken.

version ist die Release dieses Agenten, etwa 1.0.3. Die Protokollversion wandert mit dem Interface, in supportedInterfaces[].protocolVersion. Schreibt ihr an beiden Stellen 1.0, wisst ihr später nicht, welche Seite sich bewegt hat. provider ist optional, aber wenn vorhanden ein Paar: organization plus url. documentationUrl und iconUrl sind ebenfalls optional; lange Prosa gehört an die Docs-URL, nicht in die Karte.

Nach dem Identitätsblock innehalten. Ohne Interfaces ist die Karte nicht aufrufbar. Ohne Skills findet der Katalog euch nicht. Den ersten der drei Sätze kurz und wahr halten, dann Endpoints füllen.

Interfaces: supportedInterfaces ist der Endpoint

In 1.0 sitzt der primäre Endpoint nicht oben. supportedInterfaces ist ein geordnetes Array; der erste Eintrag ist bevorzugt. Jedes Item braucht url, protocolBinding und protocolVersion. Produktions-url muss absolutes HTTPS sein. Offizielle Kernwerte: JSONRPC, GRPC, HTTP+JSON; die Spec lässt den String für Erweiterungen offen. tenant ist optional — nur bei Multi-Tenant.

Ein Agent darf drei Bindings auf drei URLs listen. Clients nehmen das erste, das sie sprechen, in Array-Reihenfolge. Nicht alle drei auf denselben 404 zeigen, nur um vollständig zu wirken. 0.3s Top-Level-url plus protocolVersion ist der alte Vertrag; die v1.0-Änderungsseite sagt, sie sind nicht mehr primär. Als 1.0 registrieren und die URL oben parken: 1.0-Validierung sollte scheitern oder der primäre Endpoint wird ignoriert.

Das Interface-Array entscheidet, wie ihr sprecht, nicht was ihr erledigt. JSONRPC ohne Skills: erreichbar, nicht suchbar. Skills ohne Interfaces: suchbar, kein Task. Beide Blöcke müssen da sein.

Capabilities und Standard-MIME-Typen

capabilities ist in 1.0 ein Pflicht-Objekt; die Booleans darin sind optional: streaming, pushNotifications, extendedAgentCard, plus extensions. Fehlt oder false, soll die passende Operation fehlschlagen, nicht still retryen. 0.3s stateTransitionHistory nicht als Kernfähigkeit zurückholen. Tabelle 4.4.3 listet sie nicht mehr.

defaultInputModes und defaultOutputModes sind Medientyp-Arrays für jeden Skill. Ein Skill darf mit inputModes / outputModes überschreiben. Nur Text: text/plain. JSON raus: application/json dazu. Ein leeres Array ist undeclared; 1.0-Validierung sollte scheitern. Keine Dateiendungen und keine privaten Enums.

extendedAgentCard true heißt: nach Auth darf eine zweite, reichere Karte geholt werden. Die öffentliche Karte muss trotzdem allein stehen: Skills, Interfaces, Default-MIME. Einen kritischen Skill nur auf der erweiterten Karte verstecken, und unauthentifizierte Kataloge verpassen euch auf der Suchfläche.

skills[]: id, tags, examples

Jeder Skill braucht id, name, description und tags. id ist ein stabiler, kurzer, programmatischer Schlüssel — keine Leerzeichen. name ist für Menschen. description nennt I/O-Grenzen, ist immer noch kein Argument-Schema. tags ist in 1.0 ein Pflicht-String-Array für Katalog- und Orchestrator-Keywords. Auch Google Registry indexiert Tags. Leer oder fehlend: die Datei mag parsen, niemand findet euch.

examples sind optionale Prompts oder Szenen für Menschen, kein JSON Schema. 1.0 behandelt inputSchema nicht als Skill-Vertrag. Ältere Implementierungen hängen noch ein Schema an einen Skill; als Hinweis okay, als tools/call-Vertrag nicht. Gegenüber sitzt ein opaker Agent; ihr schickt einen Task. Das 0.3-Fragment auf der Site mit inputSchema am Skill ist der alte Vertrag. Nicht in eine neue Karte kopieren.

Skills nicht nach internen Funktionsnamen schneiden. Ein Skill ist eine Art Arbeit, die ein Orchestrator delegieren würde. Ein Retouren-Spezialist kann classify-return und check-window zeigen — nicht „Tabelle lesen“, „Log schreiben“, „Mail senden“ als drei Suchwörter. Unten eine 1.0-Karte zum Commit. Erst parsen, dann das offizielle Schema.

{
  "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?"]
    }
  ]
}

Was nicht in eine 1.0-Karte gehört

Mindestens ein Negativ: Top-Level-url noch da, ein Skill ohne tags, plus ein MCP-förmiges inputSchema. 1.0-Validierung sollte scheitern. Wenn CI 0.3 und 1.0 zu einem „generischen Agent-Check“ quetscht, seid ihr unordentlicher als der Client. Die Registry wählt Regeln nach der deklarierten Version und holt beim Laden kein Schema.

{
  "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 und Sicherheitsanforderungen sind optional. Eine öffentliche Karte darf ohne Signaturen auskommen. signatures sind JWS; der Verify-Walk ist der Praxis-Text. Merke: eine Signatur ersetzt keine tags. Eine ehrliche Karte mit einem echten Skill schlägt eine hübsche Karte mit leerer Skill-Liste. skills bleibt ein Pflicht-Array — keine Null-Items, außer ihr habt wirklich keine.

Keine geschlossenen Plugin-Felder, keine SKILL.md-Pfade, keine MCP-tools[].name in die Card. Drei JSON-Dateien sagen „Fähigkeit“; Fehlerbehandlung unterscheidet sich. Eine kaputte Card ist Discovery-Fehler.

Im Browser:JSON-Formatierer, ob die Karte parst;JSON-Schema-Validator für 1.0-supportedInterfaces und skills[].tags;JSON Diff, um Top-Level-url / fehlende Tags zwischen committeter Karte und Negativ zu fangen. Nichts verlässt die Maschine. Weiterlesen:Agent-Registry-Überblick und A2A vs MCP. Der Discovery-Walk ist der nächste Text.

Verwandt: Google Agent Registry, A2A vs MCP, MCP und JSON Schema.

FAQ

Fazit und nächste Schritte

2026 fällt eine A2A-Agent-Card auf eine Pflicht-Tabelle: drei Identitätsfelder, ein Interface-Array, ein Capabilities-Objekt, Default-MIME und Skills mit Tags. Orchestratoren lesen diese Felder, nicht eure Architekturslide.

Reihenfolge: legale 1.0-Karte; erstes Interface ist ein echter Endpoint; jeder Skill hat nicht-leere Tags; parsen und Schema in JSONVue. Wie der Katalog die Karte frisst: der vorige Text. Die Hops: der nächste. Signaturen und Checkliste: später.