《Agent Runtime 工程化》Production Agent Checklist v1.0 发布

• 上下文不是简单拼接聊天记录。
• 当前用户目标和显式约束优先级最高。
• 安全策略不会被历史挤掉。
• 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 到底有哪些责任面？

把责任面画清楚，再去拆细项。

推荐阅读

• 试读章节：Agent Loop 的完整生命周期
• 试读章节：Tool Runtime 与权限审批
• 一个 Agent Runtime 失败案例的完整 Trace