# 10. Шпаргалка

🔵 Быстрые таблицы для поиска. Полные детали — в указанных разделах.

## Команды

```bash
# Сервер
./agent_web_bot                                    # запуск (по умолч. 127.0.0.1:3000)
AGENT_OS_BIND=0.0.0.0:8080 ./agent_web_bot          # сменить адрес

# Тестер инструмента (без сервера и LLM)
site_tool <tool.yaml> '<json_args>'

# Тестер хука
hook_tool <hook.yaml> info|user|turn|loop [text...] [--db p] [--live]

# Локальный запуск воркфлоу (agent-шаги используют провайдер)
workflow_tool <workflow.yaml> ['{"input": ...}'] [--args-file args.json]

# Бенчмарк
agent_bench --url=https://HOST --agent=drom --max=5
agent_bench --port=3001 --max=3

# Краулер
scraper https://site -w 8 -d 3 -n 500
scraper --analyze site.archive
```

## Поля `agent.yaml`

| Поле | Описание |
|---|---|
| `name` | имя шаблона (уникальное) |
| `instructions` | системный промпт |
| `welcome` | приветствие виджета |
| `tools` | встроенные: `http_fetch`, `fs_read`, `job_done` |
| `tool_files` | пути к YAML-инструментам (отн. папки агента) |
| `hooks` / `hook_files` | имена хуков / пути к YAML |
| `max_context_tokens` | по умолчанию 32000 |
| `model` | именованная модель из `server.yaml → models:` |
| `budget` / `budget_group` | перекрытие бюджета / общая группа |
| `budget_messages` | `session_exhausted`, `user_exhausted`, `group_exhausted`, `rate_limited` |
| `inherit_budget`, `parent` | дерево процессов / наследование группы |
| `telegram` | `{token_env, allowed_user_ids, show_typing, show_tool_calls}` |
| `email` | `{imap_host, imap_port, imap_username, imap_password_env, allowed_senders, smtp, notify, poll_secs}` |
| `vk` | `{token_env, group_id, allowed_user_ids, show_typing, show_tool_calls, poll_wait}` |
| `cron` | задания по расписанию (см. §11) |
| `output_schema` | JSON Schema → `job_done` возвращает структуру (валидируется) |

## Движки инструментов (`kind:`)

| kind | Для чего |
|---|---|
| `site_tool` | скрап страницы/API → извлечь поля → формат |
| `browser_tool` | headless-браузер: JS-сайты, шаги (goto/click/type/check), JS в странице, скриншот/PDF |
| `archive_tool` | поиск/чтение локального текстового архива |
| `json_tool` | поиск по предзагруженному JSON |
| `rss_tool` | поиск по RSS-лентам |
| `pdf_tool` | чтение PDF постранично |
| `trace_tool` | запросы к трейсам агентов |
| `geo_tool` | геокодинг и POI (OpenStreetMap) |
| `script_tool` | своя логика на JS или Rhai |
| `state_tool` | scoped state store (session/user/agent) |
| `table_tool` / `chart_tool` | статичные таблица/график |
| `visualize_tool` | график/таблица из данных (или результата другого инструмента) |
| `subagent_tool` | делегировать задачу субагенту |
| `email_tool` | отправить письмо (SMTP) |
| `vk_tool` | вызов VK API: `method`/`params` или `action` (`send_message`/`wall_post`/`search`) |
| `workflow_tool` | запустить воркфлоу |
| `duckdb_tool` | своя DuckDB-база (query/execute/schema, `init`, `{user}`/`{session}`/`{template}`) |
| `sql_tool` | SQL-доступ к внешней PostgreSQL/MySQL (query/execute/schema, пул по URL) |
| `shell_tool` | запустить внешнюю команду CLI (команда/args/env из YAML) |
| `file_tool` | отправить файл пользователю (content/data/path/temp/state/source) |
| `office_tool` | генерация/чтение Word·Excel·PowerPoint через OfficeCLI (`create`/`fill`/`extract`/`convert`/`edit`/`merge`) |

