Agent Card in A2A: vollständiges JSON-Beispiel und Feldanalyse

Eine Agent Card ist ein JSON-Dokument, das einem Client-Agenten sagt, wen er aufrufen soll, wohin er eine Aufgabe senden soll und welche Skills verfügbar sind. Im A2A-Protokoll (Agent2Agent) wird die Karte üblicherweise unter /.well-known/agent-card.json veröffentlicht: ohne sie ist der Agent schwer zu finden; mit einer vagen Beschreibung schwer korrekt zu routen.

• Agent Card - öffentlicher Vertrag über die Fähigkeiten des Agenten
• Discovery - Auffinden der Karte über well-known URL oder Registry
• skills - konkrete Fähigkeiten, kein generisches «ich kann alles»
• capabilities - Streaming, Push, erweiterte Karte
• security - Authentifizierungsschemata im OpenAPI-Stil

Wozu eine Agent Card?

A2A verbindet unabhängige Agenten: einer agiert als Client, der andere als Executor. Bevor eine Aufgabe gesendet wird, liest der Client die Karte und beantwortet:

1. Passt dieser Agent zur Absicht des Nutzers?
2. Welcher Endpoint nimmt Aufgaben entgegen?
3. Welche MIME-Typen sind für Input und Output unterstützt?
4. Ist Authentifizierung nötig - und welche?
5. Werden Event-Streaming und Webhook-Benachrichtigungen unterstützt?

Die Karte ist kein Marketingtext. Orchestratoren und LLM-Router parsen sie. Je präziser description, skills und examples sind, desto stabiler ist die Auswahl des Executors.

Vollständiges JSON-Beispiel

Unten ein funktionsfähiges Beispiel für einen Agenten, der Produkte auf einer Website sucht, Preise berechnet und nach Nutzerbestätigung eine Anfrage erstellt. Die Felder nutzen camelCase wie in typischen A2A-JSON-Karten.

{
  "name": "Site Commerce Agent",
  "description": "Durchsucht den Website-Katalog, berechnet Preis und Lieferzeit und erstellt nach Nutzerbestätigung eine Anfrage. Arbeitet mit Katalog, Warenkorb-Entwurf und Bestellstatus. Verarbeitet keine Zahlungen und ändert keine Preise.",
  "version": "1.2.0",
  "protocolVersion": "0.3.0",
  "url": "https://api.example.com/a2a",
  "documentationUrl": "https://docs.example.com/a2a/commerce-agent",
  "iconUrl": "https://example.com/icons/commerce-agent.svg",
  "provider": {
    "organization": "Example Shop",
    "url": "https://example.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "search-products",
      "name": "Produktsuche",
      "description": "Sucht Produkte nach Anfrage, Kategorie, Preis und Verfügbarkeit. Liefert Kandidaten mit id, Name, Preis und Kurzbeschreibung.",
      "tags": ["catalog", "search", "products"],
      "examples": [
        "Finde Laptops unter 800 Euro mit Lieferung diese Woche",
        "Zeige verfügbare Tarife für ein Team von 20 Personen"
      ],
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["application/json", "text/plain"]
    },
    {
      "id": "calculate-quote",
      "name": "Preisberechnung",
      "description": "Berechnet Preis, Steuern, Versand und Lieferzeit für ausgewählte Positionen und Mengen. Erstellt keine Bestellung.",
      "tags": ["pricing", "quote", "shipping"],
      "examples": [
        "Berechne die Kosten für 3 Stück product_id=sku-1042 mit Lieferung nach Berlin",
        "Vergleiche Basic und Pro für 50 Nutzer"
      ],
      "inputModes": ["application/json", "text/plain"],
      "outputModes": ["application/json"]
    },
    {
      "id": "create-lead",
      "name": "Anfrage erstellen",
      "description": "Erstellt nach ausdrücklicher Nutzerbestätigung einen Lead- oder Anfrage-Entwurf. Benötigt Kontakt und Einwilligung zur Datenverarbeitung.",
      "tags": ["lead", "order-draft", "crm"],
      "examples": [
        "Erstelle eine Pro-Anfrage für ACME, Kontakt: ops@acme.example",
        "Erstelle einen Bestellentwurf aus quote_id=q-7781"
      ],
      "inputModes": ["application/json"],
      "outputModes": ["application/json", "text/plain"]
    },
    {
      "id": "get-order-status",
      "name": "Bestellstatus",
      "description": "Liefert Zahlungs- und Lieferstatus per order_id für einen authentifizierten Nutzer oder eine öffentliche Tracking-Nummer.",
      "tags": ["orders", "status", "tracking"],
      "examples": [
        "Wie ist der Status der Bestellung ORD-20441?",
        "Wo ist das Paket mit Tracking TRK-998877?"
      ]
    }
  ],
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    },
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "clientCredentials": {
          "tokenUrl": "https://auth.example.com/oauth/token",
          "scopes": {
            "catalog:read": "Katalog und Angebote lesen",
            "leads:write": "Anfragen erstellen",
            "orders:read": "Bestellstatus lesen"
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": ["catalog:read"]
    },
    {
      "bearer": []
    }
  ]
}

