# 1. Концепции

ИИ-агенты и бизнес усиливают друг друга: агенты снимают рутину и работают без
перерывов, бизнес даёт им цель, данные и границы. Переход к агентам — не разовый
эксперимент, а неизбежная трансформация: модели дешевеют, и автоматизировать
типовую работу становится выгоднее, чем держать под неё людей.

Agent OS — платформа для этой трансформации. Она превращает ИИ из «ассистента,
который отвечает» в «сотрудника, который действует»: на одном ядре запускаются
десятки агентов — поддержка, продажи, HR, аналитика — под контролем бюджета,
качества и безопасности.

Статья написана «от общего к частному» и помечена по аудитории:

- 🟢 — для всех (включая бизнес и новичков);
- 🔵 — для тех, кто собирает агентов и эксплуатирует платформу;
- ⚫ — для тех, кто пишет/меняет само ядро.

### Уровни и типы агентов

Внедрение идёт по уровням — от простого к автономному:

1. **FAQ-бот** — отвечает по базе знаний: поиск и готовые ответы.
2. **Ассистент** — понимает и рассуждает, работает с живыми данными через
   инструменты.
3. **Агент** — ставит цель, использует инструменты и доводит до результата:
   не «найди цену», а «сравни варианты и предложи лучший».
4. **Автономный агент** — запускается сам (триггеры) и выходит на связь, когда
   что-то произошло.

Мы выделяем четыре типа бизнес-агентов — по тому, с кем они работают и кто их
запускает. Один набор примитивов — процессы, инструменты, триггеры, IPC —
складывается в разные роли:

**Агенты вовне** — работают с клиентами и внешним миром: поддержка, продажи,
консультации, первый контакт. Живут в каналах (виджет на сайте, Telegram), а
инструменты дают им доступ к живым данным — каталогам, ценам, остаткам,
расписаниям. *Примеры из демо: поддержка вуза (`ngu`), подбор авто (`drom`),
авиабилеты (`aviasales`), книги (`chitai-gorod`, `labirint`).*

**Агенты внутрь** — закрывают внутренние процессы: HR, документы, бэк-офис,
онбординг. Вместо того чтобы штудировать регламенты, сотрудник спрашивает
агента — тот ищет по базе знаний и отвечает со ссылками. *Механизмы: поиск и
чтение архива (`site_tool` / `archive_tool` / `pdf_tool`), память (`memory`),
эскалация на живого сотрудника (`escalate`).*

**Агенты-наблюдатели** — следят за данными и сами выходят на связь, когда
что-то меняется. Не ждут вопроса, а запускаются триггерами: cron (по
расписанию) или monitor (при появлении нового). *Примеры: `rss`-агент мониторит
новостные ленты, `zakupki` следит за новыми закупками, результат уходит в
Telegram / email / другой агент.*

**Агенты-контроллеры** — реагируют на события и управляют другими агентами.
Через IPC запускают дочерних агентов (subagents), через workflow собирают
многошаговые пайплайны с условиями и ретраями, через escalate передают сложное
человеку.

---

## 1.1 Зачем это нужно — какие задачи решает

🟢 Пока агент один, достаточно скрипта вокруг одной модели: токены не считаются,
изоляция не нужна, ошибку можно «перезапустить и забыть». Проблемы начинаются,
когда агентов много и они работают на бизнес. Тогда возникает то, чего у
«личного агента» нет:

| Личный агент | Бизнес-агент (нужна платформа) |
|---|---|
| Токены не считаются | **Токены — это деньги**: бюджеты, кэш, лимиты |
| «Иногда ошибается» | **Надёжность**: валидация ответа, ретраи, эскалация |
| Песочница | **Безопасность**: персональные данные, роли, аудит действий |
| Один агент | **Масштаб**: сотни сессий, планировщик, изоляция |
| Перезапустил и забыл | **Управляемость**: живое обновление, версионирование |

Agent OS решает четыре задачи, которые неизбежны при росте числа агентов:

1. **Эффективное использование ресурсов.** Агенты делят общие ресурсы
   платформы — языковую модель (LLM), вычислительные мощности и хранилище;
   ядро решает, кто и когда выполняется.
