--- name: design-a2a-agent-card description: > Eine A2A-Agentenkarte (.well-known/agent.json) als Manifest entwerfen, das Agentenfaehigkeiten, Skills, Authentifizierungsanforderungen und unterstuetzte Inhaltstypen beschreibt. Verwenden beim Erstellen eines Agenten, der von anderen A2A-konformen Agenten auffindbar sein muss, beim Bereitstellen von Faehigkeiten fuer Multi-Agenten-Orchestrierung, beim Migrieren eines bestehenden Agenten zum A2A-Protokoll, beim Definieren des oeffentlichen Vertrags fuer einen Agenten vor der Implementierung oder beim Integrieren mit Agentenregistern, die Agentenkarten konsumieren. license: MIT allowed-tools: Read Write Edit Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: a2a-protocol complexity: intermediate language: multi tags: a2a, agent-card, manifest, capabilities, interoperability locale: de source_locale: en source_commit: a87e5e03 translator: claude translation_date: "2026-03-17" --- # A2A-Agentenkarte entwerfen Eine standardkonforme A2A-Agentenkarte erstellen, die Identitaet, Skills, Authentifizierungsanforderungen und Faehigkeiten eines Agenten fuer die Erkennung durch andere Agenten bewirbt. ## Wann verwenden - Einen Agenten erstellen, der von anderen A2A-konformen Agenten auffindbar sein muss - Agentenfaehigkeiten fuer Multi-Agenten-Orchestrierung bereitstellen - Einen bestehenden Agenten zum A2A (Agent-to-Agent)-Protokoll migrieren - Den oeffentlichen Vertrag fuer einen Agenten vor der Implementierung definieren - Mit Agentenregistern oder -verzeichnissen integrieren, die Agentenkarten konsumieren ## Eingaben - **Erforderlich**: Agentenname und -beschreibung - **Erforderlich**: Liste der Skills, die der Agent ausfuehren kann (Name, Beschreibung, Ein-/Ausgabeschemata) - **Erforderlich**: Basis-URL, unter der der Agent gehostet wird - **Optional**: Authentifizierungsmethode (`none`, `oauth2`, `oidc`, `api-key`) - **Optional**: Unterstuetzte Inhaltstypen ueber `text/plain` hinaus (z.B. `image/png`, `application/json`) - **Optional**: Faehigkeits-Flags (Streaming, Push-Benachrichtigungen, Zustandsuebergangsverlauf) - **Optional**: Anbieterorganisationsname und URL ## Vorgehensweise ### Schritt 1: Agentenidentitaet und -beschreibung definieren 1.1. Die Agentenidentitaetsfelder festlegen: ```json { "name": "data-analysis-agent", "description": "Performs statistical analysis, data visualization, and report generation on tabular datasets.", "url": "https://agent.example.com", "provider": { "organization": "Example Corp", "url": "https://example.com" }, "version": "1.0.0" } ``` 1.2. Eine klare, handlungsorientierte Beschreibung verfassen, die beantwortet: - Welche Domaenen deckt dieser Agent ab? - Welche Arten von Aufgaben kann er bearbeiten? - Was sind seine Einschraenkungen? 1.3. Die kanonische URL festlegen, unter der die Agentenkarte unter `/.well-known/agent.json` bereitgestellt wird. **Erwartet:** Ein vollstaendiger Identitaetsblock mit Name, Beschreibung, URL, Anbieter und Version. **Bei Fehler:** Wenn der Agent mehrere Domaenen bedient, abwaegen, ob es ein Agent mit vielen Skills oder mehrere Agenten mit fokussiertem Umfang sein sollte. A2A bevorzugt fokussierte Agenten mit klaren Grenzen. ### Schritt 2: Skills mit Ein-/Ausgabeschemata auflisten 2.1. Jeden Skill definieren, den der Agent ausfuehren kann: ```json { "skills": [ { "id": "analyze-dataset", "name": "Analyze Dataset", "description": "Run descriptive statistics, correlation analysis, or hypothesis tests on a CSV dataset.", "tags": ["statistics", "data-analysis", "csv"], "examples": [ "Analyze the correlation between columns A and B in my dataset", "Run a t-test comparing group 1 and group 2" ], "inputModes": ["text/plain", "application/json"], "outputModes": ["text/plain", "application/json", "image/png"] }, { "id": "generate-chart", "name": "Generate Chart", "description": "Create bar, line, scatter, or histogram charts from tabular data.", "tags": ["visualization", "charts"], "examples": [ "Create a scatter plot of height vs weight", "Generate a histogram of the age column" ], "inputModes": ["text/plain", "application/json"], "outputModes": ["image/png", "image/svg+xml"] } ] } ``` 2.2. Fuer jeden Skill bereitstellen: - **id**: Eindeutiger Bezeichner (Kebab-Case) - **name**: Menschenlesbarer Anzeigename - **description**: Was der Skill tut, in ein bis zwei Saetzen - **tags**: Durchsuchbare Schluesselwoerter fuer die Erkennung - **examples**: Natuerlichsprachliche Aufgabenbeispiele, die diesen Skill ausloesen - **inputModes**: MIME-Typen, die der Skill akzeptiert - **outputModes**: MIME-Typen, die der Skill produzieren kann 2.3. Sicherstellen, dass Skill-Grenzen klar und nicht ueberlappend sind. Jede Aufgabe sollte genau einem Skill zugeordnet werden. **Erwartet:** Ein Skills-Array, in dem jeder Eintrag id, name, description, tags, examples und I/O-Modi hat. **Bei Fehler:** Wenn Skills sich erheblich ueberschneiden, zu einem einzigen breiteren Skill mit mehr Beispielen zusammenfuehren. Wenn ein Skill zu breit ist, in fokussierte Unter-Skills aufteilen. ### Schritt 3: Authentifizierung konfigurieren 3.1. Das Authentifizierungsschema basierend auf dem Bereitstellungskontext definieren: **Keine Authentifizierung (lokal/vertrauenswuerdiges Netzwerk):** ```json { "authentication": { "schemes": [] } } ``` **OAuth 2.0 (empfohlen fuer Produktion):** ```json { "authentication": { "schemes": ["oauth2"], "credentials": { "oauth2": { "authorizationUrl": "https://auth.example.com/authorize", "tokenUrl": "https://auth.example.com/token", "scopes": { "agent:invoke": "Invoke agent skills", "agent:read": "Read task status" } } } } } ``` **API Key (einfaches Shared-Secret):** ```json { "authentication": { "schemes": ["apiKey"], "credentials": { "apiKey": { "headerName": "X-API-Key" } } } } ``` 3.2. Die minimal notwendige Authentifizierung fuer die Bereitstellungsumgebung waehlen: - Lokale Entwicklung: `none` - Interne Dienste: `apiKey` - Oeffentlich zugaengliche Agenten: `oauth2` oder `oidc` 3.3. Den Token-/Schluessel-Bereitstellungsprozess im Provider-Abschnitt der Agentenkarte oder in externer Dokumentation dokumentieren. **Erwartet:** Ein Authentifizierungsblock, der den Sicherheitsanforderungen der Bereitstellung entspricht. **Bei Fehler:** Wenn keine OAuth-2.0-Infrastruktur verfuegbar ist, mit API-Key-Authentifizierung beginnen und Migration planen. Niemals einen oeffentlichen Agenten mit `none`-Authentifizierung bereitstellen. ### Schritt 4: Faehigkeiten angeben 4.1. Deklarieren, welche Protokollfunktionen der Agent unterstuetzt: ```json { "capabilities": { "streaming": true, "pushNotifications": false, "stateTransitionHistory": true } } ``` 4.2. Jedes Faehigkeits-Flag basierend auf der Implementierungsbereitschaft setzen: - **streaming**: `true` wenn der Agent SSE-Streaming ueber `tasks/sendSubscribe` unterstuetzt. Ermoeglicht Echtzeit-Fortschrittsaktualisierungen fuer langlebige Aufgaben. - **pushNotifications**: `true` wenn der Agent Webhook-Rueckrufe senden kann, wenn sich der Aufgabenstatus aendert. Erfordert, dass der Agent Webhook-URLs speichert und zurueckruft. - **stateTransitionHistory**: `true` wenn der Agent einen vollstaendigen Verlauf der Aufgabenzustandsuebergaenge fuehrt (submitted, working, completed, etc.). Nuetzlich fuer Audit-Trails. 4.3. Faehigkeiten nur auf `true` setzen, wenn die Implementierung sie vollstaendig unterstuetzt. Nicht unterstuetzte Faehigkeiten zu bewerben bricht die Interoperabilitaet. **Erwartet:** Ein Capabilities-Objekt mit booleschen Flags, die der tatsaechlichen Implementierung entsprechen. **Bei Fehler:** Wenn unsicher, ob eine Faehigkeit implementiert wird, auf `false` setzen. Faehigkeiten koennen in zukuenftigen Versionen hinzugefuegt werden. Eine Faehigkeit zu entfernen ist eine brechende Aenderung. ### Schritt 5: Agentenkarte validieren und veroeffentlichen 5.1. Die vollstaendige Agentenkarte zusammenstellen: ```json { "name": "data-analysis-agent", "description": "Performs statistical analysis and visualization on tabular datasets.", "url": "https://agent.example.com", "version": "1.0.0", "provider": { "organization": "Example Corp", "url": "https://example.com" }, "authentication": { "schemes": ["oauth2"], "credentials": { ... } }, "capabilities": { "streaming": true, "pushNotifications": false, "stateTransitionHistory": true }, "skills": [ ... ], "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"] } ``` 5.2. Die Agentenkarte validieren: - Als JSON parsen und auf Syntaxfehler pruefen - Verifizieren, dass alle erforderlichen Felder vorhanden sind (name, description, url, skills) - Verifizieren, dass jeder Skill id, name, description und mindestens einen Ein-/Ausgabemodus hat - Verifizieren, dass die URL erreichbar ist und die Karte unter `/.well-known/agent.json` bereitstellt 5.3. Die Agentenkarte veroeffentlichen: - Unter `https:///.well-known/agent.json` bereitstellen - `Content-Type: application/json` setzen - CORS-Header aktivieren, wenn Cross-Origin-Erkennung benoetigt wird - Bei relevanten Agentenverzeichnissen oder -registern registrieren 5.4. Erkennung durch Abrufen der Karte testen: ```bash curl -s https://agent.example.com/.well-known/agent.json | python3 -m json.tool ``` **Erwartet:** Eine gueltige JSON-Agentenkarte, bereitgestellt unter der Well-Known-URL, parsebar von jedem A2A-Client. **Bei Fehler:** Wenn die JSON-Validierung fehlschlaegt, einen JSON-Linter zur Identifizierung von Syntaxfehlern verwenden. Wenn die URL nicht erreichbar ist, DNS, SSL-Zertifikate und Webserver-Konfiguration pruefen. Wenn CORS benoetigt wird, `Access-Control-Allow-Origin`-Header hinzufuegen. ## Validierung - [ ] Agentenkarte ist gueltiges JSON ohne Syntaxfehler - [ ] Alle erforderlichen Felder sind vorhanden: name, description, url, skills - [ ] Jeder Skill hat id, name, description, inputModes und outputModes - [ ] Authentifizierungsschema entspricht den Sicherheitsanforderungen der Bereitstellung - [ ] Faehigkeits-Flags spiegeln den Implementierungsstatus genau wider - [ ] Agentenkarte wird unter `/.well-known/agent.json` mit korrektem Content-Type bereitgestellt - [ ] A2A-Clients koennen die Karte erfolgreich abrufen und parsen - [ ] Beispiele in Skills sind realistisch und loesen den korrekten Skill aus ## Haeufige Stolperfallen - **Faehigkeiten ueberversprechen**: `streaming: true` oder `pushNotifications: true` ohne Implementierung zu setzen verursacht Client-Fehler bei Nutzung dieser Funktionen. Konservativ sein. - **Vage Skill-Beschreibungen**: Beschreibungen wie "macht Datensachen" verhindern genaues Skill-Matching. Spezifisch ueber Eingaben, Ausgaben und Domaenen sein. - **Fehlende CORS-Header**: Browserbasierte A2A-Clients koennen die Agentenkarte ohne korrekte CORS-Konfiguration nicht abrufen. - **Skill-Ueberschneidung**: Wenn zwei Skills dieselbe Aufgabe bearbeiten koennten, koennen Client-Agenten nicht bestimmen, welchen sie aufrufen sollen. Klare Grenzen sicherstellen. - **Standard-Modi vergessen**: Wenn `defaultInputModes` und `defaultOutputModes` fehlen, wissen Clients moeglicherweise nicht, welche Inhaltstypen sie senden sollen. - **Versionsstagnation**: Die Agentenkarten-Version aktualisieren, wenn sich Skills oder Faehigkeiten aendern. Clients koennten alte Versionen zwischenspeichern. - **Vor der Implementierung veroeffentlichen**: Die Agentenkarte ist ein Vertrag. Skills zu veroeffentlichen, die noch nicht implementiert sind, fuehrt zu Laufzeitfehlern. ## Verwandte Skills - `implement-a2a-server` — Den Server hinter der Agentenkarte implementieren - `test-a2a-interop` — Agentenkarten-Konformitaet und Interoperabilitaet validieren - `build-custom-mcp-server` — MCP-Server als Alternative/Ergaenzung zu A2A - `configure-mcp-server` — MCP-Konfigurationsmuster, anwendbar auf A2A-Setup