Федеративное обнаружение и поиск агентных ресурсов

Версия: v0.91 Статус: предложение Дата: 26 августа 2026 г.

Авторы:

• Junjie Bu - Google
• R.V.Guha
• Shaun Smith - Hugging Face

1. Обзор

LLM всё чаще опираются на внешние возможности - инструменты MCP, агентов A2A, навыки и другие вызываемые сервисы, - чтобы расширять свою функциональность. В этом документе мы обобщённо называем их агентными ресурсами (agentic resources).

Спецификация Agentic Resource Discovery (ARD) определяет, как агентные ресурсы описываются, обнаруживаются и находятся поиском в федеративных сетях.

Эта версия (v0.91) заново излагает слой описания в терминах JSON-LD и пространств имён. Запись - это узел JSON-LD, термины которого берутся из пространства имён по умолчанию, если в записи не объявлено иное. Это смена подачи, а не новое определение: существующие манифесты без изменений остаются допустимыми записями. Добавляется точка расширения @context: запись МОЖЕТ (MAY) брать термины из дополнительных пространств имён, и эти термины становятся доступны для обнаружения без каких-либо изменений в настоящей спецификации. Какие пространства имён помимо пространства по умолчанию признаются, оставлено открытым; ожидается, что со временем их число будет расти, и эта эволюция не затрагивает записи, написанные сегодня.

2. Мотивация

Преобладающая модель требует, чтобы пользователи или разработчики явно «устанавливали» каждого агента или жёстко прописывали его в коде до использования. Когда экосистема вырастает до тысяч или миллионов агентов, нужна модель, в которой LLM могут обнаруживать и вызывать агентов динамически - подобно тому, как поисковые системы обнаруживают веб-страницы.

Описания агентов, как правило, носят общий характер, а большинство LLM сейчас выбирают инструменты, помещая все описания в контекстное окно, - такой подход не масштабируется. ARD решает эту задачу, вынося обнаружение за пределы LLM в выделенный поисковый сервис, где можно использовать более богатые сигналы (репрезентативные запросы, идентичность издателя, метаданные о соответствии требованиям, закономерности использования), не расходуя токены контекстного окна.

Опора слоя описания на JSON-LD продолжает ту же логику. Ресурс описывается один раз, на собственном домене; сервис обнаружения индексирует термины, которые он распознаёт, и сохраняет остальные; а издатель может обогатить запись предметным словарём, не дожидаясь пересмотра настоящей спецификации.

3. Основные принципы проектирования

ARD следует перечисленным ниже основным принципам проектирования, которые обеспечивают масштабируемость, взаимную совместимость и простоту внедрения:

3.1 Обнаружение через поиск

ARD не требует от пользователей или систем заранее устанавливать агентов (по аналогии с моделью магазина мобильных приложений), а продвигает модель, в которой агенты обнаруживаются динамически через поиск. Реестры поддерживают общий, непрерывно обновляемый индекс, благодаря чему возможности становятся обнаруживаемыми в момент публикации.

3.2 Масштабируемость за пределами контекстного окна

Традиционный выбор инструментов основан на подстановке всех описаний в контекстное окно LLM, что не масштабируется. ARD выносит задачу выбора за пределы LLM в выделенный поисковый сервис и применяет методы информационного поиска, чтобы масштабироваться до тысяч или миллионов возможностей, не расходуя токены контекстного окна.

3.3 Оболочка, не зависящая от вида артефакта

Спецификация не определяет и не ограничивает внутреннюю схему конкретных типов агентов (MCP, A2A и т. д.). Вместо этого она выступает чистой оболочкой, которая с помощью термина type (в формате типа содержимого (media type) IANA) указывает, чем является артефакт, и оставляет определение метаданных, специфичных для артефакта, спецификациям соответствующих протоколов.

[!NOTE] Статус регистрации в IANA: типы application/a2a-agent-card+json и application/mcp-server-card+json, используемые в настоящей спецификации, - это фактические стандарты сообщества, которые движутся к официальной регистрации. Разработчикам следует учитывать, что каталоги общеизвестных путей (например, /.well-known/agent-card.json) официально зарегистрированы как постоянные записи, тогда как полная регистрация типов ожидает совместной подачи рабочими группами, и формат может измениться. До тех пор посредникам не следует строго проверять эти типы.

3.4 Записи JSON-LD и пространства имён

Запись - это узел JSON-LD. Термины, записанные просто, без префикса, принадлежат пространству имён по умолчанию - это те же термины, которые манифест использует сегодня, и толкуются они так же. Через @context записи издатель МОЖЕТ (MAY) дополнительно брать термины из других пространств имён для описания ресурса. Потребитель обрабатывает термины, которые он распознаёт, и сохраняет остальные (§5.3.1). Так сохраняется единая модель записи, а словарь становится открытым по краям, а не замкнутым.

3.5 Универсальная основа для федерации

Чтобы любая система могла участвовать в обнаружении независимо от своего стека исполнения, реестр агентов ОБЯЗАН (MUST) предоставлять стандартный поисковый интерфейс HTTP REST. Для исполнения могут использоваться специализированные протоколы, но обнаружению нужна универсальная основа, доступная любому HTTP-клиенту.

3.6 Разделение ответственности

Чтобы стандарт оставался чистым и реализуемым, протокол делегирует эксплуатационные детали:

• Аутентификация делегирована: аутентификацией агентов занимается протокол конкретного артефакта, а не слой обнаружения.
• Распространение - это инфраструктура: механизмы физической доставки (OCI, npm и т. д.) оставлены на усмотрение серверной реализации и не входят в запись обнаружения.

4. Запись ARD

Единица, которую ARD описывает, индексирует и возвращает, - это запись ARD: описание одного агентного ресурса в форме, позволяющей найти его поиском. ARD определён в терминах записей ARD; контейнер, в котором запись передаётся (размещённый манифест, веб-страница, ответ API), относится к транспорту и рассматривается в §5.

Настоящая спецификация определяет запись ARD. Запись ARD - не тот же объект, что запись каталога, и смешивать их не следует. Запись каталога - это позиция, которой издатель вносит ресурс в перечень: её задача - вместить всё, что издатель пожелает описать, поэтому обязательного в ней как можно меньше. Запись ARD - это описание, несущее сигналы, которые нужны поисковому сервису, чтобы ресурсы были сопоставимы между издателями, никогда не согласовывавшими свои действия: её задача - гарантировать, что эти сигналы присутствуют и единообразно адресуемы.

Эти два понятия связаны, но различны. ARD принимает основные термины пространства имён по умолчанию (§4.2) и добавляет поверх них термины, от которых зависит обнаружение, - прежде всего representativeQueries, наличие которого в записи ARD ожидается. Отсюда следует, что каждая запись ARD - это корректно сформированная запись каталога, но не каждая запись каталога - это запись ARD: позиция перечня, в которой нет терминов обнаружения, остаётся совершенно допустимой записью каталога и просто не обнаруживается через ARD. На уровне схемы ARD держит это ожидание мягким: отсутствующий или недостаточно заполненный representativeQueries инструменты проверки соответствия отмечают как предупреждение, а не как жёсткую ошибку валидации, поэтому записи, созданные существующими инструментами, по-прежнему проходят валидацию (§4.2).

Поскольку определения раздельны, соответствие каждой спецификации самодостаточно: изменение того, чего требует запись каталога, не меняет того, чего требует запись ARD, и наоборот.

В настоящей спецификации «запись» означает «запись ARD», если не указано иное.

4.1 Запись ARD - это узел JSON-LD

Запись - это узел JSON-LD, описывающий агентный ресурс. Её термины получают значение через базовый контекст ARD, опубликованный по адресу https://agenticresourcediscovery.org/context/v1, который отображает основные термины на IRI в пространстве имён по умолчанию (https://agenticresourcediscovery.org/ns#).

Соответствующий спецификации потребитель ОБЯЗАН (MUST) расширять запись, используя базовый контекст ARD как начальный контекст расширения (параметр JSON-LD expandContext). Собственный @context записи, если он присутствует, применяется после базового контекста: он МОЖЕТ (MAY) добавлять или переопределять пространства имён, но не удаляет базовый контекст. По этому правилу основные термины разрешаются в свои IRI, а термины с пространством имён (например, okf:taxonomy) разрешаются через префиксы, объявленные в записи.

Указывать @context в самой записи НЕОБЯЗАТЕЛЬНО (OPTIONAL). Запись, в которой он опущен, - включая любую запись, опубликованную в формате-предшественнике, - толкуется любым потребителем, применяющим базовый контекст, и не требует изменений. В запись СЛЕДУЕТ (SHOULD) включать "@context": "https://agenticresourcediscovery.org/context/v1" (при желании - первым элементом массива, последующие элементы которого добавляют локальные пространства имён), когда её могут читать универсальные инструменты JSON-LD, которым не сообщили о необходимости применить базовый контекст, - в первую очередь когда она встроена как разметка на странице. Это следствие намеренное: запись без @context может истолковать только потребитель, который знает, что это запись ARD, и применяет базовый контекст. Такова цена краткости при составлении и обратной совместимости.

4.2 Термины записи

Пространство имён по умолчанию даёт определения перечисленным ниже терминам; ARD определяет, какие из них запись должна содержать. Запись ARD ОБЯЗАНА (MUST) содержать:

Термин	Требование	Примечания
identifier	ОБЯЗАН (MUST)	Глобально уникальный указатель обнаружения. URN, привязанный к домену (urn:air:<publisher>:<namespace>:<agent-name>); см. Приложение C. @id JSON-LD МОЖЕТ (MAY) его повторять.
displayName	ОБЯЗАН (MUST)	Имя, понятное человеку.
type	ОБЯЗАН (MUST)	Тип артефакта как тип содержимого IANA (§3.3).
url или data	ОБЯЗАН (MUST), ровно один из двух	Значение или ссылка (§4.3).

В записи ARD дополнительно СЛЕДУЕТ (SHOULD) указывать representativeQueries, а capabilities рекомендуется там, где он применим; это сигналы обнаружения, поэтому они описаны здесь полностью, а не ссылкой.

Термин	Требование	Описание
representativeQueries	СЛЕДУЕТ (SHOULD)	Образцы запросов на естественном языке, которые может задать пользователь и которые этот ресурс способен обслужить, - сигнал, по которому реестр строит свой семантический индекс. Запись без него нельзя найти поиском, и именно это отличает запись ARD от простой записи каталога. СЛЕДУЕТ (SHOULD) указывать 2-5 примеров. Жёстким требованием это не является: схема не отклоняет запись, в которой он опущен или число примеров иное, - средство проверки соответствия отмечает такие случаи как предупреждения (§D.2), поэтому результат работы существующих инструментов по-прежнему проходит валидацию.
capabilities	МОЖЕТ (MAY)	Короткие обозначения навыков или инструментов (например, ["WeatherTool"]), позволяющие быстро выполнять структурированную фильтрацию без загрузки полного артефакта.