2. **Управление бюджетом.** Лимиты токенов на ход / минуту / время жизни —
   один агент не «сожжёт» весь бюджет.
3. **Наблюдаемость.** Каждый шаг логируется: видно, что сделал агент и почему.
4. **Безопасность и изоляция.** Агент не читает чужой контекст и не тратит
   чужой бюджет.

---

## 1.2 Что такое Agent OS

🟢 **Одной фразой:**

> **Agent OS — это ядро (kernel) для ИИ-агентов.** Как операционная система
> управляет обычными программами-процессами, так Agent OS управляет
> ИИ-агентами.

Agent OS не делает инференс сам. Он относится к языковой модели (LLM) так же,
как операционная система относится к процессору:

- **LLM — это «CPU».** Agent OS не вычисляет ответы — он *планирует*
  вычисления на внешнем провайдере (DeepSeek, любой OpenAI-совместимый API,
  Ollama).
- **Agent OS — это «ядро».** Оно решает, *кто* из агентов сейчас получит
  доступ к модели, *сколько* токенов потратит и *с какими инструментами*.

Отсюда три ключевые идеи, которые отличают Agent OS от «обычного агента»
(скрипта вокруг одной модели):

1. **Агент = процесс.** Каждый агент — самостоятельный процесс со своим PID,
   инструкциями, контекстом (рабочей памятью), набором инструментов и бюджетом
   токенов.
2. **Ядро = порядок.** Агенты делят общий LLM — ядро планирует их, лимитирует
   и изолирует друг от друга.
3. **Всё контролируемо.** Каждый шаг (вызов инструмента, потраченные токены,
   состояние) логируется и поддаётся лимитам.

---

## 1.3 Метафора операционной системы

🟢 Вся конструкция — это аналогия с обычным ядром ОС. Она и есть «интуиция»
для всего остального:

| Понятие ОС | В Agent OS | Что делает |
|---|---|---|
| **Процесс** | `AgentProcess` | независимая единица: PID, состояние, контекст, инструменты, бюджет |
| **CPU** | `InferenceProvider` | подключаемый провайдер инференса (LLM) |
| **RAM** | `ContextWindow` | ограниченная рабочая память с вытеснением |
| **Устройство I/O** | `Tool` | контролируемый доступ к миру (HTTP, парсеры, PDF, RSS…) |
| **cgroups / ulimits** | `TokenBudget` / `BudgetGroup` | лимиты на процесс и на дерево процессов |
| **Системный вызов** | `Syscall` | API, которым агент просит услуги ядра |
| **Сигнал** | `Signal` | управление: terminate, pause, resume, interrupt |
| **fork()** | `fork()` | клонировать процесс (копия контекста, наследование бюджетной группы) |
| **Таблица процессов** | реестр `PID → AgentProcess` | кто вообще запущен |
| **Драйвер устройства** | `ToolHandler` | реализация инструмента |

Если держать эту таблицу в голове, всё дальнейшее читается «само».

---

## 1.4 Основные понятия

🔵 Понятия делятся на две группы: **ядро** (базовые блоки модели — без них
не понять, как всё работает) и **сервисы поверх ядра** (опциональные,
подключаются при загрузке).

### 4.1 Ядро — базовые блоки

| Понятие | Суть | Где видно |
|---|---|---|
| **Шаблон → процесс → сессия** | рецепт → запущенный экземпляр → разговор пользователя | `config/agents/<name>/agent.yaml` |
| **Контекст (рабочая память)** | ограниченная история сообщений + политика вытеснения | `max_context_tokens` |
| **Планировщик** | кто и когда получает общий LLM | `kernel.concurrency_limit` |
| **Бюджет** | token bucket: лимиты на ход/минуту/время жизни + группы | `budgets.yaml` |
| **Инструменты** | единственный выход в мир; ядро посредничает в каждом вызове | `tools:` / `tool_files:` |
| **Хуки** | перехват жизненного цикла (до/после хода) | `hook_files:` |
| **HTTP-маршруты** | пользовательские REST-эндпоинты и статика, добавленные без пересборки | `config/routes/` / `route_files:` |
| **IPC** | связь агентов: send/recv, spawn/fork/kill | системные вызовы |

