ard.json

Agentic Resource Discovery (ARD) to specyfikacja katalogowania zasobów agentowych. Plik manifestu ard.json opisuje zasoby agentowe w domenie, takie jak serwery MCP, agenty A2A i umiejętności agentów, dzięki czemu agenty AI i rejestry mogą je znaleźć.

Jak działa kontrola Lighthouse

Proces wykrywania: audyt wyszukuje plik manifestu na podstawie mechanizmów wykrywania opisanych w specyfikacji ARD (§5.1):

  • Sprawdzam, czy w pliku robots.txt znajduje się dyrektywa Agentmap:.
  • Skanuję kod HTML w poszukiwaniu tagów <link rel="ard" href="...">.
  • Sprawdzanie odpowiedzi nagłówka HTTP Link: <...>; rel="ard".
  • Pobieram z dobrze znanego punktu końcowego /.well-known/ard.json.

Jeśli podstawowe wykrywanie się nie powiedzie, Lighthouse sprawdza starsze ścieżki (takie jak rel="ai-catalog" lub /.well-known/ai-catalog.json). Treści znalezione w tych miejscach są nadal sprawdzane, ale pojawia się ostrzeżenie, ponieważ standardowi klienci ARD nie muszą obsługiwać wycofanych ścieżek.

Reguły weryfikacji: weryfikacja jest przeprowadzana za pomocą JavaScriptu pakietu zgodności ARD w wersji 0.91, który sprawdza te kryteria:

Błędy zgodności i walidacji:

  • Składnia i schemat: plik manifestu jest prawidłowym plikiem JSON i jest zgodny ze schematem pliku manifestu ARD, a każdy wpis jest zgodny ze schematem wpisu ARD. Lighthouse nie pobiera ani nie weryfikuje artefaktu, do którego prowadzi wpis (np. karty serwera MCP pod adresem url).
  • Wymagane pola: plik manifestu zawiera tablicę entries, a każdy wpis zawiera pola identifier, displayName i type.
  • Nazwy URN powiązane z domeną: każda nazwa identifier ma format urn:air:<publisher>:<namespace>:<name>.
  • Definicja lokalizacji: każdy wpis definiuje dokładnie 1 element url lub wbudowany element data, nigdy oba ani żaden z nich.
  • Struktura pliku manifestu zaufania: gdy uwzględniony jest element trustManifest, jest to obiekt z właściwością identity.

Ostrzeżenia dotyczące sprawdzonych metod:

  • Reprezentatywne zapytania: każdy wpis zawiera tablicę representativeQueries z 2–5 przykładowymi zapytaniami. Rejestry tworzą na ich podstawie indeks wyszukiwania, więc wpis bez nich nie pojawi się w wynikach wyszukiwania. (Jeśli jest obecny, musi być tablicą ciągów znaków. Każda inna wartość jest błędem).
  • Typ multimediów: type musi być prawidłowo sformatowanym typem multimediów. Lighthouse ostrzega o wycofanych typach (np. application/mcp-server+json do application/mcp-server-card+json), typach standardowych z brakującymi lub dodatkowymi parametrami oraz nierozpoznanych typach poza application/*. Dozwolone są niestandardowe typy application/*.
  • Kolekcje: oznacza pole collections najwyższego poziomu. Nie jest już częścią ARD i jest ignorowany. Zamiast tego hierarchie modeli znajdują się wewnątrz entries.
  • Starsze punkty końcowe: oznacza pliki manifestu, które można znaleźć tylko w starszych lokalizacjach ai-catalog.
  • Uszkodzone lokalizacje reklamowane: oznacza każdą reklamowaną lokalizację (link Agentmap:, rel="ard" lub rel="ai-catalog" albo nagłówek Link), której nie udało się wczytać, gdy plik manifestu został znaleziony w innym miejscu.

Niewymagane:

  • specVersion i inne dodatkowe pola najwyższego poziomu nie mają wpływu na wynik.
  • Pytania oznaczone jako capabilities są opcjonalne i nie są oceniane. Jeśli zasób udostępnia nazwane narzędzia lub umiejętności, rozważ ich wymienienie (np. ["WeatherTool", "ForecastTool"]), aby rejestry mogły je filtrować bez pobierania pełnego artefaktu. Jeśli jest uwzględniona, musi być tablicą ciągów znaków.

Interpretowanie tabeli wyników

W kolumnie Element wyświetla się Root w przypadku problemów z całym plikiem manifestu. W przypadku problemów z wpisem wyświetla się displayName wpisu, a jeśli nie jest dostępny, to identifier lub Entry #n. Pojedynczy problem ze schematem może pojawić się dwukrotnie – raz w sekcji Root i raz we wpisie, co odpowiada wynikom oficjalnego testu zgodności.

Interpretowanie wyniku

Wyniki kontroli są wyświetlane w następujący sposób:

  • Zaliczone (1): znaleziono plik manifestu i nie zawiera on błędów ani ostrzeżeń.
  • Częściowe zaliczenie (0,9): plik manifestu jest prawidłowy, ale zawiera co najmniej 1 ostrzeżenie dotyczące sprawdzonych metod.
  • Niepowodzenie (0): dowolny błąd zgodności, taki jak nieprawidłowy format JSON, naruszenie schematu, nieprawidłowy identyfikator URN, brak obu lub żadnego z pól url/data. Kontrola nie powiedzie się też, jeśli manifest został zareklamowany (za pomocą robots.txt, linku rel="ard" lub rel="ai-catalog" albo nagłówka Link), ale nie udało się go wczytać.
  • Nie dotyczy: nie znaleziono pliku manifestu żadną metodą. Nie ma to wpływu na wynik Lighthouse.

Sposób naprawienia

Aby przejść kontrolę, wykonaj te czynności:

  1. Udostępnij plik manifestu w /.well-known/ard.json lub połącz go z rel=ard. Jeśli używasz ai-catalog.json lub rel=ai-catalog, przejdź na nowe nazwy.
  2. Popraw błędy wymienione w tabeli kontrolnej, aby plik manifestu był zgodny ze schematem ARD.
  3. Każdy wpis musi mieć identyfikator urn:air:... oraz dokładnie 1 identyfikator url lub data.
  4. W polu type używaj standardowego typu multimediów ARD, jeśli jest on dostępny.
  5. Aby uzyskać idealny wynik, dodaj od 2 do 5 representativeQueries do każdego wpisu.