## Шаги воркфлоу (`type:`)

`agent` (`template`/`prompt`/`output_schema`), `tool` (`tool`/`args`),
`condition` (`when`/`then`/`else`), `for_each` (`over`/`item`/`steps`/`collect`).
Файлы в `config/workflows/*.yaml`; запуск `POST /v1/workflows/<name>/run`.

## Виды хуков (`kind:`)

| kind | Для чего |
|---|---|
| `faq_cache` | кэш ответов, пропуск LLM на повторах |
| `inject` | впрыснуть контекстные сообщения |
| `escalate` | передача человеку, когда агент не может помочь |
| `memory` | долгая память на пользователя |
| `script_hook` | своя логика на JS или Rhai |

## Трансформации `site_tool` extract

`lookup`, `truncate`, `take`, `skip`, `len`, `not_null`, `bool`, `int`,
`filter` (шаблон), `transliterate`, `strip_html`.

## Поля бюджета

`refill_per_sec` (токенов/сек), `max_bucket` (burst), `max_total` (за жизнь,
отсутствует = без лимита). Слои: `группа → per_user → per_session`.

## Переменные окружения

`DEEPSEEK_API_KEY` / `AGENT_OS_API_KEY`, `AGENT_OS_BIND`,
`AGENT_OS_TLS_CERT` / `AGENT_OS_TLS_KEY`, `AGENT_OS_ADMIN_TOKEN`,
`AGENT_OS_CONFIG_REPO` / `_REF` / `_DIR` / `_POLL`, `AGENT_OS_DISTRIB_DIR`.

## Помощники скриптов (JS и Rhai)

`http_get(url[,timeout])`, `http_post(url,body[,ctype[,timeout]])`,
`http_put`/`http_patch`/`http_delete`, `http(method,url,…)`, `env_var(name)`,
`llm(...)`, `now()`, `sleep_ms(ms)`, `print`/`debug`, `urlencode`/`url_encode`,
`urldecode`/`url_decode`, `extract_script_json(html,contains)`,
`json_get(data,pointer)`, `schedule_cron`/`cancel_cron`/`list_cron`,
`state_get`/`state_set`/`state_push`/`state_sadd`/…,
`db_query`/`db_execute`/`db_schema`, `shell`. JSON: JS —
`JSON.parse`/`JSON.stringify`, Rhai — `parse_json`/`to_json`. Движок по
расширению `.js` vs `.rhai`.

## Ключевые HTTP-эндпоинты

`/health`, `/v1/models`, `/v1/templates`, `/v1/agents`, `/v1/sessions`,
`/v1/budgets`, `/v1/chat/completions`, `/widget`, `/widget.js`,
`/proxy?url=`, `/proxy/content?url=`, `/v1/cron`, `/v1/workflows`,
`/v1/workflows/:name/run`, `/v1/workflows/runs/:id`, `/v1/inbound/:template`.

## Где что лежит

| Что | Путь |
|---|---|
| Конфиг сервера | `config/server.yaml` |
| Бюджеты | `config/budgets.yaml` |
| Шаблон агента | `config/agents/<name>/agent.yaml` |
| Инструменты | `config/agents/<name>/tools/*.yaml` |
| Хуки | `config/agents/<name>/hooks/*.yaml` |
| Бенчмарк | `config/agents/<name>/bench/scenarios.yaml` |
| Тесты инструментов | `config/agents/<name>/tests/*.yaml` |
| Примеры скриптов | `config/scripts/` |
| Архивы/JSON | `data/` |
| Логи/БД | `logs/` |
| Секреты | `.env` |

## Live reload

- `config/agents/**` + `config/web/**` → hot-reload (при `kernel.live_reload: true`).
- `config/server.yaml` → нужен рестарт.
- Запущенные процессы хранят системный промпт с момента спавна.