Разберём каждое.

**Шаблон → процесс → сессия.** Три уровня одного и того же:

- **Шаблон** — переиспользуемый рецепт агента: имя, инструкции, инструменты,
  хуки, бюджет. Лежит в `config/agents/<name>/agent.yaml`.
- **Процесс** — запущенный экземпляр шаблона со своим PID, контекстом и
  бюджетным ведром.
- **Сессия** — разговор пользователя, привязанный к процессу (`session_id`,
  `user_id`).

Агенты **не** создаются заранее при старте: первый запрос к шаблону создаёт
процесс «на лету» (lazy spawn). Шаблоны видны в `GET /v1/templates`, запущенные
процессы — в `GET /v1/agents`.

**Контекст (рабочая память).** Ограниченная история сообщений (как RAM).
Когда лимит `max_context_tokens` превышен, срабатывает политика вытеснения:

- `fifo` — удалять самые старые;
- `summary_first` — старые сворачивать в краткое резюме (по умолчанию);
- `sliding_window` — держать только последние N.

**Планировщик.** Один планировщик решает, какой готовый процесс выполняется
следующим. Сегодня это `round_robin` с **лимитом конкурентности**
(`kernel.concurrency_limit`) — потолком на число агентов, одновременно
потокующих токены. Когда потолок достигнут, процессы ждут, пока один не
«уступит» (yield) или не заблокируется.

**Бюджет (token bucket).** Каждый процесс тратит токены из ведра:

- `refill_per_sec` — сколько токенов добавляется в секунду;
- `max_bucket` — ёмкость ведра (сколько накапливается в простое);
- `max_total` — жёсткий лимит на всю жизнь процесса (после — смерть).

Бюджеты объединяются в **группы** (как cgroups на дерево процессов). Перед
каждым ходом ядро проверяет по порядку: **группа → per-user → per-session**.
Если хоть один слой исчерпан, ход отклоняется, и пользователь видит текст из
`budget_messages.*` агента.

**Инструменты.** Единственный способ агента взаимодействовать с миром: сеть,
файлы, сайты, документы. Ядро посредничает в **каждом** вызове — проверяет
доступ, логирует, считает стоимость. По уровню конфигурации инструменты
различаются от встроенных (подключаются просто именем) до декларативных
(описываются конфигурацией) и скриптовых (своя логика, когда готовых не хватает).

**Хуки.** Перехватывают жизненный цикл агента в трёх точках и могут
трансформировать или отменить работу без LLM:

- `before_user_message` — до входа сообщения в контекст (впрыснуть/переписать/
  ответить самому);
- `after_turn` — после финального ответа (может достримить уведомление);
- `after_loop` — когда цикл работы агента завершается.

Встроенные виды: `faq_cache`, `inject`, `escalate`, `memory`, `script_hook`.

**IPC.** Агенты общаются через системные вызовы: `send`/`recv` (точка-точка),
`spawn` (создать новый процесс), `fork` (клонировать себя с наследованием
бюджетной группы), `kill`, `yield`.

### 4.2 Сервисы поверх ядра

Эти подсистемы опциональны и подключаются при загрузке. Если какой-то нет —
соответствующие вызовы отвечают «не настроено», а остальное продолжает
работать.

**Триггеры — что запускает агента без человека.** Это ключевое отличие
платформы: агент может работать полностью автономно. Три механизма:

| Триггер | Природа | Где |
|---|---|---|
| **Cron** | по расписанию (cron-выражение / интервал `every Ns` / разово `oneshot`) | `cron.yaml`, `agent.yaml → cron:` |
| **Webhook** | внешний push: `POST /v1/inbound/:template` запускает ход и синхронно возвращает ответ | `server.yaml → inbound` |
| **Monitor** | pull: следит за источником (RSS) и запускает агента только при **новых** элементах | `monitors.yaml` |

У всех триггеров результат уходит в **sink**: log / webhook / telegram /
messages_db / email / другому агенту.

