# Agent-карточки и .well-known для AI-агентов

* **Коротко.** [AI-агенты](/articles/how-to-build-ai-agent) ищут на сайте машиночитаемые «визитки» в каталоге `/.well-known/`: `agent-card.json` (Google A2A), `ai-plugin.json` (плагины), `mcp/server-card.json` (Model Context Protocol) и `agents.json`. Вместе с `llms.txt` в корне сайта они объясняют агенту, что вы умеете, какие у вас [API](/api-docs) и как с вами взаимодействовать. Это новый слой «SEO для агентов» — без него агент видит только сырой HTML.

## Что такое .well-known и зачем он агентам

 Каталог `/.well-known/` — стандартизированное место (RFC 8615), куда сервисы кладут метаданные о себе: от проверки SSL до конфигурации OpenID. AI-агенты переиспользуют этот же механизм, чтобы найти описание возможностей сайта по предсказуемому пути, не парся всю навигацию.

> Человек читает страницу «О нас». Агент читает `/.well-known/agent-card.json`. Если карточки нет — агент догадывается по HTML, и догадки бывают неточными.

## Ключевые файлы и их роли

 ФайлНазначениеКто использует agent-card.jsonОписание агента: навыки, URL, версия протоколаGoogle A2A, агентные фреймворки ai-plugin.jsonМанифест плагина: имя, описание, точка входа APIПлагин-совместимые ассистенты mcp/server-card.jsonКарточка MCP-сервера: инструменты и ресурсыMCP-клиенты (Claude и др.) agents.jsonКаталог доступных агентов/действийУниверсальные агенты llms.txt (в корне)Человеко- и машиночитаемая карта сайта для LLMВсе AI-краулеры

## Пример agent-card.json

 Минимальная корректная agent-карточка по спецификации A2A включает версию протокола и описание навыков:

```
`{ "protocolVersion": "0.2.0", "name": "enterno.io", "description": "Инструменты диагностики сайтов и мониторинга аптайма", "url": "https://enterno.io", "capabilities": { "streaming": false }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "skills": [{ "id": "http-check", "name": "HTTP header check", "description": "Анализ заголовков ответа и редиректов" }] }`
```

 Файл размещается по адресу `https://example.com/.well-known/agent-card.json` и должен отдаваться с `Content-Type: application/json`.

## Идея mcp/server-card.json

 Если у вас есть MCP-сервер, карточка по пути `/.well-known/mcp/server-card.json` описывает доступные инструменты и ресурсы, чтобы MCP-клиент мог обнаружить их без ручной настройки:

```
`{ "name": "enterno-mcp", "version": "1.0.0", "description": "MCP-сервер с инструментами проверки сайтов", "endpoint": "https://enterno.io/mcp", "tools": [ { "name": "check_http", "description": "Проверить HTTP-заголовки URL" }, { "name": "check_ssl", "description": "Проверить SSL-сертификат" } ] }`
```

 Карточка — это «оглавление» вашего MCP-сервера: клиент читает её, понимает список инструментов и подключается к рабочему endpoint.

## Как агенты находят и читают карточки

 - Агент запрашивает `/.well-known/agent-card.json` по предсказуемому пути.
 - Параллельно читает `llms.txt` в корне для карты контента.
 - Если есть MCP — обращается к `mcp/server-card.json` за списком инструментов.
 - Подсказки можно дублировать в [HTTP-заголовке](/) `Link:`, указывая на эти файлы.

> Чем меньше агенту приходится «угадывать», тем точнее он представит ваш сервис в ответе пользователю. Карточки убирают догадки.

## Чек-лист готовности к агентам

 - `llms.txt` в корне сайта, актуальный и полный.
 - `/.well-known/agent-card.json` с `protocolVersion` и `securitySchemes`.
 - `ai-plugin.json`, если предлагаете плагин-совместимый API.
 - `mcp/server-card.json`, если есть MCP-сервер.
 - Все файлы отдаются с корректным JSON и `Content-Type: application/json`.
 - AI-краулеры разрешены в `robots.txt` (GPTBot, ClaudeBot, PerplexityBot и др.).

## Частые вопросы

### Обязательны ли agent-карточки прямо сейчас?

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

### Чем agent-card.json отличается от llms.txt?

 `llms.txt` — карта контента* для LLM (что читать). `agent-card.json` — описание *возможностей и API* для агентов (что можно делать). Они дополняют друг друга.

### Нужен ли свой MCP-сервер?

 Не для всех. MCP уместен, если вы хотите дать агентам активные инструменты (вызовы API), а не только контент для чтения. Для контентного сайта достаточно llms.txt и agent-card.

### Как проверить, что всё настроено правильно?

 Используйте проверку AI-готовности — она проверяет наличие и валидность llms.txt и карточек в `.well-known`. См. также гайд [по robots.txt](/articles/robots-txt-guide) для доступа AI-краулеров.

 Связанные материалы: [robots.txt и AI-краулеры](/articles/robots-txt-guide), [структурированные данные для SEO](/articles/structured-data-seo).

 [Проверить AI-готовность →](/ai-check)

---

Источник: https://enterno.io/articles/agent-cards-well-known
