Eingaben
Beispiel
https://agent.example/.well-known/agent-card.json -> Pflichtfelder, Skills, Protocol Bindings, Capabilities und Security-Metadaten.
A2A-Agent-Card-Validator
Validiert A2A-Agent-Card-Discovery-JSON, Skills, Interfaces, Capabilities und Deployment-Metadaten.
Nutze es, um versionsbewusste A2A-v0.2-, v0.3- oder v1.0-Card-Struktur und Discovery-Evidenz zu prüfen, ohne den Agent-Endpunkt aufzurufen.
Die Vertragsdatei, die andere Agents zuerst lesen
Im A2A-Protokoll ist die Agent Card der komplette erste Eindruck: ein JSON-Dokument an einer Well-known-URL, das anderen Agents sagt, wer du bist, welche Skills du anbietest, welche Endpunkte und Transporte du sprichst und wie sich Aufrufer authentifizieren müssen. Konsumierende Agents parsen sie mechanisch. Ein fehlendes Pflichtfeld, ein Skill ohne Beschreibung oder Auth-Metadaten, die deinem tatsächlichen Deployment widersprechen, erzeugen auf der Gegenseite keine freundliche Fehlermeldung — sie erzeugen stille Inkompatibilität, und der aufrufende Agent zieht einfach weiter.
Dieser Validator erkennt die Card-Form zuerst als A2A v0.2, v0.3 oder v1.0 und meldet bei gemischten Feldern eine mehrdeutige Version, statt sie willkürlich gegen ein Schema zu prüfen. Danach gelten die versionsspezifischen Regeln für Identität, Transporte oder Interfaces, Skills, Capabilities, Security und Discovery-Pfad; unbekannte Extension-Felder bleiben erhalten.
Eine Card vor und nach der Veröffentlichung validieren
Beim Entwerfen fügst du das JSON direkt ein und behebst Fehler vor Warnungen: Fehler betreffen Felder, auf die sich ein konformer Konsument verlassen darf; Warnungen sind die Stellen, an denen Interoperabilität leise schlechter wird. Besondere Aufmerksamkeit verdienen die Skill-Beschreibungen — über sie entscheidet der auswählende Agent beziehungsweise das Modell dahinter. Eine vage Skill-Beschreibung ist das Agent-Äquivalent eines toten Links: syntaktisch in Ordnung, praktisch nutzlos.
Nach dem Deployment holst du die Card von ihrer öffentlichen Well-known-URL, statt sie aus dem Repository einzufügen — die interessanten Bugs wohnen im Auslieferungspfad: ein Redirect, der den Pfad verschluckt, ein Proxy, der Content-Types umschreibt, eine alte Version im Edge-Cache oder TLS, das auf einem Namen terminiert, den die Card nicht erwähnt. Die geholte Card ist die, die jeder andere Agent sieht; alles andere zu validieren heißt, eine Hoffnung zu validieren.
Nur Discovery-Prüfung, nie Live-Aufrufe
Eingefügtes JSON bleibt im Browser; Live-Abrufe laufen über den Same-Origin-Helfer und ausschließlich gegen die öffentliche Card-URL. Der Validator kontaktiert nie den Agent hinter der Card: keine Skill-Aufrufe, keine Task-Übermittlung, kein JSON-RPC-Verkehr, keine Callback-Ausführung. Geprüft werden die praktisch lokal verifizierbaren Felder — ein Bestehen ist ein solider Preflight; die Konformität gegen das offizielle A2A-Schema und die eigenen Implementierungstests bleibt der zweite Schritt.
Häufige Fragen
Wo muss die Card liegen?
Für v0.2 ist der historische Well-known-Pfad /.well-known/agent.json. v0.3 und v1.0 verwenden /.well-known/agent-card.json. Eine explizite Card-URL kann ebenfalls geprüft werden, wird aber getrennt von erfolgreicher Well-known-Discovery ausgewiesen.
Testet die Card-Validierung meinen Agent?
Nein. Ein gültiges Ergebnis belegt nur die geprüfte JSON-Struktur und Abruf-Evidenz. Es ruft keinen Endpunkt auf, beweist keine Authentifizierung oder Protokollfunktion und verifiziert deklarierte Signaturen nicht kryptografisch.
Was gehört in die Card — und was darf nie hinein?
Hinein gehören Identität, Skills, Transporte, Endpunkt-URLs und Authentifizierungsanforderungen. Niemals hinein gehören Geheimnisse: keine API-Keys, keine Tokens, keine internen Hostnamen. Die Card ist per Definition öffentlich — schreibe sie in dem Wissen, dass auch Angreifer sie lesen.
Wie granular sollten Skills geschnitten sein?
So granular, dass ein konsumierender Agent allein anhand der Beschreibung wählen kann. Ein Alleskönner-Skill zwingt Aufrufer zum Raten; ein Dutzend fast identischer Skills zwingt sie zum Disambiguieren. Skill-Grenzen sind API-Design — mit einem Modell als Leser.
Warum überhaupt Authentifizierung in der Card deklarieren?
Damit Aufrufer vor dem ersten fehlschlagenden Request entscheiden können, ob sie mit dir sprechen können. Deklarierte Schemes müssen dem Deployment exakt entsprechen — OAuth bewerben und API-Keys erzwingen kostet jeden Konsumenten eine verwirrende Runde, oder gleich die ganze Integration.
Wie oft sollte sich die Card ändern?
Immer dann, wenn sich Skills, Endpunkte, Transporte oder Auth ändern — atomar mit dem Deployment, versioniert wie ein API-Vertrag. Eine veraltete Card bringt anderen Agents falsche Fakten über dich bei, und sie handeln nach diesen Fakten.