Production Agent Checklist v1.0 发布
前 21 天，我一直在讲一个判断：
Agent Runtime 不是框架名。
它是一组工程责任。
今天把这组责任整理成第一版清单：
Production Agent Checklist v1.0
这不是最终版。
也不是'照着打勾就永远安全'的东西。
它的作用更朴素：让团队在讨论一个 Agent 能不能上线时，不再只说'我试了几次，感觉还行'。
感觉不够。
要有检查项。
这份清单适合谁
适合三类人：
正在做 coding agent / data agent / internal agent 的工程师
准备二开开源 agent framework 的团队
要评审 Agent 上线风险的技术负责人
不适合拿来做 PPT 装饰。
它应该进入：
README
PR 模板
release checklist
eval report
incident review
上线审批
如果一项检查永远不会影响发布决策，那它就不该留在清单里。
Production Agent Checklist v1.0
下面是第一版正文。
1. Run Identity
- 每次用户请求都有
runId、turnId、traceId。 - 每次模型决策或工具推进都有
stepId或 step index。 - 每个 tool call 有稳定
toolCallId。 - final、failed、cancelled、paused、max_steps、budget_exhausted 有明确 stop reason。
- 用户能看到任务是完成、失败、取消还是等待审批。
没有 ID，后面所有排障都是散的。
2. Loop Control
- Runtime 有 max steps。
- Runtime 有 wall-clock timeout。
- Runtime 能响应用户取消。
- Runtime 能识别 repeated tool call。
- Runtime 能识别 repeated error。
- Runtime 不允许模型无限重试同一个失败路径。
- 停止原因写入 trace 和最终响应。
Agent 要会做事，也要会停。
3. Context Builder
- 上下文不是简单拼接聊天记录。
- 当前用户目标和显式约束优先级最高。
- 安全策略不会被历史挤掉。
- repo map、文件片段、工具结果按相关性装载。
- 长工具输出有截断、摘要或 artifact ref。
- 每次 context build 输出 debug report。
- debug report 包含 included、summarized、dropped 和 reasons。
- 上下文预算进入 trace。
模型答错时，先看它到底看见了什么。
4. Model Provider
- Runtime 有自己的
ModelResponse中间表示。 - provider 原始字段不散落在业务代码里。
- tool calling、streaming、parallel tool calls、strict schema 等能力显式记录。
- 模型超时、限流、上下文超限有不同错误类型。
- 模型调用 token、latency、finish reason 进入 trace。
- 真实模型之外，有 deterministic mock provider 用于 runtime eval。
不要把 Runtime 绑死在某个 SDK 的字段名上。
5. Tool Registry
- 工具不是
Map<string, Function>。 - 每个工具有 name、version、description、schema。
- 每个工具有 risk level。
- 每个工具声明 timeout、parallelSafe、outputPolicy。
- 工具参数先 schema validation，再 policy validation。
- 未知工具返回结构化 observation，不让进程崩溃。
- 工具版本进入 trace 和 eval。
工具是 Runtime 的能力入口，不是随手注册的函数。
6. Tool Execution
- 工具执行有 timeout。
- 工具执行支持 AbortSignal 或取消机制。
- 工具输出有最大长度。
- 超长输出进入 artifact，不直接塞回模型。
- 工具结果有 status、errorCode、duration、outputChars、truncated、retryable。
- 并行工具由 Runtime 调度，不由模型直接决定。
- 并行结果写回顺序稳定。
模型提出动作，Runtime 安排执行。
7. Permission And Policy
- 每个高风险工具调用先生成 plan。
- PermissionGate 在 execute 前运行。
-
read、write、shell、network、install、dangerous风险分开。 - 写文件有 diff 或内容预览。
- 网络工具展示域名和用途。
- 安装依赖展示包名、版本、registry、lockfile 影响。
- 破坏性操作默认拒绝或强确认。
- 非交互模式有明确 policy，不默认全放行。
- permission decision 持久化，并进入 trace。
审批不是 UI 小插曲，是系统事实。
8. Sandbox And Harness
- 文件读写限制在 workspace 内。
- 写入拒绝 symlink escape。
- 默认不读取
.env、SSH key、浏览器 profile、系统 credential。 - shell 默认只读白名单。
- 网络默认 deny 或 allowlist。
- 子进程环境变量经过过滤。
- 工具有超时和进程树清理。
- sandbox profile 进入 trace。
- Harness 能说明自己提供了哪些隔离能力。
'开了 sandbox'不是答案。要说清开了什么。
9. MCP Governance
- MCP Server 有 trust level。
- MCP 工具进入本地 Tool Registry。
- MCP 工具有本地 namespace，避免名称冲突。
- 不直接相信 MCP 工具描述里的 safe/read-only。
- tools/list 结果变化写入 trace。
- schema hash 进入 trace。
- 当前 step 只暴露相关 MCP 工具给模型。
- 第三方或未知 MCP Server 默认 ask 或 deny。
- 非幂等 MCP 工具禁止自动重放。
MCP 解决连接，不解决治理。
10. Memory And State
- Run state、tool ledger、checkpoint 归 Runtime 管。
- 用户偏好归 Application 管。
- 业务事实保留在权威业务系统。
- 长期 memory 有来源、作用域、置信度、过期时间。
- 模型推断的长期偏好需要用户确认。
- Memory 是否进入上下文由 Context Builder 决定。
- 影响行动的 memory 来源进入 trace。
Agent 记错，比失忆更危险。
11. Checkpoint And Recovery
- run 开始保存初始状态。
- 每个 step 后保存 checkpoint。
- 工具 planned / started / succeeded / failed / uncertain 有 ledger。
- 写文件前记录 base hash。
- 写文件后记录 after hash 和 diff。
- resume 时校验 workspace 当前状态。
- 不自动重放不可幂等工具。
- rollback 前检查用户是否改过文件。
- 外部副作用使用 compensation，不假装 undo。
Checkpoint 保存的是恢复证据，不是聊天记录。
12. Trace And Observability
- 一次 run 对应一条 trace。
- context build、model call、tool plan、permission、tool execute、checkpoint 都有 span 或 event。
- trace 包含 token、latency、tool count、status、error kind。
- 完整 prompt、完整文件、完整 stdout 不直接塞进 trace。
- 大内容用 artifact ref。
- secret 输出会脱敏。
- 失败能归因到模型、工具、上下文、权限、runtime 或外部系统。
- 线上失败能转成 eval case 草稿。
Trace 不是日志堆，是事故证据链。
13. Eval And CI
- 有 deterministic mock model 测 Runtime 逻辑。
- 有真实模型 smoke eval。
- eval 不只比较最终回答。
- eval 检查 required tools。
- eval 检查 forbidden tools。
- eval 检查权限拒绝路径。
- eval 检查文件 diff 或业务结果。
- eval 检查 max steps、token、cost。
- checkpoint/resume 有回归用例。
- PR 或 release 需要附 eval 结果。
Agent 变好，要用证据证明。
14. Cost And Budget
- token budget、step budget、wall-clock budget、tool-call budget 分开。
- 每次 model call 记录 token usage。
- 每次 run 记录估算成本。
- 工具输出过大时降级。
- context 超限时按固定降级顺序处理。
- 成本异常能进入告警或 eval report。
- 不允许无限 retry 消耗预算。
成本不是财务最后看的东西，它是 Runtime 的停止条件。
15. Release Readiness
- README 说明当前 Agent 能做什么、不能做什么。
- 默认策略保守。
- 高风险能力默认关闭。
- 用户能取消长任务。
- 用户能看到 Agent 做过哪些关键动作。
- 失败时返回可理解原因。
- 有事故复盘路径。
- 有回滚或恢复方案。
- 关键风险写进发布说明。
能上线的 Agent，不是永不失败。
是失败后还能被理解、被停止、被恢复。
怎么使用这份清单
不要把它当一次性打勾表。
更好的用法是三层。
第一层，立项评审。
先判断这个 Agent 到底有没有生产风险。如果它只做只读问答，清单里很多项可以标成 N/A。如果它能写文件、跑命令、联网、改数据库，就不要跳过 Runtime 检查。
第二层，PR 门禁。
每次改工具、权限、上下文、checkpoint、provider adapter，都要说明影响了哪几项 checklist。
第三层，事故复盘。
出问题后，不要只写'模型判断错误'。回到清单，看是哪一层缺证据：context、tool、permission、checkpoint、trace，还是 eval。
v1.0 故意没有做成 50 项
后面我会写一篇：
生产级 Agent 上线前必须检查的 50 件事
那篇会更像 release gate。
今天这版是模块级清单。
它先回答一个更基础的问题：
你的 Agent Runtime 到底有哪些责任面？
把责任面画清楚，再去拆细项。
