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.

Was das für Unternehmer bedeutet

Die Agent Card ist ein technisches Detail mit geschäftlichen Folgen. Fehlt sie oder ist sie vage, finden Partnersysteme und AI-Orchestratoren Ihren Service unter den Alternativen schlicht nicht - wie eine Website ohne korrektes SEO-Markup. Ist die Karte zu offen (z. B. stimmen capabilities oder security nicht mit den echten Grenzen überein), entsteht ein Risiko: Ein fremder Agent könnte versuchen, eine Operation aufzurufen, die von außen nicht erreichbar sein sollte.

Sie müssen das JSON nicht selbst schreiben - fragen Sie aber Ihr Entwicklungsteam: Welche Skills und Daten sind für externe Agenten sichtbar, welche Authentifizierung ist nötig, und wurde die Checkliste unten vor der Veröffentlichung durchgegangen?

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.

Wann Sie keine Agent Card brauchen

Plant Ihr Unternehmen noch keine Integrationen mit externen AI-Agenten, Agenten-Marktplätzen oder Partner-Orchestratoren, kann eine vollständige Agent Card warten. Sie ist nicht kritisch für:

• einen internen Chatbot auf der Website, der nur über ein Web-Widget mit Menschen spricht;
• ein MVP ohne öffentliche API, bei dem Integrationen mit anderen Agenten erst später kommen;
• Szenarien, in denen der Agent nur von Ihrem eigenen Code aufgerufen wird, nicht von fremden Systemen.

Sobald eine Partnerintegration ansteht oder der Agent an einen Marktplatz oder einen fremden Orchestrator angebunden werden soll, wird die Karte verpflichtend.

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 bei Entwicklung, KI-Einführung oder Website-Betreuung für Ihr Projekt brauchen - schreiben Sie mir.

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.

Begriffe in diesem Artikel

A2A — Agent-to-Agent — Protokoll für die Kommunikation zwischen KI-Agenten

endpoint — specific API URL that accepts requests — spezifische API-URL, die Anfragen entgegennimmt

router — routes requests or dialog turns

breaking changes — updates that break existing clients or integrations — Änderungen, die bestehende Clients/Integrationen brechen

webhooks — HTTP callbacks when events happen — HTTP-Rückrufe bei Ereignissen

orchestrator — component that coordinates steps/services

chatbot — conversational bot interface

MVP — Minimum Viable Product