ard.json

Agentic Resource Discovery (ARD) is een specificatie voor het catalogiseren van agentic resources. Het ard.json-manifest beschrijft agentische bronnen in een domein, zoals MCP-servers, A2A-agents en agentvaardigheden, zodat AI-agents en registers ze kunnen vinden.

Hoe de Lighthouse-controle werkt

Ontdekkingsproces: De controle zoekt naar het manifest op basis van de ontdekkingsmechanismen in de ARD-specificatie (§5.1):

  • Controleren op een Agentmap:-instructie in robots.txt.
  • HTML scannen op <link rel="ard" href="...">-tags.
  • Controleren op een HTTP-headerreactie van Link: <...>; rel="ard".
  • Ophalen van het bekende eindpunt /.well-known/ard.json.

Als de primaire ontdekking mislukt, controleert Lighthouse verouderde paden (zoals rel="ai-catalog" of /.well-known/ai-catalog.json). Hoewel content die hier wordt gevonden nog steeds wordt gevalideerd, wordt er een waarschuwing gegeven omdat standaard ARD-clients niet verplicht zijn om beëindigde routes te ondersteunen.

Validatieregels: De verificatie wordt uitgevoerd met een JavaScript-poort van de ARD v0.91 conformiteitssuite, die test op de volgende criteria:

Overeenstemmings- en validatiefouten:

  • Syntaxis en schema: Het manifest is een geldige json en komt overeen met het ARD-manifestschema. Elke invoer komt overeen met het ARD-invoerschema. Lighthouse haalt het artefact waarnaar een item verwijst niet op en valideert het niet (bijvoorbeeld de MCP-serverkaart op url).
  • Vereiste velden: Het manifest bevat een entries-matrix en elk item bevat een identifier, displayName en type.
  • Aan domein verankerde URN's: Elke identifier volgt de indeling urn:air:<publisher>:<namespace>:<name>.
  • Locatiedefinitie: Elke invoer definieert precies één van url of inline data, nooit beide of geen van beide.
  • Structuur van vertrouwensmanifest: Als een trustManifest is opgenomen, is dit een object met een identity-property.

Waarschuwingen voor best practices:

  • Representatieve zoekopdrachten: Elk item heeft een representativeQueries-matrix met 2 tot 5 voorbeeldzoekopdrachten. Registers bouwen hun zoekindex op basis hiervan op, dus een vermelding zonder deze gegevens verschijnt niet in de zoekresultaten. (Als deze aanwezig is, moet het een matrix van tekenreeksen zijn. Al het andere is een fout.)
  • Mediatype: type moet een correct opgemaakt mediatype zijn. Lighthouse waarschuwt voor beëindigde typen (bijvoorbeeld application/mcp-server+json tot application/mcp-server-card+json), standaardtypen met ontbrekende of extra parameters en niet-herkende typen buiten application/*. Aangepaste application/*-typen zijn toegestaan.
  • Collecties: Markeert een collections-veld op het hoogste niveau. Het maakt geen deel meer uit van ARD en wordt genegeerd. Gebruik in plaats daarvan modelhiërarchieën in entries.
  • Verouderde eindpunten: Markeert manifesten die alleen worden gevonden via de verouderde locaties van ai-catalog.
  • Defecte geadverteerde locaties: Markeert geadverteerde locaties (Agentmap:-, rel="ard"- of rel="ai-catalog"-link of Link-header) die niet kunnen worden geladen als het manifest ergens anders is gevonden.

Niet vereist:

  • specVersion en andere extra velden op het hoogste niveau hebben geen invloed op de score.
  • capabilities zijn optioneel en worden niet beoordeeld. Als je bron benoemde tools of vaardigheden beschikbaar maakt, kun je deze vermelden (bijvoorbeeld ["WeatherTool", "ForecastTool"]) zodat registers erop kunnen filteren zonder het hele artefact op te halen. Als deze is opgenomen, moet het een matrix van tekenreeksen zijn.

De resultaattabel lezen

In de kolom Element staat Root voor problemen met het manifest als geheel. Voor problemen met een item wordt de displayName van het item getoond, of de identifier of Entry #n als geen van beide beschikbaar is. Een probleem met één schema kan 2 keer verschijnen, een keer onder Root en een keer onder de invoer, overeenkomend met de uitvoer van de officiële conformiteitstest.

Inzicht in je score

De controleresultaten worden op de volgende manieren weergegeven:

  • Geslaagd (1): Het manifest is gevonden en bevat geen fouten of waarschuwingen.
  • Gedeeltelijke punten (0,9): Het manifest is geldig, maar heeft minstens één waarschuwing voor best practices.
  • Mislukt (0): Een conformiteitsfout, zoals een onjuist opgemaakte JSON, een schemaviolatie, een ongeldige URN, of beide of geen van url/data. De controle mislukt ook als een manifest is aangekondigd (via robots.txt, een rel="ard"- of rel="ai-catalog"-link of een Link-header), maar niet kan worden geladen.
  • Niet van toepassing: Er is geen manifest gevonden met een van de methoden. Dit heeft geen invloed op je Lighthouse-score.

Oplossing

Volg deze stappen om de controle te doorstaan:

  1. Lever je manifest op /.well-known/ard.json of koppel het met rel=ard. Als u ai-catalog.json of rel=ai-catalog gebruikt, moet u overstappen naar de nieuwe namen.
  2. Los de fouten in de controletabel op, zodat het manifest overeenkomt met het ARD-schema.
  3. Geef elk item een urn:air:...-ID en exact één van url of data.
  4. Gebruik een standaard ARD-mediatype in type als dat van toepassing is.
  5. Voeg 2 tot 5 representativeQueries toe aan elk item om een perfecte score te krijgen.