Это руководство для разработчиков, которые создают ИИ-клиент - оркестратор, агента или агентную среду (harness), - который должен обнаруживать агентные ресурсы (agentic resources) во время выполнения, а не работать с жёстко зашитыми инструментами. С ARD ваш клиент спрашивает сервис обнаружения: «что доступно для этой задачи?», выбирает ресурс и подключается к нему через собственный механизм этого ресурса.

Это нужно, когда вашему агенту требуются возможности - MCP-серверы, агенты A2A, навыки (Skills), API, - которые не подключены заранее, и вы хотите, чтобы этот набор оставался актуальным без повторного выпуска клиента.

Уже пользуетесь одним из крупных чат-ботов? Для Claude, ChatGPT, GitHub Copilot, Microsoft Copilot и Gemini мы предоставляем готовые коннекторы - см. Подключение чат-бота. Вы можете взять их за основу или улучшить. Это руководство - для случая, когда у вас собственный клиент и вы хотите добавить поддержку ARD напрямую.

Что делает клиент

1. Хранит список конечных точек (endpoints) сервисов обнаружения, к которым ему разрешено обращаться.
2. Превращает задачу пользователя в поисковый запрос и отправляет его этим сервисам.
3. Ранжирует результаты и при необходимости задействует федерацию нескольких сервисов.
4. Проверяет доверие, прежде чем что-либо использовать.
5. Подключается к выбранному ресурсу через его собственный механизм и использует его.

Шаг 1 - настройте конечные точки обнаружения

Клиент никогда не придумывает, где искать. Держите в настройках список сервисов обнаружения (реестры / Agent Finders), к которым он может обращаться, - публичных, сервисов поставщиков или внутреннего сервиса вашей организации - и предоставьте оператору решать, чему доверять. Файл agent-finders.json в репозитории connectors - один из примеров такого подхода.

Шаг 2 - выполните поиск

Отправьте намерение пользователя на конечную точку POST /search сервиса обнаружения. text содержит описание потребности на естественном языке, а filter сужает выборку по структурированным полям - оба находятся внутри query; federation и pageSize расположены на корневом уровне:

POST https://your-discovery-service/search

{
  "query": {
    "text": "book me a flight to Tokyo",
    "filter": { "type": ["application/mcp-server+json"] }
  },
  "federation": "referrals",
  "pageSize": 3
}

• query.text - обязательное поле; задача обычными словами.
• query.filter - необязательные структурированные ограничения (type, tags, capabilities, publisher, trustManifest.*, …). Внутри одного ключа значения объединяются по ИЛИ; между ключами - по И.
• federation - auto (сервис объединяет результаты вышестоящих сервисов), referrals (сервис возвращает другие сервисы, к которым вы обращаетесь сами) или none.
• pageSize / pageToken - постраничная выдача (по умолчанию 10, максимум 100).

Шаг 3 - прочитайте ответ

В ответ вы получаете ранжированные записи каталога - каждая содержит нужные вам схему и конечную точку - и необязательные отсылки (referrals):

{
  "results": [
    {
      "identifier": "urn:air:acme.com:travel:concierge",
      "displayName": "Travel Concierge",
      "type": "application/mcp-server+json",
      "url": "https://api.acme.com/mcp/travel.json",
      "score": 95,
      "source": "https://registry.acme.com/api/v1/"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:air:example.org:registry",
      "type": "application/ai-registry",
      "url": "https://finder.example.org/search"
    }
  ]
}

Обратите внимание: score (0-100) - это ранжирование по семантической релевантности от сервиса обнаружения. Ваш клиент НЕ ДОЛЖЕН (MUST NOT) трактовать его как оценку доверия, соответствия требованиям или безопасности - выполняйте такую оценку отдельно (шаг 4).

Шаг 4 - проверьте доверие, прежде чем что-либо использовать

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

1. Извлеките домен - выделите полное доменное имя (FQDN) из идентификатора URN (urn:air:acme.com:travel:… ➜ acme.com).
2. Проверьте идентичность - получите манифест и убедитесь, что trustManifest.identity (например, идентификатор SPIFFE или did:web) привязана к этому домену.
3. Проверьте соответствие требованиям - изучите массив attestations (SOC2, HIPAA, GDPR, …).
4. Проверьте подпись - проверьте отделённую подпись JWS манифеста доверия и тем самым убедитесь, что запись не была изменена при передаче.

Доверие - это ваше решение (и решение реестра). Спецификация только переносит свидетельства; сама она никогда не ручается за ресурс.

Шаг 5 - используйте федерацию (необязательно)

При federation: "referrals" в ответе, в поле referrals, перечислены другие сервисы обнаружения. Обращайтесь к тем, которым доверяете: отправьте тот же поисковый запрос на их url и объедините результаты самостоятельно. federation: "auto" перекладывает это объединение на сервис; none оставляет поиск локальным. Топологией управляете вы.

Шаг 6 - подключитесь и используйте

Обнаружение сообщает, какой ресурс подходит и где к нему обратиться; затем вы подключаетесь через собственный механизм этого ресурса:

• application/mcp-server+json - получите артефакт (url) или прочитайте встроенные data, затем общайтесь с сервером по MCP (JSON-RPC).
• application/a2a-agent-card+json - загрузите карточку агента и используйте A2A.
• application/ai-skill - установите или загрузите навык.
• Традиционный API - вызывайте его согласно описанию OpenAPI / REST.

Загружайте в контекст модели схему только выбранного ресурса. В этом и состоит смысл подхода «сначала обнаружение»: модель видит несколько инструментов, важных для задачи, а не тысячи.

Минимальный пример

curl -s https://your-discovery-service/search \
  -H 'content-type: application/json' \
  -d '{"query":{"text":"summarize a PDF"},"pageSize":3}' \
  | jq '.results[] | {displayName, type, url, score}'

Выберите результат, проверьте его trustManifest, загрузите содержимое по его url и подключитесь через собственный механизм ресурса.