Agent 迟早要接外部工具。本章讨论怎么接，以及怎么避免被某个供应商或协议绑死。 Agent Runtime 不能永远只使用本地写死的工具。它需要连接数据库、浏览器、设计工具、代码托管平台、内部系统、文档库和企业权限系统。MCP 的出现，正是为了解决 LLM 应用与外部数据、工具之间缺少统一连接方
长任务跑久了，问题会变成一句话：有限的 context window 里，到底该放什么？ Agent Runtime 的上下文不是聊天记录的简单拼接。它是一份给模型的'案卷'：用户意图、当前目标、最近进展、关键文件、工具结果、约束、计划、失败记录、可用工具。案卷太薄，模型会失忆；案卷太厚，会浪费成本
写一个 miniagent： 支持 listfiles； 支持 readfile； 支持 shellreadonly； 支持最多 10 轮工具调用； 支持流式输出 runtime event； 非法 tool args 能被拦截并反馈给模型； 每次 run 输出一份简单 JSON trace。 任务
第三章 最小 Agent Loop：3.6 一个 miniagent 的目录 建议项目结构： 不要急着做框架。先让每个模块的职责一眼能看懂。等你知道重复在哪里，再抽象。
选三个项目：Cline、Codex CLI、aider。分别画出一次用户请求如何走到工具调用的链路图。你不需要读完整个仓库，但要回答： 1. 用户输入进入哪里？ 2. 模型调用在哪里发生？ 3. 工具在哪里注册？ 4. 工具调用结果如何回到模型？ 5. 权限审批或确认在哪里发生？ 6. 日志或 tr
Agent eval 天生有波动。处理 flaky 的方法： runtime 单元测试使用 mock model； 真实模型 eval 多跑几次取统计； 用行为断言代替字面匹配； 把'必须不发生'的危险行为单独作为硬门禁； 把人工 judge 与程序化断言分开； 对不稳定 case 标记 quara
说 Agent '变好了'很容易。证明它变好了，要靠 eval。 Agent 产品很容易陷入'今天试了几个问题，感觉不错'的幻觉。工程系统不能靠感觉上线。Eval Harness 要把真实任务变成可重复的测试，把 trace 变成回归样本，把 prompt、工具和 runtime 策略的变化变成可比
入门阶段可先用本地 JSONL： 每个 run 写入： 后续再接 OpenTelemetry、LangSmith 或自建 UI。先把语义记对，再追求漂亮 dashboard。
Agent 出错后，最怕只剩一句'模型没做好'。这一章讲怎么查清楚。 没有 trace 的 Agent Runtime，就像没有采访记录的新闻调查。出错后只能凭印象复盘：模型好像看过文件，好像调用过工具，好像测试失败了，好像用户批准过。工程系统不能靠'好像'。 OpenTelemetry 把 tra
恢复流程要保守： 1. 找到最新完整 checkpoint； 2. 校验 workspace 状态； 3. 恢复 message history 和 run state； 4. 检查最后一个 tool call 是否已完成； 5. 对不可重复工具禁止自动重放； 6. 给模型注入恢复说明； 7. 从下
很多人学会 async/await 后，会误以为异步编程已经结束。对普通 Web API 来说，这通常够用；对 Agent Runtime 来说，不够。 Runtime 面对的不是一次请求一次响应，而是长时间过程： 模型流式吐出 token 和 tool call delta； shell 命令持续
真实模型有随机性、网络波动和供应商变化。Eval 需要两层： 第一层用 deterministic mock model 测 runtime 逻辑。它按照脚本返回固定 tool calls，用来验证 schema 校验、权限、checkpoint、trace、停止条件。 第二层用真实模型测端到端能力
现在可以动手了：把模型、工具和观察结果接成一个受控循环。 最小 Agent Loop 是本书第一座桥。过了这座桥，你就不再只是调用一次模型，而是在写一个会观察、会行动、会停止的运行系统。这个系统可以非常小，但边界必须正确。
长任务一定会中断。问题是：失败后怎么继续，而不是重来？ Agent Runtime 一旦进入真实工程任务，就会遇到长运行：改多个文件、跑多轮测试、安装依赖、查文档、等待用户确认。长运行必然遇到中断。浏览器刷新、进程崩溃、网络超时、模型失败、用户临时离开，都可能打断 run。如果没有 checkpoi
本书统一使用以下术语。 turn 是一次用户与系统的交互轮次。用户提出一个任务，是一个 turn 的开始。 step 是 runtime 在一个 turn 内的一次模型决策或工具执行推进。一次 turn 可以有很多 step。 run 是一次完整执行，从收到用户请求到最终回答、失败或取消。长任务中，
幂等性是恢复执行的核心词。一个工具如果重复执行不会造成额外副作用，就更容易恢复。例如读文件幂等，搜索幂等，纯计算幂等。写文件如果基于相同 base hash 应用同一个 patch，也可以设计成近似幂等。发邮件、支付、删除远程资源通常不幂等。 工具定义中应声明： 这会直接影响 resume 策略。
第八章 Checkpoint、Resume、Rollback：8.3 gitbased checkpoint 另一种做法是借助 git。每个 step 或关键写入点创建临时 commit、stash、worktree 或 patch 文件。 gitbased 的优点是成熟、可审计、适合代码项目。缺点
第八章 Checkpoint、Resume、Rollback：8.2 patchbased checkpoint 对 coding agent 来说，文件系统状态是第一等公民。最轻量的做法是 patchbased checkpoint：每次工具执行前后记录 diff。 优点： 存储小； 容易审计；
写 Agent Runtime 之前，先补一门不太体面的课：异步任务和进程控制。 Agent Runtime 表面上是在调用模型，实际上是在管理一串可能很慢、会失败、有副作用、需要取消的异步任务。模型请求会流式返回，shell 命令会持续输出，文件系统可能被修改，用户可能中途按下取消，工具可能超时，
Agent Runtime Engineering v0.1 发布 今天把这个项目正式按 v0.1 的方式放出来。 仓库地址： https://github.com/zeeklog/agentruntimeengineering 先说清楚：
