# Спецификация ARD

> Перевод спецификации Agentic Resource Discovery: запись ARD, манифест и обнаружение, API поиска, федерация, модель доверия и формальные схемы.

Страница: https://agenticresourcediscovery.ru/spec/
Оригинал на английском: https://agenticresourcediscovery.org/spec/
Указатель сайта: https://agenticresourcediscovery.ru/llms.txt

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

**Версия**: 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`, поэтому её термины разрешаются в пространство имён по умолчанию:

```json
{
  "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` терминами из дополнительного пространства имён. Термины без префикса остаются в пространстве имён по умолчанию; термины с префиксом (здесь - собственное пространство имён расширения издателя) становятся измерениями фильтрации:

```json
{
  "@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"]
}
```

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

```json
{
  "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`.

```json
{
  "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` необязателен.

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

```json
{
  "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` выходит за рамки этого черновика; клиент, которому нужна полная запись, получает её из источника, который её опубликовал.

```json
{
  "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` необязательны; когда оба отсутствуют, агрегация охватывает весь реестр.

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

```json
{
  "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 | Необязательное. Скрывать корзины со счётчиком ниже этого порога. |

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

```json
{
  "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**: реестр ищет только по собственному индексу.

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

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

**Запрос:**

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

**Ответ:**

```json
{
  "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`](https://github.com/ards-project/ard-spec/blob/main/spec/schemas/ard-entry.schema.json) - определяет `ArdEntry` и `ArdManifest` (документ `/.well-known/ard.json`, §5.1).
* **Базовый контекст**: [`spec/schemas/ard.context.jsonld`](https://github.com/ards-project/ard-spec/blob/main/spec/schemas/ard.context.jsonld) - начальный контекст расширения из §4.1, доступный по адресу `https://agenticresourcediscovery.org/context/v1`.
* **Структурная грамматика (CDDL, RFC 8610)**: [`spec/schemas/ard.cddl`](https://github.com/ards-project/ard-spec/blob/main/spec/schemas/ard.cddl)

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

Чтобы проверить запись с помощью AJV CLI:
```bash
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`](https://github.com/ards-project/ard-spec/blob/main/spec/schemas/ard.openapi.yaml)

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

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

* **Исполняемый файл инструмента**: [`conformance/bin/conformance-test`](https://github.com/ards-project/ard-spec/blob/main/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