生产级 Agent 上线前必须检查的 50 件事
前面我发布了 Production Agent Checklist v1.0。
那是一份模块级清单。
今天这篇更像上线门禁。
如果一个 Agent 要进入真实用户环境，尤其是能读文件、写文件、跑命令、联网、调用 MCP 或触发业务流程，我会至少检查下面 50 件事。
不是为了吓人。
是为了避免那句最危险的上线理由：
我试了几次，感觉还行。
感觉不够。
上线要有证据。
1-5：身份和状态
- 每次执行都有
runId、turnId、traceId。 - 每个 step 有稳定 index 或
stepId。 - 每个 tool call 有
toolCallId。 final、failed、cancelled、paused、max_steps、budget_exhausted能区分。- 用户能看到当前任务状态，而不是只看到一个转圈动画。
没有身份，后面所有排障都会散。
6-10：Loop 控制
- 有
maxSteps。 - 有 wall-clock timeout。
- 支持用户取消。
- 能识别 repeated tool call。
- 能识别 repeated error。
Agent 不只要会跑。
它还要会停。
11-15：上下文
- Context Builder 不是简单拼聊天记录。
- 当前用户目标和显式约束不会被摘要覆盖。
- 安全策略不会被历史挤掉。
- 工具结果过长时会截断、摘要或保存 artifact。
- 每次 context build 都有 debug report。
模型答错时，先看它到底看见了什么。
16-20：模型和 Provider
- Runtime 有自己的
ModelResponse中间表示。 - provider 原始字段没有散落在业务代码里。
- 记录模型 token、latency、finish reason。
- 限流、超时、上下文超限有不同错误类型。
- 有 deterministic mock provider 测 Runtime 逻辑。
真实模型会变。
Runtime 的状态转移不能跟着飘。
21-25：工具系统
- 工具不是
Map<string, Function>。 - 每个工具有 schema、risk、timeout、output policy。
- 工具先 schema validation，再 policy validation。
- 未知工具返回 observation，不让进程崩溃。
- 工具版本进入 trace 和 eval。
Tool Calling 只是接口能力。
Tool Runtime 才是工程边界。
26-30：权限审批
- PermissionGate 在 execute 前运行。
- 写文件有 preview 或 diff。
- 网络工具展示域名和用途。
- 安装依赖展示包名、版本、registry、lockfile 影响。
- 破坏性操作默认拒绝或强确认。
用户批准的不是'运行工具'。
用户批准的是具体副作用。
31-35：Sandbox 和安全
- 文件读写限制在 workspace 内。
- 写入拒绝 symlink escape。
- 默认不读取
.env、SSH key、浏览器 profile、系统 credential。 - shell 默认只读白名单。
- 网络默认 deny 或 allowlist。
'开了 sandbox'不是答案。
要说明它隔离了什么。
36-40：Checkpoint 和恢复
- run 开始保存初始状态。
- 每个 step 后保存 checkpoint。
- 工具 planned / started / succeeded / failed / uncertain 有 ledger。
- 写文件前后记录 hash 和 diff。
- resume 时不自动重放不可幂等工具。
Checkpoint 不是聊天记录。
它是恢复证据。
41-45：Trace 和事故复盘
- 一次 run 对应一条 trace。
- context、model、tool、permission、checkpoint 都有 span 或 event。
- 大内容用 artifact ref，不直接塞进 trace。
- secret、token、cookie、private key 默认脱敏。
- 失败能归因到模型、工具、权限、上下文、runtime 或外部系统。
Trace 要回答'系统实际做了什么'。
不是只保存模型说了什么。
46-50：Eval、成本和发布
- Eval 不只比较最终回答。
- Eval 检查 required tool 和 forbidden tool。
- Eval 检查权限拒绝、resume、rollback。
- token、step、wall-clock、tool-call 四类预算进入报告。
- Release note 写明已知限制和高风险能力默认策略。
没有 eval 的上线，是靠记忆发布。
靠记忆发布，迟早会忘。
一个最小发布门禁
如果你现在没有完整平台，至少做这个最小门禁：
必须有：
- runId / traceId
- maxSteps
- Tool Registry
- PermissionGate
- workspace path check
- shell readonly policy
- checkpoint after step
- JSONL trace
- mock eval
- release known limitations
这十项做完，系统未必成熟。
但已经不是裸奔。
哪些可以暂时 N/A
清单不是一刀切。
只读 RAG Agent 可以暂时 N/A：
写文件 preview
安装依赖审批
rollback files
shell sandbox
但如果你的 Agent 能写文件、跑命令、联网或调用业务 API，就不要轻易 N/A。
越接近真实副作用，越需要 Runtime。
最后
上线前，我会问一句：
如果明天它出事，我们能不能知道发生了什么？
如果答案是否定的，那就还没准备好。
