ard.json

Agentic Resource Discovery (ARD) est une spécification permettant de cataloguer les ressources agentiques. Le fichier manifeste ard.json décrit les ressources agentiques d'un domaine, telles que les serveurs MCP, les agents A2A et les compétences des agents, afin que les agents IA et les registres puissent les trouver.

Fonctionnement de l'audit Lighthouse

Processus de découverte : l'audit recherche le fichier manifeste en fonction des mécanismes de découverte de la spécification ARD (§5.1) :

  • Recherche d'une directive Agentmap: dans robots.txt.
  • Analyse du code HTML pour détecter les balises <link rel="ard" href="...">…
  • Recherche d'une réponse d'en-tête HTTP Link: <...>; rel="ard".
  • Récupération à partir du point de terminaison connu /.well-known/ard.json.

Si la découverte principale échoue, Lighthouse vérifie les anciens chemins d'accès (comme rel="ai-catalog" ou /.well-known/ai-catalog.json). Bien que le contenu trouvé ici soit toujours validé, un avertissement est émis, car les clients ARD standards ne sont pas tenus de prendre en charge les routes obsolètes.

Règles de validation : la validation est effectuée à l'aide d'un port JavaScript de la suite de conformité ARD v0.91, qui teste les critères suivants :

Erreurs de conformité et de validation :

  • Syntaxe et schéma : le fichier manifeste est un fichier JSON valide et correspond au schéma du fichier manifeste ARD, et chaque entrée correspond au schéma d'entrée ARD. Lighthouse ne récupère pas ni ne valide l'artefact vers lequel pointe une entrée (par exemple, la fiche du serveur MCP à l'adresse url).
  • Champs obligatoires : le fichier manifeste contient un tableau entries, et chaque entrée contient un identifier, un displayName et un type.
  • URN ancrés au domaine : chaque identifier suit le format urn:air:<publisher>:<namespace>:<name>.
  • Définition de l'emplacement : chaque entrée définit exactement un url ou un data intégré, jamais les deux ni aucun des deux.
  • Structure du fichier manifeste de confiance : lorsqu'un trustManifest est inclus, il s'agit d'un objet avec une propriété identity.

Avertissements concernant les bonnes pratiques :

  • Requêtes représentatives : chaque entrée comporte un tableau representativeQueries contenant deux à cinq exemples de requêtes. Les registres créent leur index de recherche à partir de ces éléments. Par conséquent, une entrée sans ces éléments n'apparaîtra pas dans les résultats de recherche. (S'il est présent, il doit s'agir d'un tableau de chaînes. Tout autre élément est une erreur.)
  • Type de média : type doit être un type de média correctement formé. Lighthouse signale les types obsolètes (par exemple, application/mcp-server+json à application/mcp-server-card+json), les types standards avec des paramètres manquants ou supplémentaires, et les types non reconnus en dehors de application/*. Les types application/* personnalisés sont autorisés.
  • Collections : signale un champ collections de niveau supérieur. Il ne fait plus partie d'ARD et est ignoré. Utilisez plutôt les hiérarchies de modèles dans entries.
  • Anciens points de terminaison : signale les fichiers manifestes qui ne sont trouvés que via les anciens emplacements ai-catalog.
  • Emplacements annoncés non fonctionnels : signale tout emplacement annoncé (lien Agentmap:, rel="ard" ou rel="ai-catalog", ou en-tête Link) qui n'a pas pu être chargé lorsque le fichier manifeste a été trouvé ailleurs.

Non requis :

  • specVersion et les autres champs de premier niveau supplémentaires n'ont pas d'incidence sur le score.
  • capabilities sont facultatives et ne sont pas notées. Si votre ressource expose des outils ou des compétences nommés, envisagez de les lister (par exemple, ["WeatherTool", "ForecastTool"]) afin que les registres puissent les filtrer sans récupérer l'artefact complet. S'il est inclus, il doit s'agir d'un tableau de chaînes.

Lire le tableau des résultats

La colonne "Élément" affiche Root pour les problèmes liés au fichier manifeste dans son ensemble. Pour les problèmes liés à une entrée, il affiche le displayName de l'entrée, en revenant à son identifier, ou Entry #n si aucun n'est disponible. Un même problème de schéma peut apparaître deux fois, une fois sous Root et une fois sous l'entrée, correspondant au résultat du test de conformité officiel.

Comprendre votre score

Les résultats de l'audit sont reflétés de la manière suivante :

  • Réussite (1) : le fichier manifeste a été trouvé et ne comporte aucune erreur ni aucun avertissement.
  • Crédit partiel (0,9) : le fichier manifeste est valide, mais comporte au moins un avertissement concernant les bonnes pratiques.
  • Échec (0) : toute erreur de conformité, telle qu'un fichier JSON incorrect, une violation de schéma, un URN non valide, ou les deux ou aucun des deux url/data. L'audit échoue également si un fichier manifeste a été annoncé (via robots.txt, un lien rel="ard" ou rel="ai-catalog", ou un en-tête Link), mais n'a pas pu être chargé.
  • Non applicable : aucun fichier manifeste n'a été trouvé, quelle que soit la méthode. Cela n'affecte pas votre score Lighthouse.

Résolution des problèmes

Pour réussir l'audit, suivez ces étapes :

  1. Diffusez votre fichier manifeste sur /.well-known/ard.json ou associez-le à rel=ard. Si vous utilisez ai-catalog.json ou rel=ai-catalog, passez aux nouveaux noms.
  2. Corrigez les erreurs listées dans le tableau d'audit afin que le fichier manifeste corresponde au schéma ARD.
  3. Attribuez à chaque entrée un identifiant urn:air:... et exactement un url ou data.
  4. Utilisez un type de média ARD standard dans type, le cas échéant.
  5. Ajoutez entre 2 et 5 representativeQueries à chaque entrée pour obtenir un score parfait.