pjt222/design-a2a-agent-card

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:

{
  "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:

{
  "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):

{
  "authentication": {
    "schemes": []
  }
}

OAuth 2.0 (empfohlen fuer Produktion):

{
  "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):

{
  "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:

{
  "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:

{
  "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://<agent-url>/.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:

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