背压是很多 Agent Demo 不谈、生产系统绕不开的问题。工具输出可能非常大，例如 npm test 打出几万行日志，grep 搜索整个仓库，构建工具输出长堆栈。Runtime 不能把所有内容原样塞进模型上下文。 正确做法是分两层处理： 第一层是执行层限流。命令执行器记录完整日志到文件或 tra
一个 Agent trace 至少包含： span 至少包含： 不要把 trace 做成聊天 transcript。聊天记录回答'说了什么'，trace 回答'系统做了什么'。
TypeScript 生态里，Zod 常用于运行时校验；模型和协议层常使用 JSON Schema。工程上可以用 Zod 编写工具输入，再转换为 JSON Schema 提供给模型或 MCP。 注意两点。 第一，schema 要表达约束，而不是只写类型。string 太宽，path、command、
一次工具调用 roundtrip 包含六步： 1. Runtime 把工具描述和上下文发给模型。 2. 模型返回 tool call。 3. Runtime 校验工具名和参数。 4. Runtime 判断是否允许执行。 5. Tool Executor 执行工具，得到 result。 6. Runt
coding agent 迟早会执行 shell 命令。读目录、跑测试、安装依赖、生成文件、调用 CLI，都会经过子进程。这里必须谨慎，因为 shell 是副作用入口。 一个最低限度的命令执行器应当具备： 明确的工作目录； 环境变量白名单或脱敏策略； stdout/stderr 流式输出； 超时；
目标：实现可恢复执行。 功能范围： 每轮工具执行前创建 checkpoint； 文件修改保存 patch； 支持恢复文件状态； 支持恢复 session 状态； 进程崩溃后继续 run； 恢复后不重复执行高风险工具。 适合证明： 状态管理； 可恢复执行； 可靠性工程； coding agent 长任
日志不是 trace。日志多半给开发者看，trace 应能还原运行路径。读项目时找： 每次模型调用是否记录； token usage 是否记录； tool call args 是否脱敏； tool result 是否保存； latency 是否可见； 错误是否分类； 用户确认是否入 log； 是否能
你不再靠感觉说 Agent 变好了，而是有数据证明；你能比较两个 prompt 或两个 runtime 策略；一次线上失败能进入回归集；危险行为有硬门禁。到这里，Agent Runtime 已经具备工程组织能信任的反馈机制。
为每次 Agent run 输出 trace JSON，记录： model； prompt tokens； completion tokens； tool name； args； duration； success/failure； retry count； cost estimate； appro
MCP 不是模型协议，也不是 Agent Runtime 的替代品。它解决'工具和上下文如何被发现、描述和调用'。权限、调度、上下文预算、trace、checkpoint 和 eval，仍然是 runtime 的活。 可以这样理解： MCP Server 把能力暴露出来，Runtime 决定这些能力
Eval 不只是测模型，也测 runtime 策略。例如： maxSteps=10 vs maxSteps=20； 工具描述短版 vs 长版； 旧历史保留 4 轮 vs 8 轮； 搜索结果返回 20 条 vs 50 条； 写入前是否强制计划； 工具失败后是否允许自动重试。 每次对比只改一个关键变量。
一次线上失败，如果不能转化为 eval，它就会再次发生。建议流程： 1. 从 trace 中提取用户目标、关键上下文、工具调用和失败结果； 2. 去除 secret 和用户隐私； 3. 固化 workspace fixture； 4. 写 expected behavior； 5. 加入 CI； 6
Agent 失败常被粗暴归结为'模型不行'。这不专业。至少分成五类： 归因 典型现象 模型问题 推理错误、忽视观察结果、重复无效计划 工具问题 工具崩溃、返回格式错、输出不完整 权限问题 策略过严或过松，审批状态丢失 上下文问题 关键文件未注入，历史摘要误导 Runtime 问题 停止条件、重试、并
Agent 能根据用户请求读文件、总结、继续追问或停止。非法工具参数不会让程序崩溃；工具失败会变成模型可理解的 observation；超过最大步数会停止并给出原因。完成这一章，你已经有了 runtime 的胚胎。
一个成熟 runtime 必须支持取消。取消不是'UI 不显示了'，而是从用户操作一路传播到模型请求、工具执行、子进程和资源清理。 这段代码只是开始。上线后的 runtime 需要把 AbortSignal 传给 HTTP client、模型 SDK、工具 executor、子进程管理器。任何一层吞
读开源 Agent 项目，别一上来就钻进细节。本章给一套追主线的方法。 读开源 Agent 项目，最怕两种读法。一种是从 README 兴奋到插件列表，最后只记住产品功能；另一种是一头扎进代码细节，三天后迷失在 UI、配置和历史兼容里。Runtime 工程师读源码，要带着问题读，尤其要追执行链路。
建立 evals/ 目录： 10 个文件编辑任务； 10 个工具调用任务； 10 个失败恢复任务； 每个任务有 fixture、prompt、expected、policy； CI 中运行 mock replay； 成功率低于阈值则失败； 输出报告包含成功率、平均 step、平均 token、失败类
一个 Context Builder 至少接收： 它输出的不只是 messages，还应输出 debug report： debug report 很朴素，却能救命。没有它，你很难解释模型为什么没看见某个文件、为什么忘记用户刚才的限制、为什么把旧错误当成新事实。 debug report 建议保存到
第一类失败是非法参数。模型传了不存在的路径、错误类型、缺字段。处理方式是 schema 校验 + observation 反馈。 第二类失败是工具不存在。模型调用了没注册的工具。处理方式是返回 UNKNOWNTOOL，并把可用工具列表简短提示给模型。 第三类失败是输出过大。处理方式是截断、摘要、引用
读完本章，你应该能清楚解释 Agent、Workflow、Tool、Runtime 的边界；能说出 step、turn、run、trace、session、checkpoint 的区别；能解释一个 Agent 为什么会卡死、乱调工具、爆 token；也能看懂本书后续所有章节围绕的是同一个运行闭环，而
