ard.json

Agentic Resource Discovery (ARD), ajan tabanlı kaynakları kataloglamak için kullanılan bir spesifikasyondur. ard.json manifesti, bir alandaki temsilci kaynaklarını (ör. MCP sunucuları, A2A aracıları ve temsilci becerileri) tanımlar. Böylece yapay zeka aracıları ve kayıt otoriteleri bu kaynakları bulabilir.

Lighthouse denetiminin işleyiş şekli

Keşif süreci: Denetim, ARD spesifikasyonundaki (§5.1) keşif mekanizmalarına göre manifesti arar:

  • robots.txt içinde Agentmap: yönergesi olup olmadığı kontrol ediliyor.
  • HTML, <link rel="ard" href="..."> etiketleri için taranıyor.
  • HTTP Link: <...>; rel="ard" üstbilgi yanıtı için denetleniyor.
  • Bilinen uç noktadan (/.well-known/ard.json) getiriliyor.

Birincil keşif başarısız olursa Lighthouse, eski yolları (ör. rel="ai-catalog" veya /.well-known/ai-catalog.json) kontrol eder. Burada bulunan içerik hâlâ doğrulanır ancak standart ARD istemcilerinin desteği sonlandırılmış rotaları desteklemesi zorunlu olmadığından bir uyarı gösterilir.

Doğrulama kuralları: Doğrulama, ARD v0.91 uygunluk paketinin JavaScript bağlantı noktası kullanılarak gerçekleştirilir ve aşağıdaki ölçütler test edilir:

Uygunluk ve doğrulama hataları:

  • Söz dizimi ve şema: Manifest geçerli bir JSON'dur ve ARD manifest şemasıyla eşleşir. Her giriş, ARD giriş şemasıyla eşleşir. Lighthouse, bir girişin işaret ettiği yapıyı (ör. url adresindeki MCP sunucu kartı) getirmez veya doğrulamaz.
  • Zorunlu alanlar: Manifest bir entries dizisi içerir ve her giriş bir identifier, displayName ve type içerir.
  • Alana sabitlenmiş URN'ler: Her identifier, urn:air:<publisher>:<namespace>:<name> biçimindedir.
  • Konum tanımı: Her giriş, url veya satır içi data öğelerinden yalnızca birini tanımlar. İkisini birden veya hiçbirini tanımlamaz.
  • Güven manifesti yapısı: trustManifest eklendiğinde, identity özelliğine sahip bir nesnedir.

En iyi uygulama uyarıları:

  • Temsili sorgular: Her giriş, 2-5 örnek sorgu içeren bir representativeQueries dizisine sahiptir. Kayıt defterleri, arama dizinlerini bunlardan oluşturur. Bu nedenle, bunlar olmadan bir giriş arama sonuçlarında görünmez. (Varsa dize dizisi olmalıdır. Diğer her şey hata olarak kabul edilir.)
  • Medya türü: type, doğru biçimlendirilmiş bir medya türü olmalıdır. Lighthouse, desteği sonlandırılan türler (ör. application/mcp-server+json - application/mcp-server-card+json), eksik veya ek parametreleri olan standart türler ve application/* dışındaki tanınmayan türler hakkında uyarıda bulunur. Özel application/* türlerine izin verilir.
  • Koleksiyonlar: Üst düzey bir collections alanını işaretler. Artık ARD'nin bir parçası değildir ve yoksayılır. Bunun yerine entries içindeki model hiyerarşileri kullanılır.
  • Eski uç noktalar: Yalnızca eski ai-catalog konumlarında bulunan manifestleri işaretler.
  • Bozuk reklam konumları: Manifest başka bir yerde bulunduğunda yüklenemeyen tüm reklam konumlarını (Agentmap:, rel="ard" veya rel="ai-catalog" bağlantısı ya da Link başlığı) işaretler.

Zorunlu değil:

  • specVersion ve diğer ek üst düzey alanlar puanı etkilemez.
  • capabilities isteğe bağlıdır ve puanlanmaz. Kaynağınız adlandırılmış araçları veya becerileri gösteriyorsa bunları listeleyin (ör. ["WeatherTool", "ForecastTool"]). Böylece kayıt defterleri, tüm yapıyı getirmeden bunları filtreleyebilir. Dahil edilirse dize dizisi olmalıdır.

Sonuç tablosunu okuma

Öğe sütununda, manifest dosyasının tamamıyla ilgili sorunlar için Root gösterilir. Bir girişle ilgili sorunlar için girişin displayName değerini gösterir. Bu değer yoksa identifier değerini, ikisi de yoksa Entry #n değerini gösterir. Tek bir şema sorunu iki kez görünebilir: Bir kez Root altında ve bir kez de girişin altında. Bu, resmi uygunluk testinin çıkışıyla eşleşir.

Puanınızı anlama

Denetim sonuçları aşağıdaki şekillerde yansıtılır:

  • Başarılı (1): Manifest bulundu ve hata veya uyarı yok.
  • Kısmi kredi (0,9): Manifest geçerli ancak en az bir en iyi uygulama uyarısı var.
  • Başarısız (0): Hatalı biçimlendirilmiş JSON, şema ihlali, geçersiz URN veya url/data değerlerinden her ikisi ya da hiçbiri gibi herhangi bir uygunluk hatası. Bir manifest bildirildiyse (robots.txt, rel="ard" veya rel="ai-catalog" bağlantısı ya da Link başlığı aracılığıyla) ancak yüklenemediyse de denetim başarısız olur.
  • Geçerli değil: Hiçbir yöntemle manifest bulunamadı. Bu durum Lighthouse puanınızı etkilemez.

Nasıl düzeltilir?

Denetimi geçmek için şu uygulanabilir adımları izleyin:

  1. Manifestinizi /.well-known/ard.json adresinde sunun veya rel=ard ile bağlayın. ai-catalog.json veya rel=ai-catalog kullanıyorsanız yeni adlara geçin.
  2. Manifestin ARD şemasıyla eşleşmesi için denetim tablosunda listelenen hataları düzeltin.
  3. Her girişe bir urn:air:... tanımlayıcısı ve tam olarak bir url veya data ekleyin.
  4. Geçerli olduğu durumlarda type için standart bir ARD medya türü kullanın.
  5. Mükemmel bir puan almak için her girişe 2 ila 5 representativeQueries ekleyin.