Остальные термины необязательны и носят описательный характер.

Термин	Описание
description, tags, version, updatedAt, metadata, trustManifest	Описательные термины. trustManifest рассматривается в §4.5; ARD не ограничивает его внутреннюю схему ничем, кроме identity, но ожидается, что реестры будут его изучать и проверять.

Термины из любого дополнительного пространства имён, объявленного в @context записи, также МОГУТ (MAY) присутствовать и становятся доступны как измерения фильтрации (§5.3.1) без изменения настоящей спецификации.

4.3 Значение или ссылка

Содержимое артефакта записи передаётся ровно одним из двух взаимоисключающих терминов - url (ссылка на документ артефакта) или data (документ, встроенный в запись). Запись НЕ ДОЛЖНА (MUST NOT) содержать оба.

4.4 Примеры

Простая запись - без @context, поэтому её термины разрешаются в пространство имён по умолчанию:

{
  "identifier": "urn:air:acme.com:server:weather",
  "displayName": "Weather Data Node",
  "type": "application/mcp-server-card+json",
  "url": "https://api.acme.com/mcp/weather.json",
  "capabilities": ["WeatherTool", "ForecastTool"],
  "description": "Enterprise weather MCP server for live telemetry.",
  "representativeQueries": [
    "what is the current wind speed in Chicago",
    "get the 5-day forecast for Seattle"
  ]
}

Та же запись, обогащённая через @context терминами из дополнительного пространства имён. Термины без префикса остаются в пространстве имён по умолчанию; термины с префиксом (здесь - собственное пространство имён расширения издателя) становятся измерениями фильтрации:

{
  "@context": {
    "acme": "https://acme.com/vocab#"
  },
  "identifier": "urn:air:acme.com:server:weather",
  "displayName": "Weather Data Node",
  "type": "application/mcp-server-card+json",
  "url": "https://api.acme.com/mcp/weather.json",
  "capabilities": ["WeatherTool", "ForecastTool"],
  "description": "Enterprise weather MCP server for live telemetry.",
  "representativeQueries": [
    "what is the current wind speed in Chicago",
    "get the 5-day forecast for Seattle"
  ],
  "acme:serviceTier": "enterprise",
  "acme:region": ["us-east", "eu-west"]
}

Запись навыка от разработчика-одиночки, никаких церемоний доверия не требуется:

{
  "identifier": "urn:air:github.com:alice-dev:pptx-creator",
  "displayName": "pptx-creator",
  "type": "application/ai-skill+md",
  "url": "https://github.com/alice-dev/pptx-creator",
  "description": "Create professional PowerPoint presentations following brand guidelines.",
  "representativeQueries": [
    "turn these bullet points into a branded slide deck",
    "make a PowerPoint from this outline"
  ]
}

4.5 Идентичность и доверие

Привязка идентичности, аттестации соответствия требованиям, происхождение и криптографические подписи передаются в необязательном термине trustManifest. Так запись остаётся лёгкой для простых сценариев и при этом даёт надёжную точку подключения для корпоративных требований соответствия, отдельную от собственных эксплуатационных метаданных артефакта. ARD требует только trustManifest.identity - для правила привязки из §4.5.1 - и не ограничивает внутреннюю схему оболочки, поэтому манифест доверия, определённый любой системой - SPIFFE, методом DID, корпоративной PKI, - структурно допустим. Это нейтральность по отношению к системе, а не безразличие к доверию: ожидается, что федеративный реестр изучит манифест доверия и проверит его согласно той системе, которую манифест объявляет (§4.5.2). Его аттестации, происхождение и подпись - это входные данные для проверки и для фильтрации и ранжирования с учётом доверия, а не чёрный ящик, который передают дальше, не читая.

4.5.1 Привязка к полномочиям издателя

Криптографический домен доверия, заявленный в trustManifest.identity, ОБЯЗАН (MUST) совпадать с доменом <publisher>, встроенным в идентификатор обнаружения записи (Приложение C). Это защита ARD от захвата чужих пространств имён: запись, заявляющую urn:air:google.com:..., проверяющий реестр отклоняет, если она не может предъявить проверяемую аттестацию, выданную google.com. В остальном идентификатор обнаружения и субъект безопасности развязаны: первый - устойчивый указатель, по которому ведётся поиск, второй - динамические криптографические учётные данные.

4.5.2 Проверка

ARD не определяет собственной процедуры подписания или проверки. Подписываемые данные, их канонизация, обработка подписи и разрешение ключей определяются системой доверия, которую манифест объявляет в trustManifest.trustSchema (через её governanceUri и verificationMethods). ARD предписывает только привязку к полномочиям издателя из §4.5.1; две реализации, проверяющие один и тот же манифест, полагаются на одну и ту же объявленную систему. Будущий профиль ARD МОЖЕТ (MAY) закрепить конкретную схему по умолчанию, но настоящая спецификация этого не делает. Федеративному реестру СЛЕДУЕТ (SHOULD) выполнять проверку, которую задаёт объявленная система, и он МОЖЕТ (MAY) использовать её результат в решениях о фильтрации, ранжировании и допуске; реестр, который пропускает непроверенный манифест доверия нетронутым, лишается доверия, на котором держится федерация.