**Каналы — как с агентом общаются.** В отличие от триггеров (кто запустил),
канал отвечает на вопрос «через что»:

- HTTP API (SSE-чат) — основной программный интерфейс;
- встраиваемый веб-виджет — кнопка «Чат с AI» на сайте;
- Telegram, email, webhook — внешние системы.

Webhook выступает и каналом, и триггером — поэтому два понятия разделены.

**Оркестрация (workflow).** Декларативный пайплайн (DAG) из агентов и
инструментов: шаги `agent` / `tool` / `condition` / `for_each`, с ретраями,
таймаутами и бюджетами на шаг. У воркфлоу *свои* триггеры (cron/webhook), но
сам по себе workflow — это оркестрация, а не триггер.

**Память и хранение.**

- `logs/process-<pid>.jsonl` — построчный JSONL-трейс процесса;
- `logs/events.db` — событийное хранилище DuckDB (питает `trace_*`-инструменты);
- `logs/messages.db` — общий журнал транскриптов + кэш FAQ + полнотекстовый поиск;
- `logs/state.db` — state store: scoped key-value (session / user / agent);
- чекпоинты — снимки состояния для восстановления после сбоя.

**Subagents.** Инструмент или хук может делегировать задачу дочернему
агент-процессу и прочитать его итоговый ответ — например, `subagent_tool`.

---

## 1.5 Ключевые архитектурные решения

⚫ Несколько решений, которые определяют характер платформы:

- **Rust.** Всё ядро — один статически скомпилированный бинарник: без рантайма
  и внешних зависимостей, деплой сводится к копированию файла, а безопасная
  конкурентность держит десятки агентов без гонок за данные.
- **Один async-runtime (Tokio).** Ядро — единственный событийный цикл, который
  планирует все процессы; на каждого агента не заводится отдельный поток.
- **Модель процессов.** Агент и воркфлоу — это процессы в одном реестре, с
  семантикой `spawn`/`fork` и деревом процессов.
- **Провайдер-абстракция.** Ядро не делает инференс, а планирует его на
  подключаемом провайдере (OpenAI-совместимый, DeepSeek, Ollama) — независимость
  от модели и вендора.
- **Kernel-mediated I/O.** Агенты никогда не вызывают инструменты напрямую:
  каждый вызов валидируется, лимитируется и логируется ядром.
- **Кооперативная многозадачность.** Агент «уступает» после каждого раунда
  инференса; опционально — вытеснение по кванту времени.
- **Opt-in подсистемы.** State store, cron, workflow и message store подключаются
  при старте; если чего-то нет, соответствующие вызовы отвечают «не настроено»,
  а не ломают ядро.

---

## 1.6 Границы системы — что это НЕ

🟢 Чтобы не путать Agent OS с соседними вещами:

| Не это | Что на самом деле | Зачем различать |
|---|---|---|
| **LLM** | планирует инференс на внешнем провайдере | независимость от модели/вендора |
| **Чат-интерфейс** | headless; UI подключаются как клиенты | встраиваемость в любой канал |
| **Фреймворк агентов** (AutoGen, CrewAI) | платформа, на которой они работают | уровень абстракции ниже |
| **Оркестратор** (LangChain, Temporal) | workflow — сервис *поверх* ядра | ядро — примитив, а не пайплайн |
| **Векторная БД / память** | память — просто инструмент | не привязан к хранилищу |
| **MCP-сервер** | хостит MCP-инструменты, но сам не сервер | хост ≠ инструмент |
| **Фреймворк промпт-инжиниринга** | промпт — user-space, ядру всё равно | разделение ответственности |

---

## 1.7 Куда идти дальше

| Вы… | Читайте |
|---|---|
| 🟢 новичок / бизнес | «Быстрый старт» (`02-quickstart`) |
| 🔵 собираете агента | «Сборка агента» (`04-building-an-agent`), «Инструменты» (`05`), «Хуки» (`06`) |
| 🔵 оператор | «Конфигурация сервера» (`03`), «Эксплуатация» (`09`) |
| ⚫ разработчик ядра | «Внутренности ядра» (`12-kernel-internals`), спецификация `SPEC.md` |