In A2A v1.0 wird der Endpoint oft über das Array supportedInterfaces statt eines einzelnen Top-Level-url beschrieben. Die Idee ist dieselbe: dem Client sagen, wohin Aufgaben gehen und welches Binding genutzt wird (JSONRPC, HTTP+JSON, GRPC usw.).

Beispiel-Fragment für v1.0:

{
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ]
}

Analyse der Top-Level-Felder

* In v0.3-Schemas ist url meist Pflicht. In v1.0 übernimmt supportedInterfaces die Endpoint-Rolle.

name und description

name ist für Menschen und Logs. description lesen Router. Schlecht: «Ein hilfreicher Website-Agent». Gut: Operationen, Grenzen und Ergebnisformat nennen.

version

Das ist die Versionsnummer der Agenten-Implementierung, nicht zwingend die Protokollversion. Bei Breaking Changes an Skills oder Antwortvertrag major erhöhen. Clients können die Karte cachen und bei Versionswechsel neu laden.

url - häufiger Fehler

url ist die Adresse für message/send / Tasks. Das ist nicht der Pfad zu /.well-known/agent-card.json.

Falsch:

"url": "https://example.com/.well-known/agent-card.json"

Richtig:

"url": "https://api.example.com/a2a"

capabilities

Setzen Sie true nur, wenn das Verhalten wirklich implementiert ist. Ein Client, der gegen einen Agenten ohne Streaming einen Stream öffnet, erhält einen Fehler.

defaultInputModes und defaultOutputModes

Standard-MIME-Typen für den gesamten Agenten. Ein Skill kann sie überschreiben. Typische Werte: text/plain, application/json, application/pdf, image/png.

Analyse von skills

Ein Skill ist eine Routing-Einheit. Ein Skill = eine klare Fähigkeit.

Examples sind keine Dekoration. Ohne sie rät der Orchestrator Eingaben nur aus der Beschreibung und irrt häufiger.

Schlechter Skill:

{
  "id": "website",
  "name": "Website",
  "description": "Arbeitet mit der Website"
}

Ein guter Skill sieht aus wie im vollständigen Beispiel: konkrete id, klare Grenzen, tags und examples.

Authentifizierung: securitySchemes und security

Schemata folgen üblicherweise dem OpenAPI-Ansatz:

• apiKey
• http (Basic / Bearer)
• oauth2
• openIdConnect
• mutualTLS

securitySchemes beschreibt verfügbare Methoden. security setzt die Standardanforderung:

• mehrere Objekte im Array security = Alternativen (OR);
• mehrere Keys in einem Objekt = alles gleichzeitig nötig (AND).

Veröffentlichen Sie wie authentifiziert wird, nicht die Secrets. Keine API-Keys, Refresh-Tokens oder internen Hostnames ins JSON legen.

Discovery: wie die Karte gefunden wird

Typischer Ablauf:

1. Der Client kennt die Basis-Domain des Agenten.
2. Er fragt https://agent.example.com/.well-known/agent-card.json ab.
3. Er validiert Pflichtfelder.
4. Er wählt einen Skill nach Beschreibung, tags und examples.
5. Er authentifiziert sich gemäß security.
6. Er sendet die Aufgabe an url / supportedInterfaces.

