# Эталонные реализации

> Сервисы обнаружения с поддержкой ARD: Hugging Face Discover, GitHub Agent Finder, Cisco AI Catalog, Ora, ANS Finder и другие, с примерами запросов.

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

## Hugging Face Discover Tool

[Discover Tool](https://github.com/huggingface/hf-discover) от Hugging Face открывает поиск по тысячам навыков (Skills), ML-приложений и MCP-серверов - на Hugging Face или в любом другом сервисе, соответствующем ARD.

### Hugging Face CLI (`hf`)

`discover` встроен в [Hugging Face CLI](https://github.com/huggingface/huggingface_hub) (`hf`). Чтобы начать:

```bash
# Install the Hugging Face CLI tool:
uv tool install huggingface_hub

# Search for resources to train a model
hf discover search "Fine tune a language model"

# Find MCP Servers to generate an image
hf discover search "Generate an image" --json --kind mcp

# Search other registries
hf discover search "Purchase aeroplane tickets" --registry-url <catalog-url>

# Navigate a federated catalog from a website
hf discover navigate <web-url> "Research biomedical datasets"
```

### Доступ через REST и MCP API

Обращайтесь к сервису каталога Hugging Face напрямую:

  - REST API по адресу: `https://huggingface-hf-discover.hf.space/search`
  - MCP по адресу: `https://huggingface-hf-discover.hf.space/mcp`

## GitHub Agent Finder

Agent Finder от GitHub - это сервис обнаружения агентных ресурсов (agentic resources): навыков, инструментов и MCP-серверов, - доступный по HTTPS по адресу `https://agentfinder.github.com/api/v1`.

### GitHub Copilot

GitHub Copilot может искать в нём напрямую: добавьте Agent Finder как инструмент удалённого MCP (или как пользовательские инструкции), затем попросите Copilot найти возможность для вашей задачи, и он вернёт ранжированные совпадения, из которых вы выбираете, что установить. Полная настройка описана на странице [Подключение GitHub Copilot](https://agenticresourcediscovery.ru/connect/github-copilot/) - в качестве примера там используется эта же конечная точка (endpoint).

### HTTP API

Вызывайте поиск напрямую: `POST https://agentfinder.github.com/api/v1/search`. Конечная точка MCP - `https://agentfinder.github.com/api/v1/mcp`.

## Cisco AI Catalog

Эталонная реализация ARD [AGNTCY Agent Directory](https://dir.agntcy.org) развёрнута в [AI Catalog](https://ai-catalog.outshift.io) от Cisco.
Каталог можно получить по адресу [`ai-catalog.outshift.io/.well-known/ard.json`](https://ai-catalog.outshift.io/.well-known/ard.json).
Он поддерживает безопасную проверку через манифесты доверия, так что клиенты могут проверить идентичность издателя и целостность ресурса перед использованием.

### 1. Получите манифест каталога

```bash
curl -sS https://ai-catalog.outshift.io/.well-known/ard.json | jq '.entries | length'
```

### 2. Найдите карточки A2A

```bash
curl -sS 'https://ai-catalog.outshift.io/v1/agents?filter=type%3Dapplication%2Fa2a-agent-card%2Bjson' \
	| jq -r '.results[] | "\(.displayName)\t\(.data.card_data.url // .identifier)"'
```

### 3. Выполните поиск по типу карточки и извлеките сведения о доверии

```bash
curl -sS 'https://ai-catalog.outshift.io/v1/agents?filter=type%3Dapplication%2Fmcp-server-card%2Bjson' \
	| jq -r '.results[] | {displayName, identity: .trustManifest.identity, identityType: .trustManifest.identityType, cardUrl: .data.card_data.url} | @json'
```

## Ora Directory

[Ora Directory](https://ora.directory) - это сервис обнаружения ARD по продуктам и сервисам, которыми агенты пользуются от имени пользователей; его ведёт [Ora](https://ora.ai). Ora проверяет каждый продукт на готовность к работе с агентами - статические проверки его документации, llms.txt, реестров и публичных API, а также живые запуски агентов, которые пытаются использовать продукт от начала до конца, - и отдаёт результаты по протоколу ARD вместе с обнаруженными у каждого продукта MCP-серверами, навыками (Skills) и спецификациями OpenAPI, а также платными конечными точками HTTP x402/MPP с оплатой за вызов, проиндексированными из публичного реестра Bazaar. Каждая запись продукта несёт его оценочную карту готовности к работе с агентами в виде подписанной аттестации доверия, так что клиент может учитывать не только то, подходит ли ресурс для задачи, но и то, подтверждено ли наблюдениями, что он работает с агентами.

Манифест издателя Ora по адресу [`ora.ai/.well-known/ard.json`](https://ora.ai/.well-known/ard.json) описывает собственные ресурсы Ora и объявляет реестр: его запись `application/ai-registry+json` указывает на `https://ora.ai/api/ard`, где отдаётся самоописывающий дескриптор с перечнем конечных точек (endpoints). Сам индекс запрашивается через эти конечные точки.

### Поиск и просмотр

Реестр реализует весь интерфейс протокола - `POST /search`, `POST /explore` и `GET /agents` с выражениями `filter` и параметром `orderBy` из спецификации - и возвращает `referrals` на равноправные реестры.

```bash
# Find products for a task
curl -sS -X POST https://ora.ai/api/ard/search \
  -H 'content-type: application/json' \
  -d '{"query":{"text":"send transactional email"},"pageSize":5}' \
  | jq -r '.results[] | "\(.displayName)\t\(.url)"'

# Browse just the MCP servers in the index
curl -sS -G https://ora.ai/api/ard/agents \
  --data-urlencode "filter=type = 'application/mcp-server-card+json'" \
  --data-urlencode "pageSize=5" \
  | jq -r '.items[].displayName'
```

### Проверка оценочной карты

Поле `trustManifest.attestations[]` каждого результата ссылается на оценочную карту готовности продукта к работе с агентами, подписанную отделённой подписью Ed25519 JWS и проверяемую по JWKS по адресу [`ora.ai/.well-known/jwks.json`](https://ora.ai/.well-known/jwks.json):

```bash
curl -sS https://ora.ai/api/ard/attestation/resend.com \
  | jq '{subject, score, grade, issuer}'
```

### MCP

Ora также доступен как MCP-сервер по адресу `https://ora.ai/api/mcp` (streamable HTTP); его инструменты `discover_products`, `get_score` и `search_capabilities` обращаются к тому же индексу.

## ANS Finder

[ANS Finder](https://github.com/agentnameservice/ans) - это сервис обнаружения в составе эталонной реализации **Agent Name Service (ANS)** с открытым исходным кодом: центр регистрации, журнал прозрачности и автономный верификатор на Go, основанные на черновике ANS в IETF. Finder читает ленту событий жизненного цикла реестра, заносит каждого зарегистрированного в ANS агента в поисковый индекс и предоставляет REST-интерфейс реестра ARD: `POST /v1/search` и `POST /v1/explore` (ARDS v0.9). Его отличает проверяемая регистрация: поле `trustManifest.attestations[]` каждой записи каталога несёт аттестацию `ANS-Registration`, URI которой разрешается в квитанцию SCITT COSE в журнале прозрачности ANS (ANS Transparency Log), так что клиент может криптографически проверить регистрацию агента - независимо от Finder - перед его вызовом. Сервис проходит проверку [набором тестов на соответствие](https://github.com/ards-project/ard-spec/tree/main/conformance) этого проекта (режим реестра).

ANS Finder рассчитан на самостоятельное размещение: запустите стек локально (или разверните собственный), а не обращайтесь к публичной конечной точке (endpoint).

### Запуск демонстрационного стека

```bash
git clone https://github.com/agentnameservice/ans && cd ans
scripts/demo/start.sh    # builds + starts the registry :18080, transparency log :18081, finder :18082
scripts/demo/register.sh --v2 translator.example.com    # register an MCP agent and drive it to ACTIVE
```

Finder опрашивает ленту событий реестра (в демонстрации - каждые 2 секунды) и индексирует агента; Swagger UI показывает контракт ARD сервиса Finder по адресу `http://localhost:18082/docs`.

### Поиск

```bash
curl -sS -X POST http://localhost:18082/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":{"text":"translator"},"pageSize":5}' \
  | jq '.results[] | {identifier, displayName, url, score}'
```

### Проверка записи по журналу прозрачности

Поле `trustManifest.attestations[]` каждого результата несёт URI квитанции SCITT в журнале прозрачности:

```bash
curl -sS -X POST http://localhost:18082/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":{"text":"translator"},"pageSize":1}' \
  | jq -r '.results[0].trustManifest.attestations[0].uri'
```

### Проверка соответствия

```bash
git clone https://github.com/ards-project/ard-spec
ard-spec/conformance/bin/conformance-test registry http://localhost:18082/v1
```

## MCP Gateway Registry

[MCP Gateway Registry](https://github.com/agentic-community/mcp-gateway-registry) - это реализация ARD с открытым исходным кодом (Apache-2.0) для самостоятельного размещения, которая охватывает обе роли - издателя (Publisher) и реестра (Registry), - а также федерацию между реестрами. Она индексирует MCP-серверы, агентов A2A и навыки и отдаёт их по контракту ARD. Полное описание - в [docs/ard.md](https://github.com/agentic-community/mcp-gateway-registry/blob/main/docs/ard.md).

### Издатель: получение манифеста каталога

Роль издателя (Publisher) формирует из записей реестра соответствующий спецификации анонимный `/.well-known/ai-catalog.json`, где перечислены только публичные и включённые активы. Каждая запись несёт URN, привязанный к домену (`urn:air:<publisher>:<namespace>:<name>`), тип содержимого (media type) IANA для своего вида и `trustManifest` со схемой `https`.

Обратите внимание: сейчас эта реализация отдаёт путь `/.well-known/ai-catalog.json`, принятый до версии v0.91, а не `/.well-known/ard.json`; в примерах ниже используется путь, по которому работающий экземпляр отвечает сегодня, а поддержка `ard.json` ожидается в основном проекте.

```bash
# Against a self-hosted instance
curl -sS https://your-registry.example.com/.well-known/ai-catalog.json \
  | jq '.specVersion, .host.displayName'
```

### Реестр: поиск и просмотр

Роль реестра (Registry) предоставляет контракт поиска и просмотра ARD по пути `/api/ard`. Обе конечные точки требуют JWT и ограничены правами доступа: вызывающая сторона видит только те активы, к которым ей разрешён доступ.

```bash
# Semantic search over the catalog
curl -sS -X POST https://your-registry.example.com/api/ard/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"query":{"text":"financial data tools","filter":{"type":["mcp_server"],"tags":["finance"]}},"pageSize":10}' \
  | jq -r '.results[] | "\(.displayName)\t\(.score)"'

# Browse all asset types (MCP servers + A2A agents + skills)
curl -sS -X GET "https://your-registry.example.com/api/ard/agents?orderBy=identifier" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.items[].displayName'
```

Результаты - это записи `catalogEntry` протокола ARD с добавлением `score` (целое число 0-100) и `source`. Ошибки используют оболочку ARD `{errorCode, message}`. Федерация загружает каталоги `ai-catalog.json` других реестров в единый локальный индекс; режим выбирается для каждого запроса параметром `federation` (`none` / `auto` / `referrals`).