Anthropic Agent 运行架构系列解读：从执行循环到可替换的 session、harness 与 sandbox
原文一：Building agents with the Claude Agent SDK（2025-09-29，原 Engineering 链接现已迁移至 Claude Blog）
原文二：Harness design for long-running application development（2026-03-24）
原文三：Scaling Managed Agents: Decoupling the brain from the hands（2026-04-08）
实践项目：PPT Master
前置文章已经讨论过一个具体问题：当任务跨越多个上下文窗口时，如何用特性清单、进度文件、Git 历史和验证机制让下一次会话接得上。
本文不再重复那套初始化 Agent 与编码 Agent 的实验，而是把视角向上下两端扩展：
单次会话内，Agent 如何工作？
↓
复杂长任务，Harness 如何组织多个角色与反馈循环？
↓
运行时间继续增长，平台如何让 session、harness、sandbox 各自可恢复和替换？三篇文章合起来回答的中心问题是：一个 Agent 系统如何从基础执行循环，演进为长任务编排，再演进为具有稳定接口的运行架构。
一、证据范围与概念边界
本文把三类内容分开处理：
| 内容 | 证据边界 |
|---|---|
| Anthropic 机制 | 仅依据三篇官方原文，保留其发布日期和实验背景 |
| PPT Master 现状 | 依据 2026-08-12 核对的仓库快照 4e6ecbc |
| 对照结论 | 是从两组事实得到的分析，不等于两个系统具有相同实现 |
这里还需要先区分三个容易混用的词：
| 层次 | 本文含义 |
|---|---|
| Agent loop | 模型在一次运行中收集上下文、采取行动、验证结果并继续迭代 |
| Harness | 调用模型、路由工具、维护任务节奏和反馈回路的运行框架 |
| Managed runtime | 把会话状态、运行框架和执行环境做成可独立恢复与替换的服务接口 |
同一个产品可以同时包含三层，但三层不是同义词。把一份步骤文档称为 harness，不能由此推导出它已经拥有持久 session、容器调度或凭据隔离。
二、第一层：Claude Agent SDK 给出基础执行循环
Claude Agent SDK 文章把通用 Agent 的基础循环概括为：
Gather context → Take action → Verify work → Repeat这四步看起来简单，但分别要求系统提供不同能力。
1. Gather context：上下文不只来自初始 Prompt
文章首先把文件系统视为可检索的上下文空间。面对日志或大型文件，Agent 可以使用 grep、tail 等工具按需读取，而不必把完整文件一次性放入窗口。
在此基础上，文章又区分了三种扩展手段：
- Agentic search：让 Agent 自己判断查什么、读哪些片段；
- Semantic search：通过分块、向量化和相似度检索加速发现；
- Subagents：让独立上下文并行探索，只把高信号结果返回主 Agent。
长运行还会遇到上下文增长。SDK 提供 compaction，把较早消息压缩成摘要，让当前循环可以继续。
这里的核心不是某一种检索技术，而是：Agent 必须能够主动取得和更新上下文，不能只消费用户开场时提供的 Prompt。
2. Take action：工具、脚本与代码是执行面
文章把工具视为 Agent 最主要的行动入口。工具定义在上下文中非常显眼，因此工具数量、名称和返回内容会直接影响 Agent 的选择。
同时，SDK 不把行动限制为预先注册的细粒度 API。Bash 和代码生成可以把复杂操作表达成可组合、可复用的程序；MCP 则提供连接外部服务的标准接口。
这意味着一个通用 Agent 往往同时有两种执行方式：
| 方式 | 适合的问题 |
|---|---|
| 显式工具 | 高频、边界清晰、需要稳定契约的动作 |
| Bash / 生成代码 | 组合、转换、批处理和临时计算 |
3. Verify work：反馈必须能作用于下一轮
文章列出规则反馈、视觉反馈和模型评审三种方式。它并没有把三者视为等价：明确规则通常更稳定，视觉反馈适合界面任务，另一个模型作评审则有额外成本和可靠性限制。
验证的价值不在于最后出一份报告，而在于把失败变成下一轮可操作的输入：
行动结果
→ 明确指出哪条规则失败、哪里与目标不一致
→ Agent 修正
→ 再验证因此，基础循环真正闭合的条件不是“Agent 调用了工具”，而是 环境能给出具体反馈，Agent 能据此继续修正。
三、第二层：Harness 把循环扩展成长任务编排
Harness design for long-running application development不是对基础循环的重复，而是在回答另一件事：当任务规模超过单个 Agent 稳定完成的范围时，哪些额外角色和制品真正有用？
1. 从“自己做、自己夸”中分离评估
原文先在前端设计任务上观察到，生成者评价自己的工作时容易过度宽松。作者把生成与评估拆开，并为评估器提供四组标准：设计质量、原创性、工艺和功能性。
这里有两个关键动作：
- 把“好不好看”转成可以逐项检查的设计原则；
- 让评估者实际操作页面、截图和检查功能，而不是只看生成者的自述。
评估结果再返回生成者，形成多轮迭代。原文也明确承认，这类循环会显著增加墙钟时间和成本。
2. 从生成—评估扩展为规划—生成—评估
用于完整应用开发时，原文形成了三个角色：
| 角色 | 主要职责 | 防止的失败 |
|---|---|---|
| Planner | 把短需求展开成产品规格，但不过早锁死实现细节 | 生成者直接开工、范围过窄 |
| Generator | 按规格实现，并在交接前自检 | 实现过程失去目标 |
| Evaluator | 按可测试契约运行应用、发现偏差并反馈 | 生成者对自身结果过度乐观 |
角色之间通过文件传递规格、契约和反馈。这些文件不是旁观记录，而是后续角色工作的输入。
这与前置文章讨论的“跨会话制品”有共同点，但研究重点已经变化：前置文章解决 下一会话如何接手；新文章进一步研究 规划和评估是否应成为独立角色，以及这些角色在当前模型上是否仍然值得成本。
3. Harness 不是越复杂越好
这篇文章最重要的校准发生在模型升级之后。
早期 Sonnet 4.5 的长任务容易出现 context anxiety，因此原有 harness 使用 context reset。作者在 Opus 4.5 上发现该现象明显减弱，于是删除 reset，改用连续会话和 SDK 自动 compaction。
之后 Opus 4.6 能够更长时间保持连贯，作者又移除了 sprint 结构，但保留 Planner 和 Evaluator，因为前者仍能防止范围不足，后者在能力边缘任务上仍能发现真实缺口。
由此得到的不是“始终使用三 Agent”，而是一条更稳健的原则：
原文递进后的结论
Harness 中的每个组件都隐含了一个“模型自己做不到”的假设。模型变化后，应逐项重新验证这些假设，而不是永久保留旧脚手架。
四、第三层：Managed Agents 把运行部件做成稳定接口
Scaling Managed Agents继续向系统层推进。它关注的已不是 Planner 应不应该存在，而是：不论 Harness 以后怎么变，长周期任务的状态和执行环境怎样保持可恢复。
1. 耦合容器为什么会变成“宠物”
早期实现把 session、harness 和 sandbox 放在同一个容器中。直接文件操作很方便，但三者具有相同的故障命运：
- 容器失败，session 可能一起丢失；
- harness 卡住、事件流断开和容器离线从外部看起来相似；
- 为了调试，需要进入可能同时持有用户数据的容器；
- harness 默认执行资源与自己位于同一个环境，难以连接客户自己的基础设施。
问题不只是“容器不稳定”，而是 状态、决策循环和执行环境没有独立生命周期。
2. session、harness、sandbox 的明确分工
Managed Agents 把三者虚拟化为独立组件：
| 组件 | 官方定义中的职责 |
|---|---|
| session | 保存发生过什么的追加式事件日志，位于模型上下文之外 |
| harness | 调用模型，并把工具调用路由到相应基础设施 |
| sandbox | 运行代码、编辑文件和连接实际资源的执行环境 |
文章使用了一组很小的接口说明这种解耦：执行环境可通过 execute 调用和 provision 重建；harness 可通过 wake 恢复，再从 session 取得事件；运行期间用 emitEvent 持续写入状态。
这些接口的价值在于，任何一层失败都不必拖着另外两层一起失败。
3. session 不等于当前上下文窗口
这是全文最容易被忽略的边界。
模型上下文中的 compaction、trimming 或记忆文件都需要决定保留什么；session 则负责耐久保存事件。Harness 可以按位置读取 session 的某一段，再决定如何转换并装入当前模型窗口。
因此两者的关系是：
Durable session：尽可能保留可恢复的历史
↓ 由 harness 选择、裁剪、重组
Model context：本轮推理实际看到的内容把这两层分开后，未来更换上下文工程策略，不需要改变底层状态的保存方式。
4. “脑”和“手”解耦还带来安全边界
文章把模型及 harness 称为 brain，把 sandbox 和工具称为 hands。解耦后，生成代码运行的 sandbox 无法接触平台凭据。Git 认证随资源 provisioning 绑定，初始化时完成 clone 并接入本地 remote，Agent 不直接处理 token；MCP 则通过 session token 调用专用代理，由代理从 vault 取得真实 OAuth 凭据。
这是 Managed Agents 自身的托管架构事实。它不能因为某个本地工作流也调用了 shell，就被类推到任何使用 Claude 的项目上。
五、把三篇文章放到一张递进图里
三篇文章不是三个互斥方案，而是在不同高度上解决问题：
| 高度 | 核心问题 | 主要机制 | 成功条件 |
|---|---|---|---|
| Agent loop | 这一轮怎么做成 | 上下文、工具、行动、反馈 | 能根据环境反馈继续修正 |
| Task harness | 一个复杂任务怎么持续做对 | 规划、生成、评估、制品交接 | 额外角色确实改善当前模型的失败 |
| Managed runtime | 运行部件怎么独立恢复和替换 | session、harness、sandbox 接口 | 状态、决策循环和执行环境不共用故障命运 |
由此可以得到一个判断顺序：
- 先闭合单 Agent 的收集—行动—验证循环；
- 只有真实任务暴露稳定失败时，才增加 Planner、Evaluator 或跨会话制品；
- 只有需要多租户、长周期恢复、异构执行环境或平台级凭据隔离时，才进入 Managed runtime 问题。
跳过第一步直接建设第三步，只会得到昂贵但没有可靠任务循环的平台。
六、PPT Master 的当前实现：它位于哪一层
以下事实核对基于 PPT Master 4e6ecbc 的 AGENTS.md、Skill 入口、Generate 工作流、Resume Execute和技术设计。
1. 它已经闭合了面向演示文稿的基础循环
Default Generate 可以与 Agent SDK 的基础循环做功能对应：
| Agent SDK 循环 | PPT Master Default Generate |
|---|---|
| Gather context | 转换并读取来源，必要时补充事实研究；读取模板、图片元数据和规划制品 |
| Take action | 主 Agent 顺序编写 svg_output/，脚本处理资源、后处理并导出 PPTX |
| Verify work | 首页质量门、最终 SVG 检查、PPTX package/resource postflight |
| Repeat | 修复拥有问题的源制品，只重跑受影响的步骤和下游步骤 |
这是一种有效对应，但不意味着 PPT Master 自己实现了 Claude Agent SDK。实际的模型循环、文件工具和命令执行仍由运行它的 Agent 宿主提供。
2. Default 的角色是同一主 Agent 的指令作用域
PPT Master 将 Strategist、Image_Generator 和 Executor 保持在同一主 Agent 内。它们通过按需加载不同参考文件切换职责，不是三个独立进程，也不是三个各自持有 session 的 Agent。
这种设计有意保护跨页面连续性：页面设计依赖完整规划、实际取得的资源和前页节奏，所以 SVG 页面必须由当前主 Agent 串行完成，不能批量委派给多个 worker。
因此，PPT Master 与三角色 Harness 的相似处是 职责分离；不同处是 没有把核心角色部署为相互独立的 Agent 实例。
3. split 提供的是制品化交接，不是持久 session 服务
Default 默认连续执行。只有 design_spec.md §I 记录 generation_mode: split 时，规划会话才在 Step 5 后停止，并要求用户在新会话中输入项目路径继续。
新会话的 resume-execute 会验证并读取：
- 完整
design_spec.md； - 完整
spec_lock.md； - §X 声明最终/逐字旁白时必需的
notes/total.md； - lock 条件引用的图片和模板；
- 通过共享目录解析的活动 Chart/Table SVG；
- 中途恢复时的最新 SVG 与当前图片元数据。
来源材料不是统一的 Step 1 sanity-check 项；进入执行后，主 Agent 只在核对具体 Fact ID、事实、引文或数据时读取相关段落。
这些真实制品替代上一会话的确认对话和资源获取历史。validation/workflow.log 被明确界定为冷的命令/结果审计日志，恢复时不重放，也不是规划状态。
这与前置《Effective harnesses》解读一致：PPT Master 用明确制品让新上下文重新建立执行状态。
但它没有 Managed Agents 的追加式 session event log，也没有 wake(sessionId) 一类会话恢复接口。用户开启的新聊天由宿主管理；PPT Master 恢复的是项目执行上下文，不是原聊天会话本身。
4. 质量检查器不是独立 Evaluator Agent
svg_quality_checker.py 和导出 postflight 是确定性工具，负责报告合同、资源和包结构问题；它们不拥有页面清单，也不替 Agent 修改页面。
PPT Master 还有显式触发的 visual-review，但它不是每次运行默认存在的第三个评估角色。现行流程更接近：
Strategist 规划
→ Executor 实现
→ 确定性检查器给出反馈
→ Executor 修复这正好符合 Harness 文章的成本原则：已能由规则可靠判断的问题，不需要默认增加一个昂贵的模型评估器。
5. Quick 把常规设计决策只保留在活动上下文中
Quick 省略 Strategist、Confirm UI、design_spec.md、spec_lock.md 和替代规划制品。当前 Agent 在活动上下文中完成内容、页面、风格和资源决策，然后直接编写 SVG。
技术设计明确说明，这些决策在活动上下文丢失后无法重建或恢复；Quick 必须重新开始。
这不是缺陷，而是 Quick 的已知交换：用更少的制品与交互换取更短路径。它也说明 可恢复性来自被选择性持久化的状态，而不是“Agent 应该记得”。
七、不能类比过去的四个边界
为了避免把 Anthropic 的托管能力写成 PPT Master 自带能力，需要明确以下差异：
| Managed Agents 能力 | PPT Master 当前事实 |
|---|---|
| Durable session | 没有追加式会话服务；只有项目制品和冷审计日志 |
| Replaceable harness service | 有工作流规则与恢复入口，但不是可部署、可重启的无状态运行服务 |
| Provisioned sandbox | 没有容器/VM 调度或执行环境 provisioning；使用宿主提供的工具环境 |
| Credential broker | 没有凭据 vault、Git/MCP 代理或 session-scoped token 机制 |
同理，IDE 是否隔离、文件系统可访问到哪里、网络是否放行，都由运行 PPT Master 的宿主决定，不由 skills/ppt-master/ 内的 Markdown 工作流决定。
对照边界
PPT Master 可以规范 Agent 应该按什么顺序行动，却不能仅凭工作流文本限制进程在操作系统层实际能够访问什么。
八、从三篇文章得到的采用判断
1. 已经值得保留：制品所有权和恢复入口
PPT Master 已把来源、规划、执行 SVG、派生预览、验证报告和导出物分开，并在失败恢复矩阵中声明从哪个拥有者修复、从哪一步继续。
这与 Managed Agents 的解耦思想方向一致：不同状态应有明确所有者和失败边界。但当前以文件和工作流表达已经足够，不需要为形式相似再包装一套服务接口。
2. 不应默认引入：独立 Planner / Evaluator Agent
Harness 文章已经说明，角色是否有价值取决于当前模型与任务难度。PPT Master 的 Strategist 已承担独立规划职责，规则检查器已覆盖大量可确定问题，核心页面生成又依赖共享上下文。
在没有可复现质量缺口前，把三种角色全部进程化只会增加成本、交接和状态漂移。
3. 不应内建：自制 session 服务与 sandbox
Managed Agents 的接口服务于托管、多环境和长周期基础设施。PPT Master 当前是 workflow/skill 包，不是 Agent 托管服务。
除非未来出现以下真实需求，否则不需要实现类似组件：
- 多个无状态 runner 必须接手同一任务；
- 一个任务需要在多个隔离执行环境间迁移；
- 平台要代理用户凭据并支持独立撤销；
- 项目制品不足以诊断或恢复真实失败。
这符合 KISS 和 YAGNI：先保持当前文件制品边界，等运行形态真正变化后再设计服务接口。
4. 值得持续检查：Harness 假设是否已经过时
PPT Master 的多阶段规则同样编码了模型能力假设。随着宿主和模型改善，应以真实任务反馈检查：
- 某个角色切换是否仍然减少漂移；
- 某个阻塞门是否仍然防止真实错误；
- 某个重复读取是否仍然提供净收益；
- 某个可选模型评估是否值得成本。
“曾经有效”不是永久保留复杂度的充分理由。
九、我的理解：稳定的不是 Harness 内容，而是责任接口
三篇文章连起来后，最重要的变化不是 Agent 数量从一个变成三个，也不是容器从一个变成多个，而是系统逐步把不同责任说清楚：
- Agent loop 负责在环境反馈中推进任务；
- Harness 负责组织循环、角色、制品和验证节奏；
- session 负责耐久状态，sandbox 负责执行边界；
- Managed runtime 允许三者独立失败、恢复和演进。
核心判断
长期稳定的通常不是某一版 Prompt、某一种角色编排或某一次上下文压缩策略，而是“状态由谁保存、循环由谁驱动、动作在哪里执行”这组责任接口。
对 PPT Master 而言，当前最准确的定位是：它在宿主 Agent 之上提供领域化 Harness 政策和项目制品契约，但不提供宿主的 session、权限、安全隔离或托管执行环境。
这个边界既不贬低现有工作流，也不夸大它的运行能力。只有先把层次分清，未来是否需要更强的恢复、调度或隔离，才会成为一个可以基于真实需求讨论的问题。