/.well-known/agent-card.json
Die von der A2A-v1.0-Spezifikation registrierte well-known URI. Neue Clients rufen zuerst diesen Pfad ab; stelle ihn mit dem Content-Type application/a2a+json bereit.
Discovery-Tool · A2A v1.0
A2A Agent Card Discovery-URLs prüfen
A2A-Clients entdecken einen Agenten, indem sie dessen JSON Agent Card von einer well-known URL abrufen. Teste beide Namenskonventionen an einer echten Domain und sieh genau, was Clients tatsächlich erhalten.
Erstellt beide Kandidaten-Discovery-URLs aus derselben Basisdomain.
Ruft das zurückgegebene JSON ab und meldet Statuscode und Content-Type.
Analysiert die Antwort nach Möglichkeit als Agent Card JSON.
Führt Bereitschaftsprüfungen für Schnittstellen, Skills, Provider, Modi, Capabilities und Sicherheitsmetadaten durch.
Öffentliche Agenten-Domain prüfen
Gib eine Basisdomain ein. Der Prüfer ruft beide Discovery-Pfade ab, analysiert das zurückgegebene JSON und führt Agent Card-Bereitschaftsprüfungen durch.
So funktioniert Discovery
Eine einzige well-known URL startet jede A2A-Integration.
Bevor ein anderer Agent Ihren Dienst aufrufen kann, ruft er die Agent Card von einer well-known URI (RFC 8615) auf Ihrer Domain ab, bewertet Skills und Sicherheitsanforderungen und ruft dann die bevorzugte Schnittstelle auf. Fehlt die Agent Card, ist sie veraltet oder hinter einer Weiterleitung versteckt, scheitert die Integration, bevor sie beginnt.
Diese Seite praktiziert, was sie prüft: AgentCard.net veröffentlicht seine eigene Agent Card unter beiden Pfaden, und das Beispiel rechts ist das echte Dokument.
Unsere Live-Agent Card ansehenagentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "AgentCard.net Toolkit",
"version": "1.0.0",
"supportedInterfaces": [
{ "url": "https://www.agentcard.net/api/agent-card",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0" }
],
"skills": [
{ "id": "generate-agent-card", ... },
{ "id": "validate-agent-card", ... },
{ "id": "check-well-known-discovery", ... }
]
}Discovery-Pfade
Zwei Konventionen, eine Agent Card.
/.well-known/agent.json
Wird von frühen A2A-Implementierungen und Codelab-Beispielen verwendet. Viele bereitgestellte Clients prüfen weiterhin nur diesen Pfad, daher ist es eine sichere Übergangsstrategie, hier dieselbe Agent Card bereitzustellen.
Veröffentlichungsmuster
Agent Card Discovery widerstandsfähig machen.
Discovery-Fehler sind selten exotisch: eine Weiterleitung, eine zwischengespeicherte Fehlerseite, oder ein Pfad bereitgestellt und der andere vergessen. Diese Veröffentlichungsroutine sorgt dafür, dass beide Konventionen stets dieselbe aktuelle Agent Card liefern.
- 1
Auf dem Standardpfad veröffentlichen
Stelle die geprüfte Agent Card unter /.well-known/agent-card.json per HTTPS auf derselben Domain wie den A2A-Dienst bereit, mit dem Content-Type application/a2a+json.
- 2
Legacy-Pfad spiegeln
Gib das identische Dokument auch unter /.well-known/agent.json zurück, solange ältere Clients noch im Umlauf sind — abweichende Agent Card auf beiden Pfaden verwirren das Routing.
- 3
Agent Card synchron halten
Wann immer sich Endpunkte, Skills, Capabilities oder Authentifizierung ändern, aktualisiere die Agent Card, erhöhe ihr version-Feld und stelle beide Pfade gemeinsam erneut bereit.
- 4
Nach jeder Änderung erneut prüfen
Führe diesen Prüfer nach Deployments, DNS-Änderungen, Gateway-Migrationen oder Marketplace-Bearbeitungen aus. Fehler lassen sich meist auf Weiterleitungen, HTML-Fehlerseiten oder einen vergessenen Pfad zurückführen.
FAQ
Häufige Fragen zu Well-known Agent JSON
Was zu veröffentlichen ist, wo es zu veröffentlichen ist, und wie Clients beider Konventionen funktionsfähig bleiben.
Welchen well-known Agent Card-Pfad sollte ich verwenden?
A2A v1.0 registriert /.well-known/agent-card.json als Standard-Discovery-Pfad. Der ältere /.well-known/agent.json stammt aus der Zeit vor v1.0, wird aber noch von vielen bereitgestellten Clients geprüft, daher ist die Veröffentlichung derselben Agent Card unter beiden Pfaden während der Übergangszeit die pragmatische Wahl.
Sollten beide Pfade identisches JSON zurückgeben?
Ja. Die Rückgabe derselben öffentlichen Agent Card von beiden Pfaden hält Clients konsistent, die nur eine Konvention unterstützen. Abweichende Dokumente lassen den Agenten je nach abgerufenem Pfad unterschiedlich erscheinen.
Mit welchem Content-Type sollte die Agent Card bereitgestellt werden?
Die Spezifikation registriert application/a2a+json für Agent Cards. Einfaches application/json wird in der Praxis breit akzeptiert, aber ein HTML-Content-Type ist ein zuverlässiges Zeichen dafür, dass der Pfad eine Fehlerseite statt der Agent Card zurückgibt.
Kann die öffentliche Agent Card private Capabilities verbergen?
Ja. Veröffentliche in der öffentlichen Agent Card nur für die Discovery unbedenkliche Metadaten, setze capabilities.extendedAgentCard auf true und stelle sensible Skills über die authentifizierte GetExtendedAgentCard-Operation bereit.
Warum schlagen Discovery-Prüfungen nach einem Deployment fehl?
Übliche Ursachen sind Weiterleitungen zu einer Login- oder Marketingseite, HTML-404-Seiten, die mit Status 200 zurückgegeben werden, veraltetes, in einem CDN zwischengespeichertes JSON, oder dass nur einer der beiden well-known Pfade bereitgestellt wurde. Der Prüfer meldet Statuscode und Content-Type für jeden Pfad, sodass der Fehler sofort sichtbar wird.
Vor der Veröffentlichung
Agent Card validieren, dann URLs prüfen.
Lasse das JSON zuerst durch den vollständigen Validator laufen, veröffentliche es unter beiden well-known Pfaden und bestätige die Discovery mit diesem Prüfer.