# Agent OS — документация

Самоучитель по работе с Agent OS **без чтения исходников на Rust**. Учит, как:

- **настроить** сервер/ядро (провайдер, планировщик, бюджеты, auth, логирование);
- **создавать агентов** целиком на YAML + опциональных скриптах (JavaScript
  или Rhai);
- **эксплуатировать** платформу: запускать, тестировать, бенчмаркать, деплоить,
  мониторить.

Всё опирается только на скомпилированные бинарники, дерево `config/` и папки
`data/` / `logs/`. Никаких `src/`, и для добавления или изменения агента
пересборка не нужна.

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

| Ты… | Начни здесь |
|---|---|
| 🟢 новичок / бизнес | `docs/01-concepts.md`, затем `docs/02-quickstart.md` |
| 🔵 собираешь агента | `docs/04-building-an-agent.md` |
| 🔵 настраиваешь сервер | `docs/03-server-configuration.md` |
| 🔵 пишешь инструмент | `docs/05-tools-reference.md` |
| 🔵 пишешь хук | `docs/06-hooks-reference.md` |
| 🔵 пишешь скрипты (JS/Rhai) | `docs/07-scripts.md` |
| 🔵 интегрируешь по HTTP | `docs/08-http-api.md` |
| 🔵 запускаешь/деплоишь/мониторишь | `docs/09-operations.md` |
| 🔵 нужна быстрая справка | `docs/10-cheatsheet.md` |
| 🔵 расписание (cron) | `docs/11-cron-jobs.md` |
| 🔵 воркфлоу | `docs/12-workflows.md` |
| 🔵 веб-контент (сайт) | `docs/13-web-content.md` |
| 🔵 HTTP-маршруты (REST/статика) | `docs/21-http-routes.md` |
| ⚫ разработчик ядра | `docs/14-kernel-internals.md` (и `SPEC.md` в корне) |
| 🔵 безопасность | `docs/15-security.md` |
| 🔵 контроль качества | `docs/16-benchmarking.md` |
| 🔵 дистрибутив | `docs/17-distribution.md` |
| 🔵 термины | `docs/18-glossary.md` |
| 🔵 виджет и каналы | `docs/19-widget-and-channels.md` |
| ⚫ пишешь нативный плагин (Rust DLL) | `docs/20-native-plugins.md` |

## Структура

```
agent-os-docs/
├── README.md                ← этот файл (индекс)
├── skills/                  ← загружаемые скиллы агентов (opencode SKILL.md)
│   ├── agent-os-configure/     настроить сервер/бюджеты/auth/логирование
│   ├── agent-os-build-agent/   создать/изменить агента
│   ├── agent-os-tools/         писать YAML-инструменты
│   ├── agent-os-hooks/         настроить хуки
│   ├── agent-os-scripts/       писать скрипты (JS или Rhai)
│   └── agent-os-routes/        добавить HTTP-маршруты (REST/статика)
└── docs/
    ├── 01-concepts.md          базовые концепции
    ├── 02-quickstart.md        быстрый старт
    ├── 03-server-configuration.md
    ├── 04-building-an-agent.md
    ├── 05-tools-reference.md    сводная таблица инструментов
    ├── 05-tools-core.md         основы (общие поля, шаблоны, встроенные)
    ├── 05-tools-data.md         сбор и поиск данных
    ├── 05-tools-state.md        состояние, БД, визуализация
    ├── 05-tools-compute.md      вычисления и действия
    ├── 05-tools-observe.md      наблюдение и отладка
    ├── 06-hooks-reference.md
    ├── 07-scripts.md           скрипты (JS и Rhai)
    ├── 08-http-api.md
    ├── 09-operations.md
    ├── 10-cheatsheet.md
    ├── 11-cron-jobs.md
    ├── 12-workflows.md
    ├── 13-web-content.md
    ├── 14-kernel-internals.md
    ├── 15-security.md
    ├── 16-benchmarking.md
    ├── 17-distribution.md
    ├── 18-glossary.md
    ├── 19-widget-and-channels.md
    ├── 20-native-plugins.md   нативные плагины (Rust DLL, C ABI)
    └── 21-http-routes.md      HTTP-маршруты (http_route / static_route)
```

## Ментальная модель в один абзац

**Agent OS — это ядро для ИИ-агентов.** LLM — это «CPU»: платформа не делает
инференс, а *планирует* его на внешнем провайдере (DeepSeek / любой
OpenAI-совместимый API). Каждый агент — *процесс* с именем, инструкциями, набором
инструментов и бюджетом токенов. Инструменты — единственный способ агента
трогать мир; хуки перехватывают его жизненный цикл. Всё настраивается **YAML-файлами
в `config/`** (плюс опциональные **скрипты — JavaScript или Rhai**). Компилировать
ничего не нужно.

## Ключевые факты

- **Агенты** лежат в `config/agents/<name>/agent.yaml`; подкаталог на агента.
- **Инструменты** — YAML-файлы, подключаются агентом (`tool_files:`), с одним из
  `kind:`: `site_tool`, `archive_tool`, `json_tool`, `rss_tool`, `pdf_tool`,
  `trace_tool`, `geo_tool`, `script_tool`, `state_tool`, `table_tool`,
  `chart_tool`, `visualize_tool`, `subagent_tool`, `email_tool`, `vk_tool`,
  `workflow_tool`, `dll_tool`.
- **Хуки** — YAML-файлы, подключаются (`hook_files:`), один из `kind:`:
  `faq_cache`, `inject`, `escalate`, `memory`, `script_hook`, `dll_hook`.
- **Встроенные инструменты** (всегда доступны, без конфига): `http_fetch`,
  `fs_read`, `job_done`.
- **Бюджеты** — token-ведра в `config/budgets.yaml`, сгруппированы на шаблон с
  опциональными слоями per-user и per-session.
- **Live reload** включён по умолчанию: правки `config/agents/**` и
  `config/web/**` подхватываются без рестарта.
- **Секреты** (ключи API, токены) — в `.env`, никогда в YAML.

## Соглашения

- `agent_web_bot` — HTTP-сервер (главный процесс).
- `agent_bench` — E2E-бенчмарк.
- `site_tool` — тест конфига инструмента локально (без сервера и LLM).
- `hook_tool` — тест конфига хука локально.
- `route_tool` — локальный тест HTTP-маршрута (`http_route` / `static_route`).
- `workflow_tool` — локальный запуск воркфлоу.
- `scraper` — краулер сайта + анализатор архива.
