ard.json

Agentic Resource Discovery (ARD) è una specifica per la catalogazione delle risorse agentiche. Il manifest ard.json descrive le risorse agentiche di un dominio, come i server MCP, gli agenti A2A e le skill degli agenti, in modo che gli agenti AI e i registri possano trovarli.

Come funziona il controllo di Lighthouse

Processo di rilevamento: il controllo cerca il manifest in base ai meccanismi di rilevamento nella specifica ARD (§5.1):

  • Controllo della presenza di un'istruzione Agentmap: all'interno di robots.txt.
  • Scansione del codice HTML per i tag <link rel="ard" href="...">.
  • Ispezione di una risposta dell'intestazione HTTP Link: <...>; rel="ard".
  • Recupero dall'endpoint noto /.well-known/ard.json.

Se il rilevamento principale non va a buon fine, Lighthouse controlla i percorsi legacy (come rel="ai-catalog" o /.well-known/ai-catalog.json). Sebbene i contenuti trovati qui vengano comunque convalidati, viene generato un avviso perché i client ARD standard non sono tenuti a supportare i percorsi deprecati.

Regole di convalida: la verifica viene eseguita utilizzando una porta JavaScript della suite di conformità ARD v0.91, testando i seguenti criteri:

Errori di conformità e convalida:

  • Sintassi e schema: il manifest è un JSON valido e corrisponde allo schema del manifest ARD. Inoltre, ogni voce corrisponde allo schema della voce ARD. Lighthouse non recupera né convalida l'artefatto a cui rimanda una voce (ad esempio, la scheda del server MCP all'indirizzo url).
  • Campi obbligatori: il manifest contiene un array entries e ogni voce contiene identifier, displayName e type.
  • URN ancorati al dominio: ogni identifier segue il formato urn:air:<publisher>:<namespace>:<name>.
  • Definizione della posizione: ogni voce definisce esattamente uno dei valori url o data in linea, mai entrambi o nessuno dei due.
  • Struttura del manifest di attendibilità: quando è incluso un trustManifest, si tratta di un oggetto con una proprietà identity.

Avvisi relativi alle best practice:

  • Query rappresentative: ogni voce ha un array representativeQueries con 2-5 query di esempio. I registri creano il loro indice della Ricerca a partire da questi elementi, quindi una voce senza questi elementi non verrà visualizzata nei risultati di ricerca. (Se presente, deve essere un array di stringhe; qualsiasi altro valore è un errore).
  • Tipo di media: type deve essere un tipo di media nel formato corretto. Lighthouse segnala i tipi deprecati (ad esempio, da application/mcp-server+json a application/mcp-server-card+json), i tipi standard con parametri mancanti o aggiuntivi e i tipi non riconosciuti al di fuori di application/*. Sono consentiti tipi application/* personalizzati.
  • Raccolte: contrassegna un campo collections di primo livello. Non fa più parte di ARD e viene ignorato; modella invece le gerarchie all'interno di entries.
  • Endpoint legacy: segnala i manifest che si trovano solo nelle posizioni ai-catalog legacy.
  • Località pubblicizzate non funzionanti: segnala qualsiasi località pubblicizzata (link Agentmap:, rel="ard" o rel="ai-catalog" o intestazione Link) che non è stato possibile caricare quando il manifest è stato trovato altrove.

Non obbligatoria:

  • specVersion e altri campi aggiuntivi di primo livello non influiscono sul punteggio.
  • capabilities sono facoltativi e non vengono valutati. Se la risorsa espone strumenti o competenze con nome, valuta la possibilità di elencarli (ad esempio, ["WeatherTool", "ForecastTool"]) in modo che i registry possano filtrarli senza recuperare l'intero artefatto. Se incluso, deve essere un array di stringhe.

Consulta la tabella dei risultati

La colonna Elemento mostra Root per i problemi relativi al file manifest nel suo complesso. Per i problemi relativi a una voce, viene mostrato il displayName della voce, con il fallback al identifier o al Entry #n se nessuno dei due è disponibile. Un singolo problema dello schema potrebbe essere visualizzato due volte, una volta in Root e una volta nella voce, in modo da corrispondere all'output del test di conformità ufficiale.

Comprendi il tuo punteggio

I risultati del controllo vengono mostrati nei seguenti modi:

  • Superato (1): il file manifest è stato trovato e non presenta errori o avvisi.
  • Credito parziale (0,9): il manifest è valido, ma presenta almeno un avviso relativo alle best practice.
  • Fail (0): qualsiasi errore di conformità, ad esempio JSON non valido, una violazione dello schema, un URN non valido o entrambi o nessuno dei due url/data. Il controllo non va a buon fine anche se un manifest è stato annunciato (tramite robots.txt, un link rel="ard" o rel="ai-catalog" o un'intestazione Link), ma non è stato possibile caricarlo.
  • Non applicabile: non è stato trovato alcun manifest con nessun metodo. Ciò non influisce sul tuo punteggio Lighthouse.

Come risolvere il problema

Per superare il controllo, segui questi passaggi:

  1. Pubblica il manifest in /.well-known/ard.json o collegalo con rel=ard. Se utilizzi ai-catalog.json o rel=ai-catalog, passa ai nuovi nomi.
  2. Correggi gli eventuali errori elencati nella tabella di controllo in modo che il manifest corrisponda allo schema ARD.
  3. Assegna a ogni voce un identificatore urn:air:... e esattamente uno tra url o data.
  4. Utilizza un tipo di media ARD standard in type, se applicabile.
  5. Aggiungi da 2 a 5 representativeQueries a ogni voce per ottenere un punteggio perfetto.