Cheat Sheet

🔵 Quick lookup tables. Full details are in the referenced sections.

Commands

# Всё — подкоманды единого CLI `agent-os` (подкоманды расширяемы модулями)

# Сервер
agent-os serve                                     # запуск (по умолч. 127.0.0.1:3000)
AGENT_OS_BIND=0.0.0.0:8080 agent-os serve          # сменить адрес

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

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

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

# Бенчмарк
agent-os bench --url=https://HOST --agent=drom --max=5
agent-os bench --port=3001 --max=3
agent-os bench --url=https://HOST --agent=drom --repeats=3   # 3 прогона, усреднение (pass^N)

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

Fields `agent.yaml`

Field	Description
`name`	template name (unique)
`instructions`	system prompt
`welcome`	widget greeting
`tools`	built-in: `http_fetch`, `fs_read`, `job_done`
`tool_files`	paths to YAML tools (relative to the agent folder)
`hooks` / `hook_files`	hook names / paths to YAML
`max_context_tokens`	defaults to 32000
`max_output_tokens`	response ceiling per inference (per-agent; overrides `kernel.max_output_tokens`)
`model`	named model from `server.yaml → models:`
`budget` / `budget_group`	budget override / shared group
`budget_messages`	`session_exhausted`, `user_exhausted`, `group_exhausted`, `rate_limited`
`inherit_budget`, `parent`	process tree / group inheritance
`durable`	`true` = session survives core restart (opt-in, §27.2)
`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}`
`yandex_messenger`	`{token_env, allowed_logins, show_typing, show_tool_calls, poll_secs}`
`cron`	scheduled jobs (see §11)
`output_schema`	JSON Schema → `job_done` returns a structure (validated)

Tool engines (`kind:`)

kind	What it's for
`site_tool`	declarative HTTP/API client: scraping + REST (method/body/oauth2) → extract fields → format
`rest_tool`	alias of `site_tool` for REST/API integrations
`browser_tool`	headless browser: JS sites, steps (goto/click/type/check), JS in the page, screenshot/PDF
`archive_tool`	search/read a local text archive
`json_tool`	search over preloaded JSON
`rss_tool`	search over RSS feeds
`pdf_tool`	read PDF page by page
`trace_tool`	queries to agent traces
`geo_tool`	geocoding and POI (OpenStreetMap)
`rasp_tool`	transport schedules (Yandex.Schedules): `station_list`/`search`/`schedule`/`thread`/`nearest_stations`
`map_tool`	map with markers (Leaflet; providers osm/google/yandex/2gis/custom)
`script_tool`	custom logic in JS or Rhai
`wait_tool`	pause for N seconds (timing of polling for long operations)
`state_tool`	scoped state store (session/user/agent/team)
`table_tool` / `chart_tool`	static table/chart
`visualize_tool`	chart/table from data (or the result of another tool)
`subagent_tool`	delegate a task to a subagent
`email_tool`	send an email (SMTP)
`vk_tool`	VK API call: `method`/`params` or `action` (`send_message`/`wall_post`/`search`)
`ym_tool`	Yandex Messenger (Bot API): `action` (`send`/`send_file`/`get_updates`/`get_file`), `login`/`chat_id`/`to`
`workflow_tool`	run a workflow
`duckdb_tool`	your own DuckDB database: raw `query`/`execute`/`schema` (`init`, `{user}`/`{session}`/`{template}`) or declarative `operations:` without free-form SQL (`emit_visual`, `sandbox`)
`sql_tool`	SQL access to an external PostgreSQL/MySQL (query/execute/schema, pool by URL)
`shell_tool`	run an external CLI command (command/args/env from YAML)
`file_tool`	send a file to the user (content/data/path/temp/state/source)
`office_tool`	generate/read Word·Excel·PowerPoint via OfficeCLI (`create`/`fill`/`extract`/`convert`/`edit`/`merge`)
`storage_tool`	files on S3/WebDAV/FTP (`list`/`get`/`put`/`delete`, `prefix`)
`calendar_tool`	read/manage Google Calendar (service account): `list_calendars`/`list`/`get`/`create`/`update`/`delete`/`quick_add`
`google_tool`	Google Drive/Sheets/Docs/Slides (service account, field `service`): `action` + `method`/`params`/`body`
`yandex_tool`	Yandex.Disk/Calendar (user OAuth, field `service`): `action` + `method`/`params`/`body`
`vision_tool`	OCR/image analysis with a vision model (`deepseek-v4-flash-vision-exp`): one or more images + prompt
`image_tool`	image processing (crop/resize/grayscale/rotate/flip/brightness/contrast/blur/format): `input` (URL / data: / path / `temp`), `ops` (batch), `output?`, `send?`

