我为什么写《Agent Runtime 工程化》
过去几天，我连续写了 6 篇关于 Agent Runtime 的文章。
先讲 Demo 为什么上不了生产，再讲 Agent Loop、Harness、Runtime 的边界。然后写 Retry 重复下单、token 成本失控、Production Runtime 架构、Memory 污染。
这些问题看起来分散，其实都指向同一件事：
Agent 真正难的部分，已经从'怎么做 demo'转到'怎么可靠运行'。
所以我决定把这套东西系统写下来。
书名就叫：
《Agent Runtime 工程化：生产级 AI Agent 架构、运行时与工程实践》
这篇算正式官宣。
为什么不是再写一本 Prompt 书
Prompt 很重要。RAG 也重要。Tool calling、MCP、Agent framework 都重要。
但这些东西进到生产环境后，会不断撞上更底层的问题：
- 谁拥有 run state？
- 谁决定工具能不能执行？
- 谁处理超时和取消？
- 谁保证 retry 不会重复副作用？
- 谁知道模型这一轮看见了哪些上下文？
- 谁控制 token 和成本？
- 谁保存 checkpoint？
- 谁记录 trace？
- 谁把事故变成 eval case？
- 谁让用户能理解 Agent 到底做了什么？
这些问题靠 prompt 很难补好。
它们属于 Runtime。
很多团队一开始会以为自己在做 Agent，做着做着发现自己在写一个小型操作系统：状态、调度、权限、日志、恢复、资源预算、外部工具、审计、回归测试。名字不一样，味道很像。
这本书想讲的就是这部分。
社区窗口已经打开了
现在中文技术社区里，'Agent Runtime'已经不是没人讲的概念。
英文社区更明显。Anthropic 在讲 effective agents 时，会区分 workflow 和 agent。LangGraph 把 durable execution、human-in-the-loop、persistence 放到 agent orchestration 的核心能力里。OpenAI Agents SDK 也把 sessions、tracing、guardrails、handoffs、human approval flows 做成一套开发体验。MCP 把外部工具连接标准化，但同时也把工具安全、用户同意、隐私边界摆到了台面上。OWASP 已经把 Excessive Agency 写进 LLM 应用风险。
这些信号说明一件事：
Agent 的竞争不再只是'谁接了更多工具'。下一阶段会变成'谁能把这些工具安全、稳定、可恢复地跑起来'。
我不想把这本书包装成'国内第一本'。这种说法风险很高，也没必要。
更准确的位置是：
系统讲清楚一个 Agent 如何从 Demo 进入生产环境。
我真正想解决的读者问题
这本书不是给完全没写过代码的人看的。
它面向三类人：
有 TypeScript/Node.js 基础的后端、全栈、工具链工程师。
准备二开 coding agent 或企业内部 agent 平台的架构师。
希望从 prompt 使用者升级为 runtime 工程师的技术负责人。
读者读完后，不应该只是'知道很多概念'。
我希望你能真的做到：
- 解释 Agent、Workflow、Tool、Runtime 的边界。
- 设计一个 TypeScript/Node.js 版最小 Agent Loop。
- 为工具设计 schema、风险等级、输出策略和失败语义。
- 建立上下文预算、repo map、滚动摘要和 debug report。
- 接入 MCP Server，并处理动态工具变化和信任分层。
- 设计 shell、文件、网络、安装、破坏性操作的权限策略。
- 实现 checkpoint、resume、rollback 的核心数据结构。
- 用 trace 定位模型、工具、权限、上下文或 runtime 问题。
- 用 eval harness 做回归门禁，而不是靠感觉判断好坏。
- 读懂主流开源 coding agent 的执行链路，并提出 PR 级改造方案。
如果这些能力听起来比'写一个 Agent Demo'麻烦，那就对了。
生产级工程本来就麻烦。
全书怎么组织
这本书分四个阶段。
第一阶段是入门。
先把 Agent、Workflow、Tool、Runtime 的边界讲清楚，再补 TypeScript/Node 的运行时基础，最后写一个最小 Agent Loop。这里不会上来就堆框架名，因为框架换得很快，运行机制更值得先学。
第二阶段是进阶。
把工具系统、上下文工程、MCP 和 Provider Adapter 接进来。也就是从'模型会调用函数'，走到'工具有 schema、权限、失败分类、输出策略；上下文有预算和 debug report；外部工具能通过 MCP 接入，但不能绕过本地治理'。
第三阶段是工程化。
处理权限、安全、checkpoint、resume、rollback、trace、eval、成本治理和 CI 回归。这里会讲很多 demo 里不会出现的东西：重复副作用、路径逃逸、secret、长日志截断、恢复后不能重放、trace 转 replay、成本进入 eval。
第四阶段是产品级实战。
先整理几条进阶路线：Eval Harness、Context Budget Allocator、MCP 工具权限层、Checkpoint/Rollback、Observability、产品化 Runtime。最后用一个真实 agent 项目做阅读样本，演示怎么在复杂代码里找 runtime 主线，并设计一个能进入 PR 的改造。
这不是'看完就会造一个独角兽产品'的书。
更现实一点：看完后，你应该能在一个真实 Agent 项目里知道该查哪里、改哪里、怎么验证，遇到线上事故时不再只说'模型不稳定'。
为什么用 TypeScript / Node
因为现在很多 Agent 产品、CLI 工具、前后端一体化应用、MCP server、开发者工具，都绕不开 TypeScript/Node。
Node 也很适合讲 Runtime 问题。
Promise、async iterator、AbortSignal、stream、child_process、文件系统、HTTP client、package manager、CLI，这些都是 Agent Runtime 会直接碰到的东西。一个 coding agent 要跑测试、读文件、改代码、执行命令，就必须面对 timeout、取消、输出背压、进程清理和环境变量脱敏。
所以书里不是只写伪代码。会有一个配套 mini runtime，围绕这些机制逐步扩展。
当然，这本书讲的不是 TypeScript 语法书。语言只是载体。真正要训练的是 runtime 判断。
工程入口会怎么做
这本书会配套一个工程入口，用来承载目录、架构图、示例代码、checklist 和读者反馈。
它不应该只是宣传页。更理想的状态是：读者读到某个 runtime 问题时，能顺手找到对应代码、测试和检查项。
参考资料
- Anthropic Engineering: Building effective agents
- LangGraph Docs: Overview
- OpenAI Agents SDK Docs: Agents
- Model Context Protocol Docs: Architecture
- OWASP: LLM06: Excessive Agency
