ard.json

Agentic Resource Discovery (ARD) adalah spesifikasi untuk membuat katalog resource agentic. Manifes ard.json menjelaskan resource agentic di domain, seperti server MCP, agen A2A, dan keahlian agen, sehingga agen dan registry AI dapat menemukannya.

Cara kerja audit Lighthouse

Proses penemuan: Audit mencari manifes berdasarkan mekanisme penemuan dalam spesifikasi ARD (§5.1):

  • Memeriksa perintah Agentmap: di dalam robots.txt.
  • Memindai HTML untuk menemukan tag <link rel="ard" href="...">.
  • Memeriksa respons header Link: <...>; rel="ard" HTTP.
  • Mengambil dari endpoint umum /.well-known/ard.json.

Jika penemuan utama gagal, Lighthouse akan memeriksa jalur lama (seperti rel="ai-catalog" atau /.well-known/ai-catalog.json). Meskipun konten yang ditemukan di sini masih divalidasi, peringatan akan muncul karena klien ARD standar tidak berkewajiban untuk mendukung rute yang tidak digunakan lagi.

Aturan validasi: Verifikasi dilakukan menggunakan port JavaScript dari suite kesesuaian ARD v0.91, yang menguji kriteria berikut:

Error kesesuaian dan validasi:

  • Sintaksis dan skema: Manifes adalah JSON yang valid dan cocok dengan skema manifes ARD, dan setiap entri cocok dengan skema entri ARD. Lighthouse tidak mengambil atau memvalidasi artefak yang ditunjuk oleh entri (misalnya, kartu server MCP di url).
  • Kolom wajib diisi: Manifes berisi array entries, dan setiap entri berisi identifier, displayName, dan type.
  • URN yang ditambatkan ke domain: Setiap identifier mengikuti format urn:air:<publisher>:<namespace>:<name>.
  • Definisi lokasi: Setiap entri menentukan tepat satu dari url atau data inline, tidak pernah keduanya atau tidak sama sekali.
  • Struktur manifes kepercayaan: Jika trustManifest disertakan, manifes tersebut adalah objek dengan properti identity.

Peringatan praktik terbaik:

  • Kueri representatif: Setiap entri memiliki array representativeQueries dengan 2–5 kueri contoh. Registry membuat indeks penelusuran dari metadata ini, sehingga entri tanpa metadata tidak akan muncul di hasil penelusuran. (Jika ada, string ini harus berupa array string; hal lain akan menyebabkan error.)
  • Jenis media: type harus berupa jenis media yang terbentuk dengan baik. Lighthouse memperingatkan tentang jenis yang tidak digunakan lagi (misalnya, application/mcp-server+json ke application/mcp-server-card+json), jenis standar dengan parameter yang tidak ada atau tambahan, dan jenis yang tidak dikenal di luar application/*. Jenis application/* kustom diizinkan.
  • Collections: Menandai kolom collections level teratas. Hierarki ini tidak lagi menjadi bagian dari ARD dan diabaikan; sebagai gantinya, hierarki model berada di dalam entries.
  • Endpoint lama: Menandai manifes yang hanya ditemukan melalui lokasi ai-catalog lama.
  • Lokasi yang diiklankan rusak: Menandai lokasi yang diiklankan (link Agentmap:, rel="ard", atau rel="ai-catalog", atau header Link) yang tidak dapat dimuat saat manifes ditemukan di tempat lain.

Tidak diperlukan:

  • specVersion dan kolom tingkat teratas tambahan lainnya tidak memengaruhi skor.
  • capabilities bersifat opsional dan tidak diberi skor. Jika resource Anda mengekspos alat atau keterampilan bernama, pertimbangkan untuk mencantumkannya (misalnya, ["WeatherTool", "ForecastTool"]) sehingga registry dapat memfilternya tanpa mengambil artefak lengkap. Jika disertakan, parameter ini harus berupa array string.

Membaca tabel hasil

Kolom Element menampilkan Root untuk masalah pada manifes secara keseluruhan. Untuk masalah pada entri, alat ini akan menampilkan displayName entri, kembali ke identifier, atau Entry #n jika keduanya tidak tersedia. Satu masalah skema dapat muncul dua kali, sekali di bagian Root dan sekali di bagian entri, yang cocok dengan output pengujian kesesuaian resmi.

Memahami skor Anda

Hasil audit ditampilkan dengan cara berikut:

  • Lulus (1): Manifes ditemukan dan tidak memiliki error atau peringatan.
  • Kredit parsial (0,9): Manifes valid, tetapi memiliki setidaknya satu peringatan praktik terbaik.
  • Gagal (0): Error kesesuaian apa pun, seperti JSON yang salah format, pelanggaran skema, URN yang tidak valid, atau keduanya atau tidak satu pun dari url/data. Audit juga gagal jika manifes diberitahukan (melalui robots.txt, link rel="ard" atau rel="ai-catalog", atau header Link), tetapi tidak dapat dimuat.
  • Tidak berlaku: Tidak ada manifes yang ditemukan dengan metode apa pun. Hal ini tidak memengaruhi skor Lighthouse Anda.

Cara memperbaiki

Untuk lulus audit, ikuti langkah-langkah yang dapat ditindaklanjuti berikut:

  1. Sediakan manifes Anda di /.well-known/ard.json, atau tautkan dengan rel=ard. Jika Anda menggunakan ai-catalog.json atau rel=ai-catalog, pindah ke nama baru.
  2. Perbaiki error yang tercantum dalam tabel audit agar manifes cocok dengan skema ARD.
  3. Berikan ID urn:air:... dan tepat satu dari url atau data untuk setiap entri.
  4. Gunakan jenis media ARD standar di type jika berlaku.
  5. Tambahkan 2 hingga 5 representativeQueries ke setiap entri untuk mendapatkan skor sempurna.