Text-to-image generation — native kind image_gen_tool (by default the Pollinations backend, free, no key): fields url_template, style, model, width/height, send/output. See 5.33. An alternative is a recipe of two tools (script_tool generate_image + image_tool image_fetch), 5.32.

Workflow steps (`type:`)

agent (template/prompt/output_schema), tool (tool/args), saga (steps with compensate), condition (when/then/else), for_each (over/item/steps/collect). Files in config/workflows/*.yaml; run with POST /v1/workflows/<name>/run.

Hook kinds (`kind:`)

kind	What it's for
`faq_cache`	response cache, skip the LLM on repeats
`inject`	inject context messages
`escalate`	handoff to a human when the agent can't help
`memory`	long-term memory per user
`rag`	retrieval from the archive: inject relevant chunks into the context
`tool_cache`	cache read-only tool results by `(scope, tool, args)`
`link_check`	verify links in the response: grounding against the archive, opt-in `live` HTTP
`condense`	convert a follow-up into a standalone query using the history
`compact_results`	compress long tool outputs (+ spill/`read_overflow`)
`format_guard`	format links in the response: bare URL → markdown, dedup, one per line
`loop_guard`	break tool-call loops: `deny` repeats above the threshold
`groundedness`	verify the response's claims against the archive/tool results; `notice`/`rework`
`guard`	DLP membrane: entity detection + `redact`/`deny`/`suppress`/`notice`/`rework` on input/output/tools
`pseudonymize`	surrogates `[TYPE_n]` into the model, DuckDB vault, detokenizing the response and tool arguments
`circuit_breaker`	config of the native provider breaker (threshold/cooldown) for the agent
`model_router`	classifier-based model routing (onnx/llm/hybrid)
`intent_router`	classifier-based triage: reply/inject/notice/escalate
`lexicon`	self-learning query normalizer: slots + gap + golden gate
`script_hook`	custom logic in JS or Rhai

Transformations `site_tool` extract

lookup, truncate, take, skip, len, not_null, bool, int, filter (template), transliterate, strip_html.

Budget fields

refill_per_sec (tokens/sec), max_bucket (burst), max_total (per lifetime, absent = no limit), warn_at (threshold on_budget_threshold). Layers: группа → per_user → per_session.

Environment variables

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

Admin tokens from env are read from the variable named in auth.admin_token_env (for example AGENT_OS_ADMIN_TOKEN); without this field the variable is ignored.

Script helpers (JS and Rhai)

http_get(url[,timeout][,headers]), http_post(url,body[,ctype[,timeout[,headers]]]), 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. Engine by extension .js vs .rhai.

Key HTTP endpoints

/health, /v1/models, /v1/templates, /v1/agents, /v1/sessions, /v1/agents/:pid/signal (steering), /v1/budgets, /v1/chat/completions, /v1/uploads, /v1/input-response, /widget, /widget.js, /proxy?url=, /proxy/content?url=, /v1/cron, /v1/workflows, /v1/workflows/:name/run, /v1/workflows/runs/:id, /v1/inbound/:template.

Reactions: config/reactions.yaml — rules on (kind/template/tool/ content/threshold/idle) → action (spawn_agent / run_workflow / call_tool / webhook / signal). See 31-reactions.

What goes where

What	Path
Server config	`config/server.yaml`
Budgets	`config/budgets.yaml`
Agent template	`config/agents/<name>/agent.yaml`
Tools	`config/agents/<name>/tools/*.yaml`
Hooks	`config/agents/<name>/hooks/*.yaml`
Benchmark	`config/agents/<name>/bench/scenarios.yaml`
Tool tests	`config/agents/<name>/tests/*.yaml`
Script examples	`config/scripts/`
Archives/JSON	`data/`
Logs/DB	`logs/`
Secrets	`.env`

Live reload

config/agents/** + config/web/** → hot-reload (with kernel.live_reload: true).
config/server.yaml → restart required.
Running processes keep the system prompt from the moment of spawn.