Sandbox 应该属于 Harness 还是 Runtime？ 这个问题看起来像架构洁癖。 其实不是。 你把 Sandbox 放错位置，后面权限、审批、恢复、trace 都会跟着乱。 我的答案是： Sandbox 的执行环境属于 Harn
《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》电子版系列完整目录，收录系列导读、12 章导读、全部小节与附录链接。
说 Agent '变好了'很容易。证明它变好了，要靠 eval。 Agent 产品很容易陷入'今天试了几个问题，感觉不错'的幻觉。工程系统不能靠感觉上线。Eval Harness 的任务，是把真实任务变成可重复的测试，把 trace 变成回归样本，把 prompt、工具、上下文、权限和 runtime 策略的变化变成可比较的数据。 截至 2026 年 8 月
Agent：根据目标和上下文选择下一步行动的执行体。 Agent Runtime：负责模型调用、工具调用、上下文、权限、状态、观测、恢复、评测和成本治理的运行系统。 Tool Calling：模型输出结构化工具调用，应用执行工具并把结果返回模型的接口能力。 Tool Registry：工具定义、sc
Tool Registry 不是一个 Map<string, Function。它至少保存以下信息： 这些字段不是装饰。description 会影响模型是否选择工具；inputSchema 负责校验；riskLevel 进入权限审批；timeoutMs 进入执行器；outputPolicy 进入上
工具失败不应只有 error: string。至少分为： 类型 例子 Runtime 行为 INVALIDARGUMENTS 参数缺字段、类型错 反馈模型重新调用 NOTFOUND 文件不存在 提示可选路径或要求搜索 PERMISSIONDENIED 用户拒绝或策略拒绝 停止或让模型寻找低风险方案
一次 Agent 任务为什么能烧掉几十次 LLM 调用？ 很多团队第一次算 Agent 成本，会算错。 他们按一次聊天请求算： 这个算法适合普通 Chatbot，不适合 Agent。 Agent 的成本通常长这样： 每一步都可能重新构造上下
工具 schema 有两个读者。模型用它决定怎么调用工具，runtime 用它判断调用是否合法。 以 readfile 为例： 不要把 schema 发给模型后就放心。模型返回的参数必须再次校验。校验失败不该让程序崩溃，应当变成一条 observation： 这很关键。工具参数错了，并不总是任务失败
你应该能解释为什么 Agent 不能直接执行任意 shell；能为 MCP 工具设计权限审批策略；能区分 schema 校验、权限策略和用户确认；能保证恢复执行后不会重复越权。
最后要交一件能拿得出手的东西：一个可展示、可维护、可验收的 runtime feature。 毕业项目不能只是再写一个 demo。它应该证明你理解 Agent Runtime 的工程闭环：需求从真实问题来，方案能解释权衡，代码能集成现有系统，行为可观测，效果可评测，失败可恢复，文档能让别人维护。 本
章节 代码主题 第 1 章 Agent Loop 伪代码 第 2 章 timeout、AbortSignal、子进程执行器 第 3 章 ModelResponse、ToolCall、最小工具 第 4 章 ToolDefinition、风险等级、审批请求 第 5 章 Context Builder 输
一次失败任务可以从 trace 里定位原因；你能区分模型问题、工具问题、权限问题、上下文问题和 runtime 问题；trace 中没有明文 secret；每个失败都能转化为一个潜在 eval case。
实现 Tool Permission Matrix： 对文件路径做 workspace whitelist； 对 shell 命令做风险分类； 对 destructive 操作默认拒绝； 对 write/network/install 操作生成 preview 并请求确认； 所有审批写入 audit
模型供应商的工具调用接口并不完全一致。Runtime 应有自己的 provider adapter： 这样做的好处是： 可切换 OpenAI、Anthropic、本地模型或 Vercel AI SDK； 可统一 stream event； 可把 provider 原生 tool call 转成本地
MCP 让工具接入变容易，也让工具信任问题变复杂。一个 Server 暴露的工具描述不应被 runtime 无条件信任。规范本身也提醒，工具描述等行为注解应被视为不可信，除非来自可信 Server。 因此，MCP 工具审批建议按 Server 信任级别分层： Server 类型 默认策略 官方可信、
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 策略可能成功率略高，但成本翻倍、工具调用
手写一个 100 行 Agent Loop 写 Agent Loop，最容易犯的错，是一上来就接真实模型。 你以为自己在调 runtime，其实你在同时调三件事： 这三件事混在一起，调试会很痛苦。模型没调用工具，你不知道是 prompt 不
