Agent 健康：分诊与修复
🔵 作为工程师（admin）如何处理崩溃的 agent：找到故障、弄清原因、
做最小修改，并用一次运行证明它。没有验证的报告不算
结果。
1. 找到出错的会话
| 步骤 | 工具 | 看什么 |
|---|---|---|
| 有错误的会话 | trace_sessions(only_errors=true) |
tool_errors、errors、warnings、agent、end_type |
| 按 agent 精确定位 | trace_sessions(agent=<template>) |
该模板最近的会话 |
| 按文本搜索 | trace_search(query="error") |
错误字符串本身及其会话 |
| 对话 | trace_transcript(session_id) |
请求 → 响应，调用了哪些工具 |
| 时间线 | trace_events(session_id) |
tool_call/tool_result、success:false 的顺序 |
指标 warnings 既统计工具的声明式警告，也统计 extractor-warning
（_warnings：响应中缺失/可选字段）。在
tool_errors=0 时 warnings 非零——是「软」故障的信号（搜索返回空、字段没找到）。
2. 读取 agent 配置
agent_config_show(name)—— bundle 的元数据（文件列表），然后agent_config_file(name, "tools/x.yaml")—— 按需读取单个文件。- 受保护的
admin/trace无法通过 builder 读取（403）——这是预期行为。 - 如果出现 404「unknown agent」——要么它不在
config/agents/中，要么 它是模块的内置 bundle（例如来自code的coder）：它存在于templates_list中，但不在agent_configs_list中。
3. 对原因进行分类
| 轨迹中的症状 | 可能原因 | 修改 |
|---|---|---|
Error: env var 'X' is not set |
密钥不在环境中 | env_set(X, …)（密钥只放在 env） |
oauth.token_file '…': expected value at line 1 column 1 |
token 的 JSON 为空/损坏 | 重新授权：oauth_connect/reconnect，在指令中自动 refresh |
Tool 'X' is not allowed for this process |
工具被直接调用，而不是通过 tool_call |
通过 tool_call(name,args) 或 tool_attach 重写调用 |
Network error … /v1/tools/…（约 60 秒后） |
嵌套 loopback 调用挂起/未被处理 | 不要重试；替换为真实文件 + tool_call |
script_tool 处的 No such file or directory |
tool_run_yaml 拉不起 sibling 脚本 |
建立 tools/<file>.yaml + tool_attach |
| 同一个工具以同样的错误反复出现 | 指令中没有「stop 规则」 | 添加禁止重复及下一步 |
no human response within … — approval timed out |
gated 工具没有人工介入 | 用 delegate 代替 agent_run（approval 会弹到聊天中） |
/v1/builder/* 上出现 403/404 |
builder 模块未激活 | 直接说明，不要编造字段 |
4. 最小修改
一次只改一样：指令、一个工具、一个 hook、一个环境变量。不要
重写整个 bundle。对于 agent.yaml —— agent_config_file → 修改 →
agent_config_validate → agent_config_upsert(agent_yaml=…)；其余文件
保持不变。
5. 证明结果
- 快速：
agent_run(template, message)—— 一个回合；然后trace_transcript(session_id)—— 实际发生了什么。 - 可靠：
bench_run(template)（低成本运行）和bench_run_show(run_id)—— 比较修改前后的回合/工具/token。只有当运行 证实了，修改才算「完成」。 - 展示 before/after，并诚实说明哪些改善了、哪些没有。
6. 报告
简要说明：(1) 什么崩溃了、在哪里（session id、确切错误），(2) 原因，(3) 改动了 什么（文件 + 要点），(4) 用什么证实（运行、指标），(5) 还剩什么。
安全
- 在执行破坏性操作（
agent_kill、session_close、module_disable、agent_config_delete、env_unset、platform_restart）之前——先警告并 请求确认。 admin和trace受保护：只能tool_attach/tool_detach。- 不要编造端点、字段和配置键——要读取真实的 bundle。