Agent-almanac design-a2a-agent-card

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/design-a2a-agent-card" ~/.claude/skills/pjt222-agent-almanac-design-a2a-agent-card-62994a && rm -rf "$T"

manifest: i18n/de/skills/design-a2a-agent-card/SKILL.md

source content

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.