说 Agent '变好了'很容易。证明它变好了，要靠 eval。 Agent 产品很容易陷入'今天试了几个问题，感觉不错'的幻觉。工程系统不能靠感觉上线。Eval Harness 的任务，是把真实任务变成可重复的测试，把 trace 变成回归样本，把 prompt、工具、上下文、权限和 runtime 策略的变化变成可比较的数据。 截至 2026 年 8 月
Agent：根据目标和上下文选择下一步行动的执行体。 Agent Runtime：负责模型调用、工具调用、上下文、权限、状态、观测、恢复、评测和成本治理的运行系统。 Tool Calling：模型输出结构化工具调用，应用执行工具并把结果返回模型的接口能力。 Tool Registry：工具定义、sc
一次 Agent 任务为什么能烧掉几十次 LLM 调用？ 很多团队第一次算 Agent 成本，会算错。 他们按一次聊天请求算： 这个算法适合普通 Chatbot，不适合 Agent。 Agent 的成本通常长这样： 每一步都可能重新构造上下
最后要交一件能拿得出手的东西：一个可展示、可维护、可验收的 runtime feature。 毕业项目不能只是再写一个 demo。它应该证明你理解 Agent Runtime 的工程闭环：需求从真实问题来，方案能解释权衡，代码能集成现有系统，行为可观测，效果可评测，失败可恢复，文档能让别人维护。 本
一次失败任务可以从 trace 里定位原因；你能区分模型问题、工具问题、权限问题、上下文问题和 runtime 问题；trace 中没有明文 secret；每个失败都能转化为一个潜在 eval case。
模型供应商的工具调用接口并不完全一致。Runtime 应有自己的 provider adapter： 这样做的好处是： 可切换 OpenAI、Anthropic、本地模型或 Vercel AI SDK； 可统一 stream event； 可把 provider 原生 tool call 转成本地
token budget 不只是技术限制，也是产品预算。一次 run 里，token 影响延迟、成本和可靠性。越长的上下文越不一定越好，因为模型注意力会被稀释，缓存命中也可能下降。 可以把上下文分为六层： 1. 系统与开发者指令； 2. 用户当前意图； 3. 近期完整对话； 4. 当前任务状态和计划
建立 evals/ 目录： 10 个文件编辑任务； 10 个工具调用任务； 10 个失败恢复任务； 每个任务有 fixture、prompt、expected、policy； CI 中运行 mock replay； 成功率低于阈值则失败； 输出报告包含成功率、平均 step、平均 token、失败类
第八章 Checkpoint、Resume、Rollback：8.2 patchbased checkpoint 对 coding agent 来说，文件系统状态是第一等公民。最轻量的做法是 patchbased checkpoint：每次工具执行前后记录 diff。 优点： 存储小； 容易审计；
成功率重要，但不够。还要看： 平均 step 数； 平均 tool call 数； 平均 token； 平均耗时； 权限请求次数； 用户拒绝后是否停止； 相同错误重复次数； 输出是否引用证据； 文件 diff 是否最小； 回滚是否成功。 一个 runtime 策略可能成功率略高，但成本翻倍、工具调用
工具结果、日志、文件片段进入模型上下文前，应经过 secret scanning。至少检查： API key； OAuth token； 私钥； .env； cloud credential； 数据库连接串； 内部域名和个人信息。 发现 secret 后，不要把原文注入模型。可以替换成 REDACT
回滚不丢对话上下文；恢复不重复执行高风险工具；文件状态和 session 状态能对应到同一个 checkpoint；trace 可以说明恢复从哪一步开始。做到这里，runtime 才从脚本接近系统。
生产级 Agent 上线前必须检查的 50 件事 前面我发布了 Production Agent Checklist v1.0。 那是一份模块级清单。 今天这篇更像上线门禁。 如果一个 Agent 要进入真实用户环境，尤其是能读文件、写文件
用户审批不能只当 UI 事件。对 runtime 来说，它是一条系统事实，每次都应写入 audit log： 恢复执行时，这些记录尤其重要。已经被拒绝的危险工具，不能因为进程重启就再次自动执行。已经批准的一次性操作，也不应无限期复用授权。
长任务跑久了，问题会变成一句话：有限的 context window 里，到底该放什么？ Agent Runtime 的上下文不是聊天记录的简单拼接。它更像一份交给模型的案卷：用户当前目标、必须遵守的约束、最近进展、关键文件、工具观察、失败记录、可用工具、当前计划。案卷太薄，模型会失忆；案卷太厚，成本上升，关键事实还可能被噪声挤掉。 上下文工程不是塞更多东西
读开源 Agent 项目，别一上来就钻进细节。本章给一套追主线的方法。 读开源 Agent 项目，最怕两种读法。一种是从 README 兴奋到插件列表，最后只记住产品功能；另一种是一头扎进代码细节，三天后迷失在 UI、配置和历史兼容里。Runtime 工程师读源码，要带着问题读，尤其要追执行链路。
coding agent 需要理解仓库。直接把所有文件塞进上下文不可行，所以需要 repo map。 repo map 可以包含： 目录树； 关键入口文件； 导出的函数、类、类型； import/export 关系； 最近修改文件； 测试文件与源文件对应关系； README、配置文件、路由文件摘要。
术语是否统一：Runtime、Agent Loop、tool call、observation、checkpoint、trace、eval。 所有'截至 20260812'的事实是否需要更新。 图片中的文字是否清晰准确。 代码是否按目标 Node.js 版本跑通。 权限、安全、隐私段落是否避免绝对化
招募 50 位 Early Reader 这本书写到这里，我想招募 50 位 Early Reader。 书名： 仓库： https://github.com/zeeklog/agentruntimeengineering 先说清楚。 我不
Agent Loop、Harness、Runtime 到底是什么关系？ 这几年 Agent 讨论里，有几个词特别容易搅在一起：Agent Loop、Harness、Runtime。 很多文章会这么写： 或者反过来： 再或者： 我不太赞同。
