ard.json

Обнаружение ресурсов агентов (ARD) – это спецификация для каталогизации ресурсов агентов. Манифест ard.json описывает агентские ресурсы в домене, такие как MCP-серверы, A2A-агенты и навыки агентов, чтобы ИИ-агенты и реестры могли их находить.

Как работает аудит Lighthouse

Процесс обнаружения. Аудит ищет манифест на основе механизмов обнаружения, описанных в спецификации ARD (§5.1):

  • Проверка директивы Agentmap: в файле robots.txt.
  • Поиск тегов <link rel="ard" href="..."> в HTML-коде.
  • Проверка ответа заголовка HTTP Link: <...>; rel="ard".
  • Получение данных из конечной точки /.well-known/ard.json.

Если основной способ обнаружения не работает, Lighthouse проверяет устаревшие пути (например, rel="ai-catalog" или /.well-known/ai-catalog.json). Найденный контент проверяется, но выдается предупреждение, поскольку стандартные клиенты ARD не обязаны поддерживать устаревшие пути.

Правила проверки. Проверка выполняется с помощью JavaScript-порта системы аттестации ARD v0.91 по следующим критериям:

Ошибки соответствия и проверки:

  • Синтаксис и схема. Манифест является действительным файлом JSON и соответствует схеме манифеста ARD, а каждая запись соответствует схеме записи ARD. Lighthouse не получает и не проверяет объект, на который указывает запись (например, карточку сервера MCP по адресу url).
  • Обязательные поля. Манифест содержит массив entries, и каждая запись содержит identifier, displayName и type.
  • URN, привязанные к домену. Каждый identifier имеет формат urn:air:<publisher>:<namespace>:<name>.
  • Определение местоположения. Каждая запись определяет только одно из значений: url или встроенное data. Нельзя указать оба значения или не указать ни одного.
  • Структура манифеста доверия. Если включен объект trustManifest, он содержит свойство identity.

Предупреждения о рекомендациях

  • Примеры запросов. Каждая запись содержит массив representativeQueries с 2–5 примерами запросов. Реестры создают свой поисковый индекс на основе этих данных, поэтому запись без них не появится в результатах поиска. Если он есть, то должен быть массивом строк. Любое другое значение будет считаться ошибкой.
  • Тип медиаконтента. type должен быть правильно оформленным типом медиаконтента. Lighthouse предупреждает об устаревших типах (например, application/mcp-server+json вместо application/mcp-server-card+json), стандартных типах с отсутствующими или лишними параметрами и нераспознанных типах, не входящих в application/*. Допускаются специальные типы application/*.
  • Коллекции. Помечает поле collections верхнего уровня. Он больше не является частью ARD и игнорируется. Вместо него используются иерархии моделей внутри entries.
  • Устаревшие конечные точки. Помечает манифесты, которые можно найти только в устаревших местоположениях ai-catalog.
  • Неработающие рекламируемые местоположения. Помечает все рекламируемые местоположения (ссылки Agentmap:, rel="ard" или rel="ai-catalog", а также заголовок Link), которые не удалось загрузить, когда манифест был найден в другом месте.

Необязательные атрибуты:

  • specVersion и другие дополнительные поля верхнего уровня не влияют на оценку.
  • capabilities не оцениваются. Если ваш ресурс предоставляет именованные инструменты или навыки, рекомендуем перечислить их (например, ["WeatherTool", "ForecastTool"]), чтобы реестры могли фильтровать их без получения полного артефакта. Если он указан, то должен быть массивом строк.

Как читать таблицу результатов

В столбце "Элемент" для проблем с манифестом в целом указано значение Root. Если проблема связана с записью, то в отчете указывается ее displayName, а если он недоступен, то identifier или Entry #n. Одна и та же проблема со схемой может быть указана дважды: в разделе Root и в записи. Это соответствует результатам официального теста на соответствие.

Как интерпретировать оценку

Результаты аудита отражаются следующим образом:

  • Пройдено (1). Манифест найден, ошибок и предупреждений нет.
  • Частичный зачет (0,9). Манифест действителен, но есть хотя бы одно предупреждение о несоблюдении рекомендаций.
  • Fail (0). Любая ошибка соответствия, например неправильный формат JSON, нарушение схемы, недопустимый URN, а также наличие или отсутствие обоих полей url/data. Проверка также не будет пройдена, если манифест был объявлен (с помощью robots.txt, ссылки rel="ard" или rel="ai-catalog" или заголовка Link), но не был загружен.
  • Неприменимо. Манифест не найден ни одним из способов. Это не влияет на оценку Lighthouse.

Как устранить проблему

Чтобы пройти проверку, выполните следующие действия:

  1. Разместите манифест по адресу /.well-known/ard.json или добавьте ссылку на него с помощью rel=ard. Если вы используете ai-catalog.json или rel=ai-catalog, перейдите на новые названия.
  2. Исправьте все ошибки, перечисленные в таблице аудита, чтобы манифест соответствовал схеме ARD.
  3. Укажите для каждой записи идентификатор urn:air:... и ровно один из идентификаторов url или data.
  4. Используйте стандартный тип медиаконтента ARD в поле type, если он подходит.
  5. Чтобы получить идеальную оценку, добавьте от 2 до 5 representativeQueries в каждую запись.