ai-agent.json

Что такое ai-agent.json?

ai-agent.json — машиночитаемый манифест по пути /.well-known/ai-agent.json, описывающий возможности сайта для AI-агентов: что умеет, какие эндпоинты доступны, как с ними взаимодействовать.

Стандарт разработан организацией Aiia (AI Interoperability Alliance) и опубликован в марте 2026 года. Большинство сайтов его ещё не поддерживают — ранняя реализация даёт early-adopter преимущество. Наш сканер фиксирует отсутствие как neutral (не fail): стандарт молодой.

Путь /.well-known/ — стандартный механизм публикации метаданных согласно RFC 5785 (там же лежат openid-configuration, security.txt и другие).

Зачем сайту ai-agent.json?

До появления ai-agent.json AI-агент не имел единого места, чтобы узнать: «что умеет этот сайт?» — приходилось угадывать по структуре URL или действовать вслепую.

Манифест решает это декларативно:

• Capability discovery — агент читает файл и сразу видит список возможностей: ["scan", "report", "contact"]
• Endpoint mapping — прямой маппинг «возможность → URL» без guesswork
• Контекст для планирования — агент с задачей «проверь AI-готовность example.com» читает ai-agent.json сканнера и понимает, как именно вызвать сканирование
• Federated discovery — AI-реестры смогут индексировать сайты по манифесту для поиска нужного инструмента

Как реализовать ai-agent.json?

Минимальный ai-agent.json по спецификации Aiia:

{
  "name": "Example Corp",
  "description": "SaaS платформа для управления проектами"
}

Рекомендуемый расширенный вариант:

{
  "name": "Agent Ready Scanner",
  "description": "Public scanner for AI agent-readiness across 23 open standards",
  "version": "1.0",
  "capabilities": [
    "scan",
    "report",
    "advise"
  ],
  "endpoints": {
    "scan": {
      "url": "/api/scan",
      "method": "POST",
      "description": "Submit URL for scanning",
      "parameters": {
        "url": "string — URL to scan"
      }
    }
  },
  "contacts": {
    "email": "hello@agentsready.io",
    "url": "/about"
  },
  "documentation": "/scanner",
  "terms": "/terms",
  "privacy": "/privacy"
}

Технические требования:

• Путь: /.well-known/ai-agent.json (строго)
• Content-Type: application/json
• Кодировка: UTF-8
• Обязательные поля: name (string), description (string)
• Рекомендуемые: capabilities (array), endpoints (object), contacts (object)

Для статических сайтов:

Создайте public/.well-known/ai-agent.json. Проверьте, что сервер не блокирует .well-known/ — иногда правила firewall или WAF блокируют пути с точкой.

Для Nginx:

location = /.well-known/ai-agent.json {
    add_header Content-Type application/json;
    alias /var/www/well-known/ai-agent.json;
}

Динамическая генерация (если данные меняются):

// src/pages/.well-known/ai-agent.json.ts
export async function GET() {
  const manifest = {
    name: 'My App',
    description: 'Description',
    capabilities: ['feature1', 'feature2'],
  };
  return new Response(JSON.stringify(manifest, null, 2), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Как мы проверяем ai-agent.json?

Наш сканер делает GET /.well-known/ai-agent.json и проверяет:

1. HTTP-статус — если 404, статус neutral (стандарт молодой, отсутствие не штраф)
2. HTTP 200 — файл существует
3. Валидный JSON — парсится без ошибок
4. Обязательные поля — присутствуют name и description, оба — строки

Если все условия выполнены — pass. Если JSON невалидный или отсутствуют обязательные поля — fail (файл есть, но неверно составлен). HTTP 404 — neutral с объяснением «стандарт новый, добавьте для early-adopter преимущества».