# Документация AgentOS

AgentOS – кабинет студента курса «AgentOS 3»: уроки и эфиры, транскрипты, анкета, персональный план, прогресс, AI-тьютор и личный менторинг. Всё, что студент видит в кабинете, его агент может читать через **REST API** или **MCP** – от имени студента и только в пределах выданных прав.

| Что | Адрес |
| --- | --- |
| REST API | `https://aos.edgelab.space/api/v1` |
| MCP (Streamable HTTP) | `https://aos.edgelab.space/mcp` |
| Контракт OpenAPI | [`/docs/openapi.json`](/docs/openapi.json) |
| Для ИИ-агентов | [`/docs/llms.txt`](/docs/llms.txt) · [`/docs/llms-full.txt`](/docs/llms-full.txt) |

## Как это устроено

Бэкенд AgentOS – для агентов, кабинет – для людей. Один и тот же слой возможностей обслуживает три входа:

- **Кабинет** (веб и Telegram Mini App) – вход по ссылке из бота, Telegram Login или паролю, сессия в cookie.
- **REST API** – `Authorization: Bearer <ключ>`; персональный API-ключ студент выпускает в кабинете.
- **MCP** – те же данные в виде инструментов для Claude, ChatGPT, Claude Code и Codex; авторизация по OAuth или тем же API-ключом.

REST и MCP используют общие обработчики, общий журнал вызовов и общие лимиты ключа: инструмент `aos_get_progress` возвращает тот же JSON, что `GET /api/v1/progress`.

## Авторизация

- **API-ключ** – `aos3.sk_` и 43 символа base64url, действует 90 дней. Секрет показывается один раз при создании. Права задают scopes.
- **OAuth** – для коннекторов Claude.ai и ChatGPT: discovery, динамическая регистрация клиента (DCR), authorization code с PKCE S256. Access token живёт час, refresh token – 30 суток с каждой выдачи (при ротации срок сдвигается).
- Bearer-токен передаётся только в заголовке, никогда в query.

| Scope | Что открывает | По умолчанию |
| --- | --- | --- |
| `course:read` | уроки, эфиры, транскрипты, поиск, прогресс, профиль | да |
| `profile:read` | анкета и персональный план | да |
| `progress:write` | отметки уроков и шагов плана | нет, включается явно |
| `tutor:read` | чтение собственной истории тьютора | нет, включается явно |
| `mentoring:read` | личный менторинг (тарифы «С куратором / Лично с Даши») | нет, включается явно |

Подробнее – [Авторизация и ключи](/docs/auth) и [OAuth для MCP](/docs/oauth).

## Что может агент

| Задача | REST | MCP |
| --- | --- | --- |
| Узнать, кто студент, тариф и права ключа | [`GET /api/v1/me`](/docs/api/profile/me) | `aos_whoami` |
| Найти урок или момент в эфире | [`GET /api/v1/search`](/docs/api/content/search) | `aos_search` |
| Прочитать урок и транскрипт | [`GET /api/v1/lessons/{id}`](/docs/api/content/lesson-get) | `aos_get_lesson`, `aos_get_transcript` |
| Подсказать следующий шаг | [`GET /api/v1/next`](/docs/api/content/next) | `aos_next` |
| Отметить урок и шаг плана | [`PUT /api/v1/progress`](/docs/api/progress/progress-put) | `aos_mark_lesson`, `aos_update_plan_milestone` |
| Прочитать личный трек и встречи с ментором | [`GET /api/v1/mentoring/track`](/docs/api/mentoring/mentoring-track) | `aos_get_personal_track`, `aos_get_session` |

Тьютор, вложения, диктовка и управление ключами доступны только из кабинета – см. [Тарифы и доступ](/docs/access).

## С чего начать

1. [Быстрый старт](/docs/quickstart) – первый запрос за минуту и подключение MCP к Claude, ChatGPT, Claude Code и Codex.
2. [REST API](/docs/api) – все публичные эндпоинты по разделам.
3. [Инструменты MCP](/docs/mcp/tools) – что умеет агент и какие права нужны.
4. [Ошибки](/docs/errors) и [Лимиты](/docs/limits) – как обрабатывать отказы и повторы.

## Документация для ИИ

Каждая страница доступна как markdown: добавьте `.md` к адресу (`/docs/quickstart.md`), для обзора – [`/docs/index.md`](/docs/index.md). Кнопка «Скопировать для ИИ» кладёт markdown страницы в буфер, «Открыть в Claude» и «Открыть в ChatGPT» передают ссылку на неё в новый чат. Индекс по стандарту [llms.txt](https://llmstxt.org) – [`/docs/llms.txt`](/docs/llms.txt), вся документация одним файлом – [`/docs/llms-full.txt`](/docs/llms-full.txt).
