agentsready
Discoverability Легко

ai-agent.json: визитка сайта для AI-агентов

Что такое ai-agent.json, зачем агентам машиночитаемый манифест сайта, минимальный пример, правильно vs неправильно, ошибки и как проверить.

Обновлено:

Что это

ai-agent.json — машиночитаемый JSON-манифест сайта для AI-агентов, который кладут по well-known-пути (/.well-known/ai-agent.json). Это «визитка»: кто вы, что предлагаете, как с вами взаимодействовать и куда обращаться. Конвенция развивающаяся, поэтому точный набор полей зависит от ваших возможностей — но базовый минимум стабилен.

Зачем это AI-агентам

Агенту, который пришёл выполнить задачу, нужно быстро понять: что это за сервис, есть ли API, какие условия. Парсить для этого весь HTML — дорого и ненадёжно. Один предсказуемый JSON по известному адресу даёт агенту опору без догадок и повышает шанс, что он корректно представит вас в ответе или сценарии.

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

{
  "name": "Example Inc.",
  "description": "Платформа аналитики для e-commerce.",
  "url": "https://example.com",
  "contact": "agents@example.com",
  "capabilities": ["search", "pricing"],
  "endpoints": {
    "api": "https://example.com/.well-known/api-catalog"
  }
}

Поля сверх минимума добавляйте по мере того, что реально предлагаете агентам.

Правильно vs неправильно

ПравильноНеправильно
Лежит по /.well-known/ai-agent.json, application/jsonПроизвольный путь, который агент не найдёт
Валидный JSON, абсолютные URLСломанный JSON или относительные ссылки
Поля отражают реальные возможностиЗаявленные endpoints, которых нет
Краткое понятное descriptionМаркетинговая «вода» без сути

Типичные ошибки

  • Невалидный JSON — агент отбрасывает весь файл.
  • Неправильный путь — не /.well-known/, агент не находит.
  • Заявлены endpoints/возможности, которых нет — подрывает доверие.
  • Отдаётся как HTML (SPA) вместо application/json.
  • Путаница версий манифеста — держите один канонический файл.

Как проверить

Скан проверит наличие и валидность манифеста. Вручную:

curl -s https://example.com/.well-known/ai-agent.json | jq .

jq должен распарсить файл без ошибок — значит JSON валиден.

Источники