工具 — 监控与调试

🔵 对 agent 追踪的只读查询以及工具的本地测试。所有引擎的汇总表请参见 «工具参考»。

5.9 trace_tool

对 agent 追踪的查询。对 logs/events.db 和 logs/process-*.jsonl 的只读查询。operation 选择查询：

operation	用途	关键参数
`sessions`	会话列表 + 聚合统计	`limit`, `offset`, `agent`, `only_errors`
`events`	会话/进程事件时间线	`session_id` 或 `pid`, `event_type`, `search`, `limit`
`transcript`	会话对话	`session_id`, `search`
`search`	对转录文本的全文搜索	`query`, `limit`
`process`	进程的原始 JSONL 追踪	`pid`, `event_type`, `include_tokens`, `search`, `limit`
`feedback`	按模板/用户/会话/值统计点赞/点踩	`group_by`, `value`, `template`, `user_id`, `session_id`, `days`
`escalations`	升级漏斗：有多少转给了操作员（requested/resolved），按原因和渠道	`days`, `limit`
`blind_spots`	«盲区»：经常返回 warning（空搜索）或失败的工具，按工具统计	`days`, `limit`

可见性与作用域

trace_tool 只返回调用者有权看到的内容：

上下文	作用域	可以查询什么
`admin_templates: "*"`	完整	所有会话 / 进程
`admin_templates: "a,b"`	受限	仅这些模板
无管理员，有 `user_id`	用户级	仅自己的会话 / 转录文本 / 进程
两者都没有	禁止	`access denied`

最终用户 agent（例如 Феликс）在没有管理员令牌时会自动从其会话的 X-User-Id 获得 user 作用域 — 其搜索只能看到当前用户的历史记录，不会在用户之间泄露。

5.21 本地测试

agent-os tool <tool.yaml> '<json_args>'
agent-os office <tool.yaml> '<json_args>'        # с автозагрузкой officecli

输出：参数、call_template（用户之前看到的内容）、给 LLM 的输出、 result_template（之后看到的内容）。agent-os tool 支持所有 kind: — site_tool, browser_tool, archive_tool, pdf_tool, rss_tool, json_tool, trace_tool, script_tool, state_tool, geo_tool, table_tool, chart_tool, visualize_tool, subagent_tool, email_tool, workflow_tool, duckdb_tool, sql_tool, shell_tool, file_tool, office_tool, vk_tool, ym_tool。单独的命令 agent-os office — 是办公 kind: office_tool 的轻量封装：首次运行时下载 officecli 并打印 file 结果块。