运维

🔵 启动、测试、基准测试、部署和监控——仅使用编译后的二进制文件。

9.1 CLI 命令

一切通过一个二进制文件 agent-os 及其子命令完成（子命令 可通过模块扩展，经由注册表 agent_os_cli）：

命令	用途
`agent-os serve`	HTTP 服务器（主进程）
`agent-os bench`	智能体 E2E 基准测试
`agent-os tool`	本地测试 YAML 工具（无需服务器和 LLM）
`agent-os hook`	本地测试 YAML 钩子
`agent-os module workflow run`	本地运行工作流
`agent-os scrape`	将网站爬取为归档；分析归档
`agent-os route`	本地测试 HTTP 路由（`http_route` / `static_route`）
`agent-os office`	本地测试办公工具（首次运行时下载 OfficeCLI）
`officecli_pdf_exporter`	OfficeCLI 的 PDF 导出插件（headless Chromium）；`agent-os pdf-exporter` 上的垫片

9.2 启动服务器

./agent-os serve
AGENT_OS_BIND=0.0.0.0:8080 ./agent-os serve        # сменить адрес привязки

加载 .env、config/server.yaml、config/agents/**、 config/budgets.yaml、config/web/**。参见 03-server-configuration。

9.3 测试工具

agent-os tool config/agents/ngu/tools/ngu_search.yaml '{"query":"поступление"}'
agent-os tool config/agents/drom/tools/drom_find_brands.yaml '{"query":"газ"}'

打印传入的参数、call_template、给 LLM 的输出以及 result_template。出错时返回非零退出码。

9.4 测试钩子

agent-os hook config/agents/ngu/hooks/faq_cache.yaml user "Как поступить на фит?"
agent-os hook config/agents/ngu/hooks/faq_cache.yaml turn "вопрос" "ответ" --db /tmp/faq.db
agent-os hook config/scripts/hooks/moderation.yaml user "Привет" --live   # реальный LLM-судья

命令：info、user "<msg>"、turn "<q>" "<a>"、loop "<reason>"。标志： --db、--live、--agent、--template、--user、--session。

9.5 基准测试

agent-os bench 运行来自 config/agents/<agent>/bench/scenarios.yaml 的场景。

# против работающего сервера
agent-os bench --url=https://HOST --agent=drom --max=5

# поднять собственный локальный сервер (нужен DEEPSEEK_API_KEY в .env)
agent-os bench --port=3001 --max=3

# фильтр по имени сценария (подстрока / regex)
agent-os bench --url=https://HOST --name="Camry|BMW" --max=10

# параллельность + таймаут
agent-os bench --url=https://HOST --agent=drom --parallel=3 --timeout=90

标志：

标志	默认值	描述
`--url=`	（启动本地实例）	连接到正在运行的服务器（跳过启动）
`--port=`	`3001`	本地服务器端口（在 `--url` 时忽略）
`--agent=`	（全部）	仅此模板
`--name=`	（全部）	仅名称中包含此子串的场景
`--max=`	全部	最多 N 个场景
`--parallel=`	`4`	并行场景数
`--timeout=`	`90`	回合超时（秒）

结果写入工作目录中的 bench_report_<timestamp>.json，包含计数器 passed/failed 和每回合 failures。

场景格式

name: "Drom Agent"
model: "drom-agent"

scenarios:
  - name: "Поиск Camry"
    turns:
      - user: "Найди Toyota Camry"
        assert:
          contains: [camry]
          min_links: 2
          valid_urls: true

检查项：contains（子串）、min_links / min_urls（markdown 链接数）、valid_urls（所有链接均为 http/https）。

9.6 将网站爬取为归档

agent-os scrape https://nsu.ru -w 8 -d 3 -n 500          # обход
agent-os scrape --analyze nsu_full.archive               # анализ повторяющихся блоков

标志：-w/--workers、-d/--max-depth、-n/--max-pages、-r/--rate-limit （毫秒）、-o/--output（归档路径）、-m/--navmap、--timeout（秒）、 --no-same-domain。

归档（包含 meta.json、docs.bin、terms.bin 的目录）正是 archive_tool 所查找的内容。

9.7 监控与日志

来源	位置	显示内容
服务器 stdout	前台启动 / 重定向到文件	启动、错误、模板列表
JSONL 追踪	`logs/process-<pid>.jsonl`	进程事件（启动、工具调用、错误）
事件存储	`logs/events.db`（DuckDB）	可查询的事件历史
消息存储	`logs/messages.db`（DuckDB）	转录 + FAQ 缓存
访问日志	`logs/access.jsonl`、`logs/access.db`	仅 HTTP 请求
Cron 存储	`logs/cron.db`（DuckDB）	任务 + 每次运行的状态/令牌/成本
健康检查	`curl .../health`	服务是否存活

读取追踪：`agent-os trace` 和 HTTP API

服务器运行时，DuckDB 文件被其连接锁定，因此无法从外部打开。为此提供了基于同一引擎 trace_tool 的只读 HTTP API 和 CLI：

agent-os trace sessions [--agent TEMPLATE] [--only-errors] [--limit N]
agent-os trace transcript <session_id> [--search QUERY] [--limit N]
agent-os trace events <session_id> [--limit N]
agent-os trace search <query> [--limit N]

CLI 访问 GET /v1/trace/{sessions,events,transcript,search}（admin 网关）。基础 URL — --url / AGENT_OS_URL（默认 http://127.0.0.1:3000），令牌 — --token / AGENT_OS_ADMIN_TOKEN / 来自 config/server.yaml 的第一个完整令牌。这些端点也便于从脚本和管理后台调用。

使用 `trace-agent`

模板 trace-agent（config/agents/trace/agent.yaml）——基于 logs/events.db 的诊断助手。在聊天中问它「哪些会话出现了错误？」、「智能体 X 花了多少？」、「哪些搜索返回了零结果？」。它的工具 trace_*（sessions、events、transcript、search、process）在 trace_tool 中有描述。

仪表盘

页面 /dashboard（及其 API GET /v1/dashboard）提供服务器的摘要：

系统 — CPU、内存、uptime、构建版本；
提供商 — 当前模型和 base URL、并发限制；
状态 — 活跃/总会话数、活跃进程数、模板数、预算组数、已消耗令牌；
Auth — 是否启用 admin-auth、令牌/用户数；
序列 — 来自事件存储的活动/令牌时间序列。

9.8 部署配置变更

仅配置变更（智能体、工具、钩子、预算、网页内容）无需重新构建——将修改后的 config/ 和 data/ 复制到服务器并重启（或依赖 config/agents/** / config/web/** 的实时重载）：

# загрузить
scp -r config/ data/ user@host:/path/to/agent_os/

# перезапустить
ssh user@host "kill \$(pgrep agent-os); cd /path/to/agent_os && \
  set -a && source .env && set +a && nohup ./agent-os serve > agent_os.log 2>&1 &"

# проверить
curl -sk https://HOST/health

如果添加了新的工具/钩子引擎（新的 kind:，需要 Rust 代码），则必须重新构建二进制文件——但在现有引擎上添加智能体/工具/钩子永远不需要这样做。

从 git 仓库部署配置

无需复制文件，直接为服务器指定配置仓库——它会在启动时克隆并固定（或轮询）：

# зафиксировать тег при старте
AGENT_OS_CONFIG_REPO=https://github.com/org/agent-config \
AGENT_OS_CONFIG_REF=v1.2.0 \
./agent-os serve

# или опрашивать репозиторий и hot-reload при изменении
AGENT_OS_CONFIG_REPO=https://github.com/org/agent-config \
AGENT_OS_CONFIG_POLL=60 \
./agent-os serve

已解析的提交会在启动时记录日志，并可在 /health 的 config 字段中看到（source、url、ref、commit、poll_secs）。要发布变更—— 在配置仓库中提交/打标签并重启（pin 模式）或等待下一次轮询。参见 §3.1。

9.9 TLS

通过 AGENT_OS_TLS_CERT / AGENT_OS_TLS_KEY 指定 PEM 证书/密钥；否则——使用普通 HTTP（例如在反向代理之后）。

运维