ard.json

Agentic Resource Discovery (ARD) ist eine Spezifikation zum Katalogisieren von agentischen Ressourcen. Das ard.json-Manifest beschreibt agentische Ressourcen in einer Domain, z. B. MCP-Server, A2A-Agenten und Agenten-Skills, damit KI-Agenten und Registries sie finden können.

So funktioniert die Lighthouse-Prüfung

Erkennungsprozess: Bei der Prüfung wird anhand der Erkennungsmechanismen in der ARD-Spezifikation (§ 5.1) nach dem Manifest gesucht:

  • Es wird nach einer Agentmap:-Anweisung in robots.txt gesucht.
  • HTML wird nach <link rel="ard" href="...">-Tags durchsucht.
  • Prüfung auf eine HTTP-Link: <...>; rel="ard"-Header-Antwort.
  • Abruf vom bekannten Endpunkt /.well-known/ard.json.

Wenn die primäre Erkennung fehlschlägt, prüft Lighthouse Legacy-Pfade (z. B. rel="ai-catalog" oder /.well-known/ai-catalog.json). Die hier gefundenen Inhalte werden zwar weiterhin validiert, es wird jedoch eine Warnung ausgegeben, da Standard-ARD-Clients nicht verpflichtet sind, veraltete Pfade zu unterstützen.

Validierungsregeln: Die Überprüfung erfolgt mit einem JavaScript-Port der Konformitätssuite von ARD v0.91. Dabei werden die folgenden Kriterien geprüft:

Konformitäts- und Validierungsfehler:

  • Syntax und Schema: Das Manifest ist gültiges JSON und entspricht dem ARD-Manifestschema. Jeder Eintrag entspricht dem ARD-Eintragsschema. Lighthouse ruft das Artefakt, auf das ein Eintrag verweist, nicht ab und validiert es auch nicht (z. B. die MCP-Serverkarte unter url).
  • Pflichtfelder: Das Manifest enthält ein entries-Array und jeder Eintrag enthält ein identifier, displayName und type.
  • Domainverankerte URNs: Jede identifier folgt dem Format urn:air:<publisher>:<namespace>:<name>.
  • Standortdefinition: Jeder Eintrag definiert genau einen url oder Inline-data, nie beides oder keines von beiden.
  • Struktur des Vertrauensmanifests: Wenn ein trustManifest enthalten ist, handelt es sich um ein Objekt mit einer identity-Property.

Best-Practice-Warnungen:

  • Repräsentative Abfragen: Jeder Eintrag enthält ein representativeQueries-Array mit 2–5 Beispielabfragen. Registries erstellen ihren Suchindex anhand dieser Angaben. Ein Eintrag ohne diese Angaben wird daher nicht in den Suchergebnissen angezeigt. (Falls vorhanden, muss es ein Array von Strings sein. Alles andere ist ein Fehler.)
  • Medientyp: type muss ein gültiger Medientyp sein. Lighthouse warnt vor verworfenen Typen (z. B. application/mcp-server+json bis application/mcp-server-card+json), Standardtypen mit fehlenden oder zusätzlichen Parametern und nicht erkannten Typen außerhalb von application/*. Benutzerdefinierte application/*-Typen sind zulässig.
  • Sammlungen: Kennzeichnet ein collections-Feld auf oberster Ebene. Es ist nicht mehr Teil von ARD und wird ignoriert. Verwenden Sie stattdessen Modellhierarchien in entries.
  • Legacy-Endpunkte: Markiert Manifeste, die nur über die Legacy-ai-catalog-Standorte gefunden werden.
  • Fehlerhafte beworbene Standorte: Kennzeichnet alle beworbenen Standorte (Agentmap:-, rel="ard"- oder rel="ai-catalog"-Link oder Link-Header), die nicht geladen werden konnten, wenn das Manifest an anderer Stelle gefunden wurde.

Nicht erforderlich:

  • specVersion und andere zusätzliche Felder auf oberster Ebene haben keinen Einfluss auf die Punktzahl.
  • capabilities sind optional und werden nicht bewertet. Wenn Ihre Ressource benannte Tools oder Skills verfügbar macht, sollten Sie diese auflisten (z. B. ["WeatherTool", "ForecastTool"]), damit Registries danach filtern können, ohne das vollständige Artefakt abzurufen. Falls angegeben, muss es ein Array von Strings sein.

Ergebnistabelle auswerten

In der Spalte „Element“ wird Root für Probleme mit dem Manifest als Ganzes angezeigt. Bei Problemen mit einem Eintrag wird der displayName des Eintrags angezeigt. Wenn dieser nicht verfügbar ist, wird der identifier angezeigt. Wenn beide nicht verfügbar sind, wird Entry #n angezeigt. Ein einzelnes Schemaproblem kann zweimal auftreten, einmal unter Root und einmal unter dem Eintrag, was der Ausgabe des offiziellen Konformitätstests entspricht.

Informationen zu deinem Index

Die Auditergebnisse werden so dargestellt:

  • Bestanden (1): Das Manifest wurde gefunden und enthält keine Fehler oder Warnungen.
  • Teilweise Anerkennung (0,9): Das Manifest ist gültig, enthält aber mindestens eine Best-Practice-Warnung.
  • Fehler (0): Ein Konformitätsfehler, z. B. fehlerhaftes JSON, ein Schemaverstoß, ein ungültiger URN oder beides oder keines von url/data. Die Prüfung schlägt auch fehl, wenn ein Manifest (über robots.txt, einen rel="ard"- oder rel="ai-catalog"-Link oder einen Link-Header) beworben wurde, aber nicht geladen werden konnte.
  • Nicht zutreffend: Es wurde kein Manifest gefunden. Dies hat keine Auswirkungen auf Ihr Lighthouse-Ergebnis.

Behebung

So bestehen Sie die Prüfung:

  1. Stelle das Manifest unter /.well-known/ard.json bereit oder verknüpfe es mit rel=ard. Wenn Sie ai-catalog.json oder rel=ai-catalog verwenden, wechseln Sie zu den neuen Namen.
  2. Beheben Sie alle in der Prüftabelle aufgeführten Fehler, damit das Manifest dem ARD-Schema entspricht.
  3. Geben Sie für jeden Eintrag eine urn:air:...-ID und genau einen url- oder data-Wert an.
  4. Verwenden Sie in type einen Standard-ARD-Medientyp, sofern zutreffend.
  5. Fügen Sie jedem Eintrag 2 bis 5 representativeQueries hinzu, um eine perfekte Punktzahl zu erhalten.