# Как добавить поддержку ARD в своего агента

> Руководство для разработчиков ИИ-клиентов: настроить конечные точки обнаружения, выполнить поиск, разобрать ответ, проверить доверие и подключить ресурс.

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

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

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

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

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

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

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

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

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

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

```json
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):

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

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

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

```bash
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` и подключитесь через собственный механизм ресурса.