# 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:

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

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

```json
{
  "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:**

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

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

```typescript
// 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 преимущества».

[← Все термины глоссария](/glossary)