Karten werden auch in Registries oder Agentenverzeichnissen veröffentlicht. Dann läuft Discovery über Suche, während well-known die Wahrheitsquelle des Besitzers bleibt.

Lokaler Check:

curl -s https://api.example.com/.well-known/agent-card.json

Was nicht in die Agent Card gehört

• API-Keys, Passwörter, Private Keys;
• ungeschützte interne Admin- oder Staging-URLs;
• Operationen, die externen Clients nicht zur Verfügung stehen;
• aufgeblasene Capabilities (streaming: true ohne Implementierung);
• vage Skills wie «macht alles auf der Website».

Die öffentliche Karte ist Angriffs- und Routing-Oberfläche zugleich. Halten Sie sie präzise und minimal ausreichend.

Häufige Fehler

1. url mit der Karten-URL verwechseln.
2. Leeres skills-Array. Der Agent wird praktisch nicht routbar.
3. Beschreibung ohne Grenzen. Es fehlt, was der Agent nicht tut (Zahlung, Löschen, Preisänderung).
4. Keine examples. Orchestratoren verstehen gültige Eingaben schlechter.
5. localhost in einer Produktionskarte. Der Endpoint muss für Clients erreichbar sein.
6. Ein Skill für das ganze Produkt. Besser mehrere schmale Skills mit unterschiedlichen Rechten und MIME-Typen.

Mini-Checkliste vor der Veröffentlichung

1. Die Karte wird per HTTPS mit Content-Type: application/json ausgeliefert.
2. Es gibt name, description, version, Endpoint und mindestens einen Skill.
3. Beschreibungen sind konkret.
4. Wichtige Skills haben examples und tags.
5. capabilities entsprechen dem realen Server.
6. Das JSON enthält keine Secrets.
7. Der Endpoint aus der Karte beantwortet eine Testaufgabe.
8. Die Version steigt bei Breaking Changes.

Fazit

Die Agent Card ist der zentrale Discovery-Vertrag in A2A. Ein vollständiges JSON mit präzisen Skills, ehrlichen Capabilities und klarer Security gibt Client-Agenten genug Daten, um den richtigen Executor zu finden und den falschen nicht aufzurufen.

Wenn Sie Hilfe beim Entwurf einer Agent Card, eines A2A-Servers oder der Anbindung eines Agenten an eine Website-API brauchen - kontaktieren Sie mich.

Häufig gestellte Fragen

Wo soll die Agent Card liegen?

Der Standardpfad ist /.well-known/agent-card.json auf der Domain des Agenten. Zusätzlich können Sie die Karte in einem Katalog oder einer Registry registrieren, aber die well-known URL bleibt ein bequemer Discovery-Punkt ohne separaten Index.

Worin unterscheidet sich url von der Kartenadresse?

Die Kartenadresse dient der Discovery; url (oder supportedInterfaces) der Aufgabenausführung. Der Client liest zuerst das JSON und sendet dann Nachrichten/Tasks an den Arbeits-Endpoint des Agenten.

Wie viele Skills sollte eine Karte haben?

So viele, wie Sie wirklich unterschiedliche Fähigkeiten mit unterschiedlichen Inputs oder Rechten haben. Meist sind 3-7 schmale Skills besser als ein generisches «mach alles». Fürs Routing zählen klare Grenzen, tags und examples.

Ist Authentifizierung in der Agent Card Pflicht?

Nicht immer. Ein öffentlicher Read-only-Agent kann security weglassen. Für Schreibzugriffe, personenbezogene Daten und kostenpflichtige Operationen deklarieren Sie securitySchemes und security und halten Secrets außerhalb der Karte.

Muss die Karte bei jedem Deploy aktualisiert werden?

Aktualisieren Sie sie, wenn sich Skills, Endpoint, Capabilities, Auth oder die Bedeutung des Agenten ändern. Ein technischer Patch ohne Vertragsänderung kann in version sichtbar werden; Breaking Changes verdienen eine Major-Version und klare Dokumentation.