Оценка релевантности, возвращаемая операцией Search (§5.3.2), отражает только семантическую релевантность и НЕ ДОЛЖНА (MUST NOT) трактоваться как суждение о доверии, соответствии требованиям или безопасности; оценка доверия полностью отделена.

5. Обнаружение

Обнаружение - это суть ARD, и ему посвящён весь этот раздел: как записи публикуются и принимаются (§5.1-5.2), как клиент ищет по получившемуся индексу (API поиска, §5.3) и как реестры объединяются в федерацию (§5.4). Оно работает на двух уровнях:

1. Статическое обнаружение: децентрализованный механизм публикации, при котором разработчики и предприятия публикуют записи как статические документы или разметку на странице.
2. Динамическое обнаружение: активные сервисы с поиском (реестры), которые индексируют опубликованные записи и предоставляют динамический API поиска.

5.1 Механизмы обнаружения

Издатели объявляют о записях с помощью перечисленных ниже механизмов. Каждый из них указывает потребителю на источник записей; сами записи следуют §4 независимо от того, как они найдены.

• Общеизвестный URI (Well-Known URI): размещение манифеста записей по адресу https://{domain}/.well-known/ard.json. Манифест - это JSON-документ с массивом entries, содержащим записи ARD (§4); любые другие члены верхнего уровня определяются транспортом и игнорируются ARD. Его форма задана определением ardManifest в схеме записи (Приложение D).
• Разметка на странице: встраивание JSON-LD записи в веб-страницу, описывающую ресурс; обнаруживается обычным обходом веба.
• Директива Agentmap: добавление в robots.txt директивы с источником записей (например, Agentmap: https://example.com/entries.json).
• HTML-тег link: включение <link rel="ard" href="..."> в <head> документа.
• DNS: публикация записей Service Binding, которые указывают либо на статический источник записей (например, _entries._agents.example.com), либо на динамическую конечную точку поиска реестра агентов (например, _search._agents.example.com).

Разрешение на стороне потребителя (нормативно). Потребитель, разрешающий записи домена, ОБЯЗАН (MUST) запросить /.well-known/ard.json и ОБЯЗАН (MUST) учитывать ссылку rel="ard". Предшественник ARD задавал путь /.well-known/ai-catalog.json и отношение ссылки ai-catalog; потребитель МОЖЕТ (MAY) дополнительно обращаться к ним, и потребитель, который так поступает, рассматривает их как равнозначные источники записей. Обращение к именам предшественника - это любезность по отношению к ресурсам, опубликованным до этой редакции, а не требование соответствия: потребитель, который разрешает только ard.json и rel="ard", полностью соответствует спецификации.

Публикация (информативно). Издатели публикуют записи по пути /.well-known/ard.json и выдают rel="ard". Обслуживать ещё и путь или отношение предшественника не нужно: ARD определяет один путь, и издателя, который его обслуживает, обнаружит любой соответствующий спецификации потребитель. Ресурс, который остаётся только по пути /.well-known/ai-catalog.json, может быть не найден, поскольку обращение к этому пути для потребителей необязательно, - издателю, использующему путь предшественника, СЛЕДУЕТ (SHOULD) перейти на ard.json.

5.2 Конвейеры приёма данных

Экземпляры реестра агентов наполняют свои индексы через конвейеры приёма данных:

• Приём из веба (обязательно): обход источников записей - размещённых манифестов и разметки на странице - по обнаруженным URI. Все реализации ARD ОБЯЗАНЫ (MUST) это поддерживать.
• Дополнительные конвейеры (необязательно): реестры могут поддерживать сканирование git-репозиториев, реестров npm или реестров OCI, как указано в их конфигурации.

5.3 API поиска

API поиска - это динамическая половина обнаружения. Реестр агентов ОБЯЗАН (MUST) предоставлять стандартный поисковый интерфейс HTTP REST, чтобы гарантировать всеобщую федерацию. Рабочий базовый URL этих конечных точек обнаруживается динамически - по записям, у которых type равен application/ai-registry+json.

5.3.1 Модель запроса

Конечные точки POST /search и POST /explore принимают общий объект query с тремя членами: @context, text и filter. Каждая конечная точка определяет собственные дополнительные параметры рядом с query (см. §5.3.2 и §5.3.3) и собственные требования к наличию text и filter.

{
  "query": {
    "@context": { "okf": "https://openknowledgeformat.org/ns#" },
    "text": "find me a flight booking agent",
    "filter": {
      "type": ["application/a2a-agent-card+json"],
      "tags": ["finance"],
      "okf:taxonomy": ["us-gaap"],
      "trustManifest.attestations.type": ["SOC2-Type2"]
    }
  }
}

Поле	Тип	Описание
@context	Object/String	Необязательное. Связывает префиксы, используемые в ключах filter, точно так же, как @context записи связывает термины, которые она содержит. Накладывается на базовый контекст ARD (§4.1); если отсутствует, применяется только базовый контекст.
text	String	Описание потребности на естественном языке. Сужает набор результатов по семантической релевантности.
filter	Object	Структурированные ограничения. Ключи - пути терминов; значения - массивы (одиночный скаляр принимается как массив из одного элемента).

text и filter сочетаются: запись входит в набор совпавших записей, если она удовлетворяет критериям релевантности для text (когда он присутствует) И каждому ограничению в filter (когда он присутствует).

Разрешение терминов. Ключ фильтра, называющий термин, разрешается в свой IRI через действующий контекст запроса - базовый контекст ARD плюс @context запроса - и сопоставляется с записями по этому IRI, а не по буквальной строке ключа. Именно поэтому фильтрация по терминам с пространством имён работает между издателями: клиент, фильтрующий по okf:taxonomy, находит любую запись, автор которой связал то же пространство имён, независимо от выбранного этим автором префикса (okf:, openknowledge:, …), потому что обе стороны разрешаются в один и тот же IRI. Основные термины (type, tags, capabilities, version, …) разрешаются через базовый контекст, и @context им не нужен.

Сегменты пути внутрь нерасширяемых членов. ARD не расширяет trustManifest, metadata и встроенный data в граф JSON-LD (§4.1); пути через точку внутрь них (например, trustManifest.attestations.type, metadata.location) - это буквальные пути JSON по исходному члену, которые не разрешаются в IRI. Начальный сегмент по-прежнему является термином, разрешаемым в IRI; остальное - буквальный путь. (Отказ от расширения члена - это утверждение о графе, а не об изучении содержимого: реестры проверяют trustManifest согласно §4.5.2.)

Семантика фильтра: когда значение по разрешённому ключу или пути является массивом, ограничение выполняется, если ему удовлетворяет любой элемент массива. В пределах одного ключа значения объединяются через ИЛИ; между ключами - через И.

Расширяемость: любой термин, который содержит запись, МОЖЕТ (MAY) использоваться как ключ фильтра без изменения спецификации - основные термины, пути внутрь нерасширяемых членов и любой термин с пространством имён, который запрос связывает в @context. Реестр, индексирующий термин, делает его пригодным для фильтрации.

Ключ publisher выводится из сегмента <publisher> идентификатора URN записи (Приложение C) и не является хранимым термином; реестры извлекают его сами.

Поддержка реестрами: реестрам СЛЕДУЕТ (SHOULD) поддерживать фильтрацию по распространённым стандартным терминам; поддержка metadata.* и других терминов расширений определяется реестром. Реестр МОЖЕТ (MAY) отклонить фильтр, ссылающийся на неподдерживаемый путь термина, с ошибкой 400.

5.3.2 Search (POST /search)

Принимает query (§5.3.1) и возвращает записи, ранжированные по релевантности. Для Search text обязателен; filter необязателен.

Схема запроса:

{
  "query": {
    "text": "find me a flight booking agent",
    "filter": {
      "type": ["application/a2a-agent-card+json"]
    }
  },
  "federation": "referrals",
  "pageSize": 5
}

Помимо объекта query (§5.3.1), Search принимает:

Поле	Тип	Описание
federation	String	Необязательное. auto (по умолчанию), referrals или none.
pageSize	Integer	Необязательное (на корневом уровне). Максимальное число результатов на странице (по умолчанию: 10, максимум: 100).
pageToken	String	Необязательное (на корневом уровне). Маркер пагинации для получения следующей страницы.

Схема ответа:

Ответ возвращает записи с дополнительными оценками релевантности и необязательные отсылки (referrals). Параметр score обозначает ранжирование по семантической релевантности (0-100), вычисленное поисковым реестром, и показывает, насколько хорошо запись отвечает запросу на естественном языке. Это исключительно информационная метрика релевантности, и оркестраторы НЕ ДОЛЖНЫ (MUST NOT) трактовать её как криптографическую оценку доверия, соответствия требованиям или безопасности. Оценка доверия полностью отделена и выполняется независимо через манифест доверия (§4.5).

В ответе запись ОБЯЗАНА (MUST) содержать identifier; все остальные термины - на усмотрение реестра. Реестр возвращает то, что полезно для выбора среди результатов, и МОЖЕТ (MAY) опустить остальное - в частности, representativeQueries служат индексированию, а не представлению, и обычно опускаются. Поэтому результат не обязательно является полной записью ARD (§4.2); его identifier называет авторитетную запись. Обратите внимание: url, когда он присутствует, указывает на артефакт (Agent Card, Server Card и так далее), а не на запись ARD, которая его описывает. Нормативная операция получения полной записи по identifier выходит за рамки этого черновика; клиент, которому нужна полная запись, получает её из источника, который её опубликовал.

{
  "results": [
    {
      "identifier": "urn:air:acme.com:agent:assistant",
      "displayName": "Corporate Assistant (A2A)",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.acme.com/agents/assistant.json",
      "score": 95,
      "source": "https://registry.acme.com/api/v1/"
    },
    {
      "identifier": "urn:air:example.com:weather-server",
      "displayName": "Global Weather Service",
      "type": "application/mcp-server-card+json",
      "url": "https://weather.example.com/mcp",
      "capabilities": ["WeatherTool"],
      "score": 88,
      "source": "https://finder.external.org/api/"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:air:nlweb.ai:registry:public",
      "displayName": "Public Agent Finder",
      "type": "application/ai-registry+json",
      "url": "https://finder.nlweb.ai/search"
    }
  ],
  "pageToken": "eyJwYWdlIjogMn0="
}

5.3.2.1 Обработка и разрешение запросов (информативно)

Хотя настоящая спецификация предписывает интерфейс REST ради взаимной совместимости, реализации могут применять продвинутые методы, чтобы разрешать запросы на естественном языке в конкретные конечные точки агентов. Примерный порядок, опирающийся на исследования Agent Naming Services (ANS) и федеративных реестров, включает следующие шаги:

1. Семантический перевод и векторное представление:
   • Интерпретация запроса с помощью LLM: реестр использует LLM, чтобы извлечь конкретные многомерные требования из поля text на естественном языке и перевести его в структурированные атрибуты возможностей (например, domain: travel, skill: flight_booking, constraints: meal_preference).
   • Векторные представления: реестр может также преобразовать описание запроса в плотное векторное представление, чтобы понять семантическое значение (например, сопоставить «foreign exchange» с «forex» или «international money transfer»).
2. Глобальное обнаружение через федеративную маршрутизацию:
   • Продвинутые реализации могут выполнять этот запрос в федеративной сети. Например, использовать семантические атрибуты или векторы представлений для поиска по распределённой хеш-таблице (DHT) (например, расширенной IPFS Kademlia DHT) или задействовать DNS-AID для обнаружения авторитетных реестров конкретных доменов.
   • Так семантические возможности отображаются на криптографические хеш-значения или конечные точки агентов, которые обладают этими навыками в федеративной сети.

5.3.3 Explore (POST /explore) - необязательно

Принимает query (§5.3.1) и возвращает агрегацию по набору совпавших записей, а не ранжированные записи. Explore позволяет клиентам исследовать реестр - например, «какие типы артефактов доступны?» - и получать разбивку по фасетам, суженную теми же text и filter, что и в Search. Для Explore и text, и filter необязательны; когда оба отсутствуют, агрегация охватывает весь реестр.

Схема запроса:

{
  "query": {
    "text": "currency conversion",
    "filter": {
      "trustManifest.attestations.type": ["SOC2-Type2"]
    }
  },
  "resultType": {
    "facets": [
      { "field": "type" },
      { "field": "publisher", "limit": 50 }
    ]
  }
}

Помимо объекта query (§5.3.1), Explore принимает:

Поле	Тип	Описание
resultType	Object	Обязательное. Форма вычисляемого результата. Единственная определённая форма - facets (ниже); будущие формы, такие как counts или sample, расширяют это поле без изменений протокола.

Каждый элемент resultType.facets:

Поле	Тип	Описание
field	String	Обязательное. Путь термина для агрегации (тот же синтаксис, что у ключей фильтра, §5.3.1).
limit	Integer	Необязательное. Максимальное число возвращаемых корзин. По умолчанию: 20.
minCount	Integer	Необязательное. Скрывать корзины со счётчиком ниже этого порога.

Схема ответа:

{
  "resultType": "facets",
  "facets": {
    "type": {
      "buckets": [
        { "value": "application/mcp-server-card+json", "count": 1247 },
        { "value": "application/a2a-agent-card+json", "count": 389 }
      ],
      "otherCount": 23
    },
    "publisher": {
      "buckets": [
        { "value": "acme.com", "count": 412 }
      ]
    }
  }
}

Каждая корзина содержит value, и в ней СЛЕДУЕТ (SHOULD) указывать count (число совпавших записей; реестр МОЖЕТ (MAY) его опустить, когда счётчики невозможно вычислить эффективно). otherCount сообщает число совпавших записей в корзинах за пределами limit.

Фасеты вычисляются по всему набору совпавших записей, а не по одной странице. Для семантических текстовых запросов реестр применяет порог релевантности: записи, релевантность которых ниже порога, исключаются из набора совпавших записей. Порог определяется реестром, но в пределах одного реестра один и тот же порог действует и для результатов Search, и для фасетов Explore. Порог и оценка релевантности (§5.3.2) отражают только релевантность и НЕ ДОЛЖНЫ (MUST NOT) трактоваться как суждение о доверии, соответствии требованиям или безопасности.

Explore не участвует в федерации; он ограничен тем реестром, к которому обращён запрос. Федеративное обнаружение - задача Search (§5.3.2), через его режимы федерации (§5.4). Реестр, не реализующий Explore, возвращает код состояния HTTP 501 Not Implemented.

5.3.4 List (GET /agents) - необязательно

Детерминированный просмотр, предназначенный для порталов разработчиков. Хорошо кешируется, опирается на строгую фильтрацию на уровне базы данных и не поддерживает сортировку по релевантности.

Параметры:

Параметр	Тип	Описание
filter	String	Выражение фильтра в EBNF.
orderBy	String	Поля сортировки (например, name, created_at DESC).
pageSize	Integer	Максимальное число результатов (по умолчанию: 20, максимум: 100).
pageToken	String	Маркер пагинации.

5.3.5 Протокольные обёртки (необязательно)

Хотя REST API предписан как минимальный уровень взаимной совместимости, реестр МОЖЕТ (MAY) дополнительно предоставлять свою возможность поиска напрямую - через инструмент MCP или навык (Skill) A2A, чтобы сохранить привычные для оркестратора сценарии.

Ответ, возвращаемый этими протокольными обёртками, ОБЯЗАН (MUST) следовать той же модели записи, которая определена в настоящей спецификации. Однако формат запроса для этих обёрток может немного отличаться, чтобы учитывать соглашения конкретных протоколов, и ожидает дальнейшего определения.

5.4 Федерация

Поскольку REST API предписан, маршрутизация между реестрами (федерация) становится простой операцией HTTP. Клиент управляет федерацией через параметр запроса federation:

• auto: реестр автоматически опрашивает вышестоящие реестры, объединяет их результаты со своими и возвращает единый ответ. Клиент получает один объединённый набор результатов.
• referrals: реестр возвращает свои результаты и записи других реестров, к которым клиент может обратиться. Клиент сам решает, по каким из них переходить.
• none: реестр ищет только по собственному индексу.

Это даёт клиенту полный контроль над топологией федерации, не требуя сложных слоёв трансляции протоколов.

Пример: режим отсылок

Запрос:

{
  "query": {
    "text": "find me a flight booking agent"
  },
  "federation": "referrals"
}

Ответ:

{
  "results": [
    {
      "identifier": "urn:air:acme.com:agent:expense",
      "displayName": "Corporate Expenses",
      "type": "application/a2a-agent-card+json",
      "url": "https://internal.corp/agents/expense.json",
      "score": 97,
      "source": "https://finder.internal.corp"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:air:nlweb.ai:registry:public",
      "displayName": "Public Agent Finder",
      "type": "application/ai-registry+json",
      "url": "https://finder.nlweb.ai/search"
    },
    {
      "identifier": "urn:air:example.com:registry:travel",
      "displayName": "Travel Agent Finder",
      "type": "application/ai-registry+json",
      "url": "https://travel.finder.example/search"
    }
  ]
}

6. Пример интеграции

Пользователь просит оркестратор: «Забронируй мне рейс в Токио и оформи отчёт о командировочных расходах».

1. Оркестратор обращается к корпоративному реестру агентов с federation: "referrals".
2. Реестр возвращает внутреннего агента по расходам и отсылки к другим реестрам.
3. Оркестратор переходит по отсылке к публичному реестру агентов и запрашивает у него агентов для бронирования рейсов.
4. Теперь у оркестратора есть обе возможности, и он может перейти к их вызову по соответствующим протоколам (например, A2A для бронирования, MCP для оформления расходов).

---

Приложение A: синтаксис выражений фильтра

Параметр filter в API List (GET /agents) использует простой формат, подобный EBNF, для структурированных ограничений.

Поле фильтра	Тип	Описание
displayName	String	Фильтр по имени без различия прописных и строчных букв.
type	String	Типы содержимого через запятую (логика ИЛИ).
publisherId	String	Идентификаторы издателей через запятую (логика ИЛИ).
createdAfter	String	Отметка времени ISO 8601.
updatedAfter	String	Отметка времени ISO 8601.

Между разными параметрами действует логическое И; внутри одного параметра с несколькими значениями (через запятую) - ИЛИ.

Приложение B: стандартные коды ошибок

Код HTTP	Код ошибки	Описание
400	INVALID_ARGUMENT	Некорректный запрос или недопустимый синтаксис фильтра.
401	UNAUTHENTICATED	Недействительные или отсутствующие учётные данные.
404	NOT_FOUND	Несуществующий агент или реестр.
429	RATE_LIMIT_EXCEEDED	Слишком много запросов.
500	INTERNAL_ERROR	Внутренний сбой сервера.

Приложение C: формат URN для именования агентов

Идентификатор обнаружения использует форму URN, привязанного к домену: urn:air:<publisher>:<namespace>:<agent-name>, где <publisher> - полное доменное имя. Ограничение идентификатора обнаружения этой формой вместо произвольных URI даёт фундаментальные архитектурные преимущества для федеративного обнаружения:

1. Устойчивость именования (неизменное имя против изменяемого расположения): произвольные URI, особенно HTTP URL, смешивают логическую идентичность возможности с её физическим расположением в сети. Идентификатор urn:air: действует как абстрактный постоянный контракт; физическое распространение и транспортные привязки вынесены в термин url или data, что позволяет инфраструктуре развиваться, не ломая клиентский код обнаружения, индексирования и оркестрации.
2. Строгое разделение ответственности: федеративным реестрам нужен устойчивый первичный ключ для индексирования возможностей; средам исполнения с нулевым доверием нужны динамические криптографические токены (идентификаторы SPIFFE, DID, сертификаты X.509) для аутентификации рабочих нагрузок. Форма urn:air: чисто отделяет указатель обнаружения, по которому ведётся поиск, от субъекта безопасности, позволяя индексу обнаружения и инфраструктуре безопасности работать независимо.
3. Децентрализованное доверие и привязка к полномочиям: требование, чтобы <publisher> был допустимым FQDN, создаёт проверяемую опору полномочий. Реестры извлекают домен и сверяют его с криптографическим утверждением в trustManifest.identity (§4.5.1); рабочая нагрузка, которая не может предъявить действительную аттестацию, выданную этим доменом, отклоняется - без централизованного комитета по именованию.
4. Удобство поиска и обнаружения (шаблон разрешения @): структурированная иерархия позволяет реестрам детерминированно выделять издателя и конечное короткое имя (например, Assistant@Acme), что открывает путь к высокопроизводительной семантической фильтрации, агрегации и разрешению конфликтов (например, показу Assistant с проверенным значком Acme).
5. Уникальность между сетями и масштабируемость федерации: URN, привязанные к домену, гарантируют глобальную уникальность во всех федеративных реестрах без централизованной регистрации, поскольку доменные имена уже глобально уникальны благодаря корню DNS, - это исключает риск коллизий при объединении каталогов в режимах федерации auto и referrals.

@id JSON-LD записи МОЖЕТ (MAY) быть установлен в тот же идентификатор (или в IRI, который разрешается в ресурс); когда присутствуют оба, они ОБЯЗАНЫ (MUST) обозначать один и тот же ресурс.

Приложение D: формальные определения схем

Чтобы поддержать автоматическую валидацию, тестирование и машиночитаемую проверку соответствия требованиям, настоящая спецификация определяет собственную схему записи.

D.1 Схема записи ARD

Запись ARD - её обязательные термины, правило «значение или ссылка» и оболочка trustManifest - формально определена в JSON Schema (Draft 2020-12). Поскольку ARD определяет запись ARD (§4), эта схема является для неё авторитетной и не выводится ни из какой схемы каталога; обе развиваются независимо.

• Авторитетная схема: spec/schemas/ard-entry.schema.json - определяет ArdEntry и ArdManifest (документ /.well-known/ard.json, §5.1).
• Базовый контекст: spec/schemas/ard.context.jsonld - начальный контекст расширения из §4.1, доступный по адресу https://agenticresourcediscovery.org/context/v1.
• Структурная грамматика (CDDL, RFC 8610): spec/schemas/ard.cddl

Обратите внимание: схема намеренно задаёт additionalProperties: true. Термины, взятые из пространств имён, объявленных в @context записи (§4.1), допустимы и становятся измерениями фильтрации; закрытая схема свела бы на нет механизм расширения. Оболочка trustManifest так же открыта - ARD читает только identity (§4.5).

Чтобы проверить запись с помощью AJV CLI:

npx ajv-cli validate -s spec/schemas/ard-entry.schema.json -d path/to/entry.json

D.2 Ограничения обнаружения ARD

Помимо структурной корректности, проверка соответствия контролирует следующее:

• representativeQueries присутствует и содержит 2-5 примеров (§4.2) - предупреждение, а не ошибка: запись, в которой он опущен или число примеров иное, по-прежнему проходит структурную валидацию, но отмечается, поскольку её не найдут поиском.
• Домен издателя в URN ОБЯЗАН (MUST) совпадать с trustManifest.identity (§4.5.1).
• capabilities рассматриваются как структурированные обозначения для фильтрации (§5.3.1).

D.3 Спецификация REST API реестра (OpenAPI)

Интерфейсы запросов HTTP (POST /search, POST /explore и GET /agents), которые предоставляют соответствующие спецификации реестры агентов, формально определены с помощью спецификации OpenAPI 3.1.0 в формате YAML.

• Авторитетный файл спецификации: spec/schemas/ard.openapi.yaml

D.4 Официальный инструмент проверки соответствия

Чтобы упростить разработку и гарантировать соответствие, этот репозиторий предоставляет официальный, не имеющий зависимостей инструмент командной строки для проверки соответствия. Он позволяет издателям тестировать свои записи, а разработчикам реестров - проверять свои серверы REST API.

• Исполняемый файл инструмента: conformance/bin/conformance-test

Возможности:

• Режим валидации манифеста: разбирает манифест JSON, проверяет его по ArdManifest, а каждую его запись - по ArdEntry (§D.1), и выполняет ограничения обнаружения ARD (§D.2): формат URN, соблюдение правила «значение или ссылка», наличие и размер representativeQueries.
• Режим разрешения издателя: по заданному домену выполняет разрешение из §5.1 - запрашивает /.well-known/ard.json, при неудаче обращается к пути предшественника с предупреждением о том, что потребители не обязаны к нему обращаться, и проверяет всё, что удалось разрешить.
• Режим валидации реестра: опрашивает работающие конечные точки (POST /search и GET /agents), отправляет соответствующие спецификации поисковые запросы и проверяет коды состояния, оболочки пагинации, оценки релевантности и возвращённые записи (§5.3.2).

Благодарности

Авторы благодарят перечисленных ниже людей за их вклад и отзывы, в алфавитном порядке.

• Amazon Web Services - Jeffrey Damick, Martin Ristov
• Cisco - Guillaume De Saint Marc, Karen Jaworski, Luca Muscariello, Ramiz Polic, Vijoy Pandey
• Databricks - Jonathan Keller, Vinod Marur
• GitHub - Evan Boyle, Jeremy Moseley, Meagan Cojocar, Trent Jones
• GoDaddy - Scott Courtney
• Google - Alan Blount, Antonio Gulli, Ines David, John Murray, Krishna Thota, Natasha Balasubramanian, Polong Lin, Rao Surapaneni, Sam Sharaf, Sampath Kumar Maddula, Srinivas Krishnan, Todd Segal
• Microsoft - Adam Zukor, Chelsea Carter, Dee Templeton, Jennifer Marsman, Kevin Scott, Lindsey Li, Lisa Jaloza, Miesha Baker, Ryan Nadel, Shelby Delano
• Nvidia - Aysen Ilkhabar
• Salesforce - Mariano Gonzales, Vijay Pandiarajan
• Snowflake - Baris Gultekin, Vivek Raghunathan