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

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

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

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

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

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

Пример 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 для доступа AI-краулеров.

Связанные материалы: robots.txt и AI-краулеры, структурированные данные для SEO.

Проверить AI-готовность →