如何做好垂域 Agent：Harness 优化与实践
1. 如何做好垂域 Agent：Harness 优化与实践
[!abstract] 速览
- 平台已有接口和页面，但用户仍要自己串联流程、跨页对齐状态，平台助手补的正是这部分判断与解释。
- Agent = Model + Harness：模型决定下一步，Harness 组织上下文与工具，业务系统守住权限、版本和验收。
- 按接入与运行能力比较五个基座，因多实例部署、检查点恢复和 Python 技术栈，最终选择 Deep Agents。
- 平台在原生 Graph 上补了 Sandbox、三层记忆、Skill、上下文压缩、受限 SubAgent、持久等待与 OBO 身份链。
- 用任务集和指标衡量效果；模型变强后逐项移除多余控制，以回归评测决定保留、修改还是撤销。
“帮我看看昨天的评测为什么没过。”对用户来说，这是一个问题；对 Agent 来说，却是一连串需要自己作出的判断：找哪次任务、看哪个版本、读哪些失败样本，证据不足时继续查，权限不够时停下来。查到一半，用户又补了一句“只看这个项目”，它还得接得住。模型能分析问题，平台也有现成接口，把它们组织成一个好用的 Agent，才是我们做平台助手时花功夫最多的地方。
这篇文章就从这里展开：我们怎样选择 Agent 基座，为什么最终用了 Deep Agents，又怎样在它的原生执行 Graph 上接入项目知识、工作区、身份鉴权和长任务恢复。随着真实任务越跑越多，有些能力需要补，有些流程反而应该撤掉。我们把这些设计和调整的依据写下来，讨论一个垂类 Agent 如何从“能调用工具”，逐步走到“值得交给它做事”。
图 1｜全文主题示意：围绕 Deep Agents 基座补充项目知识、工作区、身份与状态能力，通过评测持续调整，并接入四类应用。工作台与图上的简化 Graph 为视觉示意，执行结构见后文。
1.1. 平台有了能力，为什么还需要平台助手
先看用户在平台里完成一项工作要经过哪些环节。开发方案时，用户要选择模型、确定评测标准，再通过人工和自动评测检查质量。方案通过后，平台用它批量加工数据，并持续巡检每天的生产结果。平台已经为这些环节提供了接口、页面和任务记录，用户可以分别操作。
但要降低使用成本，还得让用户容易地把流程串起来。传统中后台要求操作者先选好流程、填对参数，并知道自己走到了哪一步。用户却可能说不清该用哪个组件、哪个版本；一次失败也可能来自数据、配置、代码或平台依赖，需要跨页面查状态、对照任务记录才能定位。继续加页面，仍然绕不开学习整条链路的成本。
我们希望用户给出目标后，平台能协助选择动作、对齐参数、跟踪状态、解释结果，遇到激活、发布、问题关闭这类关键决策再交给人。平台助手承担的就是这个角色。
1.2. 平台助手要做什么，不做什么
1.2.1. 平台助手、平台与人的分工
以“帮我按这个口径建一个巡检，拿昨天的数据先试跑一下”为例，平台助手负责 判断该走哪一步、参数怎么对齐、结果怎么解释；平台负责 动作本身、权限、版本和状态机；在巡检激活、报告发布、问题关闭这些地方停下来问人。
按照这套分工，用户在巡检工作区里可以直接把“帮我设计计划”“看看昨天的报告为什么有问题”交给平台助手。平台助手理解需求并调用工具，服务端执行动作、检查权限和结果。
1.2.2. 工作流还在，平台助手补的是不确定的部分
平台里大量的数据加工任务仍按工作流运行，输入、算子、分区和产出都有明确约定。这些步骤不需要每次交给模型重新安排。不过，用户在运行前后仍会遇到原流程没有替他回答的问题：该选哪个数据集和版本，口径是否完整，试跑失败是数据没到、配置错了还是代码问题。平台助手主要参与这些判断，并检查报告结论是否有证据支持。
在平台里，Agent 参与方案开发、问题诊断和优化；方案验证通过后，执行平台按冻结版本批量运行，不必为每条记录重新规划和编码。这也对应了工作流与 Agent 的区别：前者沿预先定义的路径执行，后者根据任务和反馈选择下一步。[1]
1.2.3. 分清模型决策、环境执行与业务验收
工具型 Agent 的核心过程并不复杂：拿到目标、约束和已有状态，在预算内反复“准备上下文 → 调用模型 → 校验并执行工具 → 把观察交回模型”。关键在观察——模型不能只在自己的文字里推演成功，它必须看到环境返回的事实。
拿到反馈后，还要分清它证明了什么：
| 层次 | 它回答的问题 | 示例证据 |
|---|---|---|
| 模型决策 | 下一步准备做什么 | 工具调用请求、计划调整 |
| 环境执行 | 这一步实际发生了什么 | 测试结果、任务状态、文件或数据库记录 |
| 业务验收 | 发生的事是否满足原始目标 | 同版本输出的质量评测、覆盖检查、约束核验 |
例如，提交工具返回成功，只能说明平台受理了任务。还要等它运行结束，检查对应版本的输出是否达标，才能回答用户的目标有没有完成。
[!tip] 核心判断
工具返回成功只说明请求被受理；任务是否完成，要看环境返回的事实和同版本产出的验收结果，模型的自述不能当作完成证据。
1.3. 从垂域 Agent 的蓝图，到基座选型
1.3.1. 我们希望建成什么样的 Agent
平台已经有模型评测、数据生产和线上巡检等业务能力。我们要建设的 Agent，需要把这些能力组织成面向目标的操作过程：用户提出需求，Agent 读取项目约定、选择工具、观察结果，遇到耗时任务可以等待，失败后能沿原任务继续，最后交付可检查的结果。
这些任务有不同的发起方式，因此我们不能只围绕一个聊天页面建设 Agent。用户可以向平台助手即时提问，也可以保存定时任务，或按业务批次发起调查巡检。在方案包里，开发者还可以通过 Workflow 调用多个 Agent，安排它们分工协作。
这四类应用都需要调用模型、使用工具和保存状态，适合复用底层能力。与此同时，每次任务的用户、项目、模型和授权范围可能不同，平台必须在执行时确定这些信息。遇到实例退出，还要能从外部存储找回运行状态，而不能只依赖原进程的内存。
图 2｜四类应用的能力分层示意。助手、定时任务与调查巡检由持久执行宿主驱动，方案包 Workflow 编排独立托管的 Agent 节点；两条路径按需接入平台能力，不表示共享同一种 Run 生命周期。Workflow 中的分析、方案与复核仅为编排示例。
我们据此提出五项选型要求：能接入平台模型与业务工具；能按用户和项目组织上下文；能保存会话并恢复中断；能在工具执行前落实授权；能通过轨迹与任务评测持续调整。后面比较基座，都回到这些要求，而不按功能数量打分。
1.3.2. 通用 Agent 基座提供什么
可以用 Agent = Model + Harness 理解分工：模型判断下一步，Harness 组织上下文、调用工具并处理返回结果。[2] 通用基座通常会把其中的重复工作封装起来，但覆盖范围和开放方式不同。
| 能力 | 基座帮助解决什么 | 接入平台后仍要确定什么 |
|---|---|---|
| 模型与工具循环 | 发起模型请求、执行工具、将观察交回模型 | 平台使用哪些模型、工具与预算 |
| 上下文管理 | 装载指令、按需读取材料、压缩长历史 | 项目知识怎样更新，关键资源标识怎样保留 |
| 文件与执行环境 | 提供读写文件、执行命令的入口 | 操作落在哪个 Sandbox，身份与目录怎样隔离 |
| 会话与恢复 | 保存消息或图状态，继续已有会话 | 谁领取执行，外部任务如何查询，副作用如何避免重复 |
| 能力扩展与协作 | 工具、插件或中间件，以及子任务委派 | 哪些扩展按场景生效，子任务拿到多少权限 |
| 观察与人工介入 | 输出执行事件，在指定位置等待确认 | 业务如何验收、哪些动作需要审核 |
基座提供的恢复原语、工具权限和审批入口，可以复用；业务资源归属、版本、幂等和发布条件，仍需要与平台服务对接。选型的重点是这些接口能否适配现有系统。
1.3.3. 五个方案，按接入与运行能力比较
这里比较 Pi、DeepSeek Harness、Codex、Claude Code 和 Deep Agents。它们的产品形态不同：有的从编码工具出发，有的提供运行服务接口，有的直接作为应用内 SDK。Codex 主要看 SDK／App Server 的集成方式，Claude Code 主要看 Claude Agent SDK，Deep Agents 则看 Python SDK。
先比较接入与扩展方式：
| 方案 | 复用形态 | 模型接入 | 工具与执行环境 | 如何扩展执行行为 |
|---|---|---|---|---|
| Pi | TypeScript SDK，可进程内嵌入；也有 CLI、RPC | 多供应商抽象，可增加 provider | 文件、Shell 等工具；工具执行环境可定制 | 扩展注册工具与事件处理，调整上下文或拦截调用；核心较小。[4][5] |
| DeepSeek Harness | 基于 Cordis 的插件运行时；提供 Web、headless、SDK 等入口 | 模型适配器作为插件装配 | 工具注册、执行策略和 Sandbox 后端按服务契约组合 | 模型、会话、工具乃至循环均可替换；需要管理插件依赖与生命周期。[6][7] |
| Codex | 复用编码 Agent，通过 SDK／App Server 接入自己的产品 | 按运行时支持的模型与 provider 配置接入 | 内置文件、命令与工具能力，配合审批和 Sandbox 策略 | 通过会话／轮次协议、工具和配置接入；不等同于应用内任意插入 Python 中间件。[8][9][21] |
| Claude Code | Claude Agent SDK，提供 Python、TypeScript 接口 | 围绕 Claude 模型及其支持的服务渠道 | 复用编码工具，可接自定义工具与 MCP | hooks、工具权限、系统指令、Skill 和子 Agent 配置；沿用 Claude Code 执行机制。[10][11] |
| Deep Agents | Python SDK 装配 LangGraph，可嵌入现有服务 | 通过 LangChain 模型接口接入，平台可在调用边界选择模型 | 文件与命令走 Backend，业务能力通过工具接入 | 中间件钩子、调用包装、Backend 与声明式 SubAgent；便于在同一服务内定制。[14] |
再比较会话、长任务与平台接入工作：
| 方案 | 会话与长上下文 | 中断与恢复的基础 | 子任务组织 | 对平台的接入工作 |
|---|---|---|---|---|
| Pi | JSONL 会话树，支持分支与压缩，保留历史 | 可恢复会话；业务任务的领取、租约和结果核对需要宿主接入 | 默认小核心，子 Agent 等能力通过扩展或包增加 | 适合深度掌控循环；需要接好服务部署、共享存储、用户隔离与治理。[4][5] |
| DeepSeek Harness | 追加式会话事件，模型上下文从日志投影产生 | 持久化由后端实现；已提交日志与未完成工具状态需区分 | 由预设和插件提供委派能力 | 插件化程度高，需要验证持久化、策略和插件组合在业务场景中的行为。[6][7] |
| Codex | Thread／Turn 管理会话，运行时处理长上下文 | 会话恢复与分支通过运行接口提供；部署需保存或迁移相应状态 | 能力取决于运行版本、配置和对外接口 | 适合复用成熟编码执行能力；平台需接入进程／服务生命周期、状态与事件协议。[8][9][21] |
| Claude Code | SDK 会话可继续、恢复或 fork，长上下文由运行时管理 | 跨宿主恢复需要让会话记录可用，文件与外部副作用另行管理 | SDK 可配置子 Agent 的指令与工具 | 适合沿用 Claude Code 工具链；需接好会话存储、执行环境和平台权限。[10][11][22] |
| Deep Agents | LangGraph 消息与检查点，Store 承载长期信息，摘要负责上下文压缩 | 可配置 Checkpointer、interrupt／resume；执行队列与外部任务订阅仍由宿主建设 | 原生 task 委派，可配置角色、工具和上下文 |
与现有 Python 服务和检查点存储衔接较直接；平台重点补执行宿主、身份、工作区和业务工具。[14][15] |
1.3.4. 为什么选择 Deep Agents
选型首先要适合平台已有的服务部署方式。我们用多个实例处理请求，会话不能绑定某一台机器；实例退出后，其他实例要能读到已保存的状态并继续执行。团队已经熟悉 LangGraph 的检查点机制，因此选择 Deep Agents 后，一天就跑通了基础链路。
另一个原因是定制位置比较明确。模型、文件、Skill 和记忆都可以从平台接入；执行前后要增加逻辑，可以使用中间件，而不必重新维护模型与工具循环。后续需要替换模型、调整摘要或收窄子 Agent 能力时，也有对应的接口。
这项选择依赖平台现有的 Python 技术栈、存储和团队经验。Deep Agents 帮我们缩短了接入路径，但任务排队、租约、取消、OBO 身份、Sandbox 路由和业务授权，仍然由平台负责。检查点提供恢复基础，不直接构成完整的分布式 Agent 服务。
1.3.5. Deep Agents 的原生架构
Deep Agents 的入口 create_deep_agent() 负责装配模型、工具、Backend、中间件和子 Agent，最终调用 LangChain 的 create_agent()，得到可以运行的 LangGraph。三个项目各自承担不同层次的职责：[14]
- Deep Agents 组合 Harness 能力：文件工具、长输出卸载、摘要、Skill、记忆注入和委派。
- LangChain 组织 Agent 循环：把模型、工具和中间件组合起来，直到本轮结束。
- LangGraph 执行与保存图状态：提供节点、条件边、检查点、事件流和中断恢复。
我们可以沿这些接口接入平台服务，不必改写整个循环。具体来说，文件读写、历史归档和命令执行交给 Backend，会话图状态存入 Checkpointer，跨会话信息可放入 Store。接入时，我们仍要确定数据存在哪里、以谁的身份访问，以及何时创建和清理。
从一次执行看，几项原生能力分别承担这些工作：
| 原生能力 | 怎样参与执行 | 平台接入时的边界 |
|---|---|---|
| Filesystem | 提供文件读取、修改、搜索，以及长工具输出的文件化处理 | execute 能否执行真实命令，取决于 Backend；文件接口本身不是 Sandbox |
| Skills | 装载目录和描述，让模型按需读取具体方法 | 目录可见不等于拥有业务资源权限 |
| Memory | 将配置的记忆来源加入模型上下文 | 来源初始化、作用域、更新与共享审核需要另行设计 |
| Summarization | 根据上下文压力压缩历史，保留继续执行所需的摘要和消息 | 历史归档能否持久读取，依赖所接 Backend |
| SubAgent | 通过 task 委派子任务，使用子上下文，再返回结果 |
上下文独立不等于文件系统或业务权限自动隔离 |
| 中间件钩子与包装 | 在执行开始、模型前后、工具调用边界增加行为 | 有些钩子成为图节点，调用包装则在节点内部生效 |
这些是我们选择复用的机制。后文讲三层记忆、动态 Skill、受限委派和持久执行时，重点是平台怎样接入与约束它们，而不是把它们再实现一遍。
1.3.6. 原生执行 Graph 长什么样
要看清平台改了什么，先需要一份原生 Graph 作对照。我们使用 Deep Agents 0.7.32，启用 Skill 和 Memory 来源，以可控模型和内存存储构图，没有添加平台中间件，也没有调用真实模型。这个配置导出了 9 个节点、10 条边；换用其他版本或参数，节点和连接关系可能不同。
图 3｜指定版本和配置下的原生架构与 Graph，保留 9 个节点、10 条路由边。下方连接 model 和 tools，分别展开 8 项模型调用包装与 2 项工具调用包装；包装不计入 Graph 节点。Skill 和记忆来自显式启用的能力。
执行从整理工具消息、加载 Skill 与记忆开始，进入模型调用前的准备节点。模型需要工具时转入 tools，工具结果回来后再次进入模型调用；本轮结束则进入收尾。图中也保留了框架允许继续循环的条件分支，实际选择取决于运行状态。
模型调用的包装链中，Filesystem、Skills、Memory 提供模型使用工具和知识所需的上下文，Summarization 处理历史压缩，SubAgent 提供委派指引，另外还有父子通信、缓存和内容适配。工具调用的包装链则围绕文件与 Skill 访问生效。图中逐项列出了这些包装，实际文件与命令由 Backend 承载；task 是委派工具，会运行子 Agent 循环并返回结果。
上述包装处理模型和工具调用，检查点则保存图状态，两者解决的问题不同。实例重启后，可以从检查点继续执行 Graph；但此前启动的外部进程、网络连接，以及已经写入业务系统的结果，还要分别查询和处理。
有了这套原生能力，下一步才是把它接到平台的身份、资源和业务系统上。
1.4. 基座之上，平台补了哪些能力
平台保留了原生执行循环，每次运行时再确定用户、项目、模型、工作区和授权范围。这样，同一份 Graph 可以服务不同任务。下面先看整体接入方式，再展开各项能力。
图 4｜平台定制总图。模型、记忆和工作区按本次可信身份绑定；工具约束与业务授权分别执行。图下的持久执行宿主驱动 Graph，OBO 身份链路见「OBO 身份鉴权」一节。
Thread 是持续会话，Run 是一次执行。 我们用检查点保存图状态，由执行宿主安排排队、领取、租约和恢复。用户在网页上查看进度，实际执行留在服务端，因此关闭网页不会直接取消已受理的 Run。
交互式助手、通用定时任务和 Agent 调查巡检都通过这条链路执行。方案包 Workflow 是另一种接入方式：它负责节点之间的编排，内部 Agent 使用独立托管循环，具体分工见「方案包 Workflow」一节。
再把平台接入后的 Graph 与「原生执行 Graph」一节对照：
图 5｜按职责抽象的定制 Graph 示意，保留执行环节与条件分支。颜色区分原生、平台新增、扩展与配置，图下列出调用包装；平台扩展使用职责标签，不对应具体源码类名或线上部署版本。
图中的长期记忆刷新和运行中补充输入是平台新增环节；Skill 与客户端交互部分接入了平台扩展实现。原生节点保留框架名称，平台扩展按职责标注。模型选择、资源引用和参数校验等在调用包装中生效，不能把它们误当成额外的串行 Graph 节点。
这些定制逻辑会在调用时读取任务配置。发起模型请求前，我们确定实际使用的模型，并按该模型的上下文容量设置摘要预算；操作文件时，Backend 根据可信上下文选择 Sandbox 和路径。这样可以复用同一套 Graph，同时让不同任务使用各自的模型和业务资源。
1.4.1. Sandbox：Agent 的工作空间
平台助手需要运行代码、读取文件，也需要限制这些操作对其他任务的影响。在成本受限的条件下，平台基于 Bubblewrap 实现进程级隔离，并封装成可调度的 Sandbox 资源池。具体取舍已经在 每个 Agent 都需要一个容器吗？轻量进程沙箱的实践中展开。
Runtime 通过 Backend 把文件和命令操作送到与当前用户、项目对应的工作区。Sandbox 按用户和项目复用，会话在其中使用各自的工作目录；目录分开用于组织文件，访问范围仍由工作区权限控制。业务资源的发布、激活等操作，继续由业务服务校验。
1.4.2. 记忆：个人偏好、项目经验与共享约定
“先给结论，再列样本”可以跨项目沿用，“日报按业务发生日统计”却只适用于特定项目。平台把长期记忆分成三层，让平台助手既能延续个人习惯，也能积累项目经验：
| 记忆层次 | 保存什么 | 对 Agent 的帮助 |
|---|---|---|
| 个人记忆 | 跨项目通用的表达、交互、编码偏好 | 换个项目，也不必重新交代工作习惯 |
| 用户项目记忆 | 本人在当前项目中确认的口径、经验和决策 | 新开会话仍能接着已有认识做事，减少重复澄清和反复纠正 |
| 项目共享记忆 | 经管理员审核发布、供项目成员复用的约定 | 不同成员使用平台助手时有共同依据，减少口径不一致和重复摸索 |
用户项目记忆让一次纠正能在后续任务中继续起作用。例如，用户确认“这个项目的日报按业务发生日统计”并要求记住，新开会话做日报时，平台助手就有了可复用的依据；切到另一个项目，这条口径不会跟过去。值得推广的经验可以提交共享建议，经管理员审核后发布，其他成员也能使用。这样，个人积累可以逐步转为团队经验，又不会把某个人的习惯直接变成所有人的默认规则。
图 6｜记忆作用域示意。用户甲的项目经验先在本人范围内复用，经审核发布后才供项目成员使用；项目 A 的口径不带入项目 B，个人偏好则可以跟随用户。示例口径用于说明设计，不代表真实业务规定。
保存时，要留下适用条件和依据。 平台助手从用户的交代和纠正中提取可复用的内容，确认后通过专门的记忆入口保存，并记录来源和版本。用户明确纠正同一个主题时，就更新原条目，避免后续同时读到新旧说法。筛选时也要排除只对这次任务有用的信息，例如“这次先抽 100 条”、当前任务进度，或模型提出但用户尚未认可的方案。
使用时，先确定范围，再提供上下文。 每次任务开始，服务端根据登录用户和项目读取这三层记忆，在固定预算内提供给模型。[20] 个人偏好可以跨项目延续，项目经验随项目切换，共享约定只在所属项目内使用。记忆帮助平台助手理解背景，当前任务是否完成、某个版本是否已经发布，仍要查询业务服务；旧口径与当前事实冲突时，也需要先核对。
对照 Codex、Claude Code 和 Hermes 的设计，我们更关注它们怎样控制进入上下文的内容，以及怎样让经验持续更新：
- Codex 把抽取和整合分成两步。 先从符合条件的历史会话提取候选，再在后台合并为经验手册和精简摘要，保留会话来源；没有值得复用的信息时，可以不生成记忆。[23]
- Claude Code 把索引和详情分开。 启动时加载精简的记忆索引，具体内容放在主题文件中；它还区分用户偏好、反馈纠正、项目事项和资料引用，便于保存不同用途的信息。[24]
- Hermes 用小容量常驻记忆搭配历史检索。 常用事实直接进入提示，细节需要时回查会话。后台整理尝试修改或删除已有记忆时，会将变更暂存审核，避免一次自动整理悄悄覆盖旧经验。[25]
对照这些做法，我们需要分别考虑 谁能使用、保存什么、何时读取。现有三层作用域已经区分了使用范围；在此基础上，还可以按偏好、纠正、项目决策和资料入口整理条目，再决定哪些内容常驻、哪些按任务读取。比如，平台助手可以始终带上用户偏好的报告顺序，排查某类评测时再读取相关经验，需要核对证据时才回查完整历史。
1.4.3. Skill：平台知识怎么组织，怎么优化
Skill 记录平台的操作方法：什么时候使用、需要哪些输入、失败后怎么恢复。模型先看到目录和简短描述，需要时再读取正文。平台按职责把 Skill 分成四类：
| 类别 | 例子 | 负责什么 |
|---|---|---|
| 端到端编排 | 方案开发编排 | 决定走哪几个阶段、在阶段之间交接 |
| 领域能力 | 数据集管理、方案包开发、扩展开发、质量评测、批量生产 | 各自负责一个业务能力，不重复别人的可执行流程 |
| 调查与诊断 | 线上巡检、日志分析、报告整理、成本估算 | 从现象定位到证据，产出可复核的结论 |
| 接入与规范 | 文档检索、外部 Agent 接入、平台规范、能力目录等 | 查询外部知识、接入别的 Agent、约束写法 |
一个操作流程只在一个 Skill 中维护。编排 Skill 引用领域 Skill，避免在多个地方重复描述命令顺序和验收条件；否则一处更新、另一处没改，模型就会读到相互矛盾的做法。
优化 Skill 时，先用同一份输入和配置复现失败。模型不知道某个 Action 要求先冻结版本，就补充操作说明；知道要查状态却没有查询入口，就补工具。修改后重跑原任务，再检查其他任务有没有退步，才能判断改动是否有效。
复现失败之后，也不一定能直接从代码或日志里找到答案。有些信息只有业务方知道，例如覆盖率和成本冲突时优先哪个、上游在节假日是否会延迟、审核口径有哪些例外。遇到这类缺口，要先找到可靠来源并确认，再写入 Skill。
Coding Agent 可以辅助读取失败轨迹、修改 Skill 并重跑任务。维护中我们主要检查两件事：
- 内容是否仍然适用。 只保留当前可执行的流程，删除废弃命令和迁移说明，变更历史交给版本管理。
- 文档能否对应真实能力。 Skill 中的 Action 必须能在注册表中找到，引用的文件必须随包发布，这些关系由检查程序验证。
Skill 能说明应该怎样操作，但有些检查必须由程序执行，不能只靠模型遵循说明。因此，我们将操作方法与执行约束分开维护：
| 内容 | 放在哪里 | 原因 |
|---|---|---|
| 开发步骤、错误恢复方法、示例 | Skill 与按需读取的 references | 随场景演进，供模型理解和选择 |
| 当前用户、项目和执行范围 | 可信宿主上下文 | 不能由模型自行声明 |
| 动作参数与读写权限 | 工具入口与业务服务 | 每次执行都要按真实身份核验 |
| 不可变版本、准入与发布条件 | 业务服务 | 需要对所有调用入口一致生效 |
| 超时、取消、执行与重试预算 | 执行宿主 | 需要在模型之外生效 |
以方案开发为例，Skill 描述怎样准备工作区、实现代码、检查样本、同步提交、发起试跑并复核结果。调用落到工具入口时，宿主提供当前用户与项目身份，执行系统据此限制子任务能力，业务服务再检查目标资源、版本与发布条件。模型选择的步骤可以变，这些检查每次都要执行。
业务样本、网页和日志可能夹带诱导模型操作的指令。因此，工具入口要根据宿主提供的身份核验权限和参数，不能接受模型自行声明的身份或授权。Skill 提供操作指引，执行系统负责让这些检查在每次调用时生效。
1.4.4. 上下文：保留判断所需的信息
一段长对话里，模型可能读过多份文档、提交过几个任务，还拿到过很长的日志。为了继续对话，我们需要压缩这些历史，但摘要必须留下后续操作所需的信息。若压缩后只剩“评测已经发起”，平台助手就无法查询结果：它还需要任务 ID、对应版本和查询入口。
这里的设计需要同时解决三个问题：当前模型能容纳多少历史，压缩以后能不能找回原文，后续操作还能不能定位原任务。平台沿用 Deep Agents 的摘要算法，在模型配置、归档和资源引用上补充适配。
图 7｜原生摘要与平台补充机制的关系。摘要有效、归档成功是提交压缩结果的条件，不表示两者并发执行；任一失败时保留原消息。资源引用单独保存，当前业务状态仍需重新查询。
首先，不同用户可能在同一套 Graph 中使用不同模型，各模型能容纳的上下文长度并不相同。因此，我们按本次模型配置计算压缩阈值和历史保留量，而不是一直沿用构图时的值。
其次，历史归档必须能读回来。平台按 Thread 解析历史路径，通过工作区文件接口传输原文，并检查查找、读取和上传结果。归档失败，或摘要为空、返回失败占位文本时，不提交这次压缩结果。原消息仍保留在检查点中，由执行宿主按预算处理失败和重试。
最后，我们从成功的工具结果中提取任务 ID、版本和查询入口，单独存入图状态，供后续模型调用使用。即使摘要只剩“已经发起评测”，平台助手也能凭这些引用查到原任务。不过，引用只能帮助定位资源，任务的当前状态仍须重新查询。
是否需要重新读取，取决于信息会不会在执行中变化。带版本的 Skill 和工具契约，在版本适用的前提下可以于本次 Run 内复用；任务是否完成、能否发布则可能随时变化，必须查询业务服务。至于跨任务使用的偏好和经验，另存为「记忆」一节所述的长期记忆，不与本次任务状态混在一起。
上下文预算还需要覆盖最终请求。若先统计历史长度，后面再加入 Skill、记忆、工具定义和资源引用，实际发送的内容就可能超出预算。设计中间件顺序时，需要把这些输入一起纳入预算，并为输出留出空间；仅压缩聊天记录还不够。
1.4.5. SubAgent：按任务分工，按能力授权
一个任务要读几十个文件、跑几轮调研时，可以把边界清楚的部分委派给子 Agent。子任务使用独立上下文，完成后把结论和证据交回主 Agent，减少主会话需要持续携带的材料。
平台按职责配置四类角色：
| 角色 | 负责什么 |
|---|---|
| 通用执行角色 | 处理通用子任务 |
| 只读调研角色 | 检索工作区和 Skill |
| 数据处理角色 | 在当前工作区处理文件、分析数据 |
| 代码复核角色 | 只读审查源码和已有测试证据，不执行命令、不改文件 |
代码复核角色只能说明审查发现了什么，不能代替实际运行测试。
为了让子 Agent 在分工后仍遵守原任务的授权，我们限定了三件事：
- 能力只收窄，不放宽。 子 Agent 的工具、Skill、文件权限都是父级能力的子集，配置里不能声明父级没有的东西。
- 身份和审批不重写。 子 Agent 继承当前用户、项目、工作区和审批规则，只接受“角色 + 指令 + 能力”三样定制。
- 记忆只能建议，不能写。 子 Agent 不持有记忆管理工具，有价值的结论回传给父 Agent 决定是否沉淀。
默认的通用执行角色也由平台配置，不能绕开上述限制。我们既在角色说明中告诉模型应该做什么，也在工具和文件权限中限制它能做什么。例如，一个只读角色必须真正拿不到写入工具，不能只在提示词里写“不要修改文件”。
是否委派，取决于子任务边界是否清楚、是否需要隔离上下文。边界不清、需要共享同一份会话状态、或者只是简单一步的，留在主会话里更省事——委派的开销在上下文重建和信息交接上。
1.4.6. 长任务与会话恢复
一次评测或批量处理可能运行几十分钟，人工确认还可能跨到第二个工作日。执行系统需要保存已经做过什么、还在等什么，以及收到结果后从哪里继续。
Agent 先提交外部任务，拿到真实任务标识，再登记等待。宿主保存图的检查点和等待订阅，释放 Agent 执行槽位。后台检测器查询原任务，拿到结束状态和结果后，将它们送回原来的等待工具调用，模型才继续分析或执行后续步骤。
图 8｜持久等待的正常时序。查询超时不等于业务失败，停止监测也不等于取消远端任务。
不同任务的查询方式由适配层处理。平台 Action 声明任务标识、查询入口和结束状态；外部服务由 Skill 提供只查询原任务的脚本，并返回约定状态。检测器复用同一套检查、退避、结果保存和唤醒机制。
等待期间不调用模型，但后台仍要查询和保存结果，因此还会产生计算与存储开销。检测器所在实例退出后，其他实例可以在租约过期后接手；接手时可能再次查询同一任务，所以查询命令必须只读且幂等。
这也限定了业务接入的条件：外部任务必须有可持续查询的标识和状态接口。只有异步调用接口，却无法在进程退出后找回原任务，就不能支持这里的持久等待。
提交与等待还要分开，因为恢复检查点时会重新进入中断节点，中断前的代码可能再次执行。[15] 如果提交也放在这个节点里，就有重复创建任务的风险。因此，我们先通过独立工具调用提交任务并保存回执，再进入只查询原任务的等待节点。
若提交请求已经发出，却没有收到明确结果，也要先查询原任务或核对幂等记录，再按业务服务的规则恢复。此外，任务结束只解决外部等待；同一轮若还在等人工确认，仍须取得确认后才能继续。
几个容易混淆的情况需要分别处理：
| 情况 | 处理方式 |
|---|---|
| 查询超时 | 在预算内退避重试，不据此判断业务任务失败 |
| 停止监测 | 如需取消远端任务，另行调用业务取消接口并确认结果 |
| 命令在路由阶段被明确拒绝，尚未执行 | 重新连接工作区后，可以重试 |
| 命令已发出，但执行结果未知 | 先查状态或结果记录，不能直接重放 |
[!warning] 恢复边界
Sandbox 快照不包含进程内存、打开的连接和后台进程。长脚本需要留下任务标识、日志和输出产物；进程消失后，要先判断哪些步骤已经产生副作用，只有确认可重入或幂等的部分才能重跑。
1.4.7. 多个入口，共用一套执行能力
网页、CLI、A2A 和 MCP 面向不同使用方式，复用的能力也有所不同：
| 入口 | 谁来用 | 形态 | 不重复实现的部分 |
|---|---|---|---|
| 网页 | 平台用户 | 事件流 + 持久化任务 | 循环、工具、Skill、记忆 |
| CLI | 终端与本地宿主 | CLI 扩展，或独立二进制 | 同一套动作与 Skill 目录 |
| A2A | 其他 Agent | 标准 Agent Card + 任务 | 治理、证据、产物 |
| MCP | 已接入 MCP 的客户端 | 持久任务工具集 | 任务、鉴权 |
远端入口完成身份认证和协议转换，再把请求交给持久执行宿主。网页和 A2A 对话有保留的交互执行槽位，避免后台长任务占满后，新对话一直排队。CLI 在本地宿主中复用动作与 Skill，其执行环境需要满足相应能力要求，不能把它与服务端执行完全等同。
跨 Agent 调用也沿用当前用户身份。访问外部数据服务时使用短期凭证，凭证不写入持久化正文；接入个人模型服务时，授权、成本与配额跟随个人账号。更换入口或模型来源，不会扩大用户在平台上的操作权限。
1.4.8. OBO 身份鉴权：Agent 代表谁执行
[!note] 术语：OBO（On-Behalf-Of）
用户通过 Agent 操作资源时，应沿用原有账号的权限。OBO 让 Agent 代表已经认证的用户发起操作：模型只负责提出动作，可信接入层确定真实操作人，下游服务再检查该用户是否有权执行。
平台把这件事分成入口认证、平台内授权和下游身份委托三部分。
图 9｜通用身份与授权边界示意。入口认证、可信执行上下文与下游身份委托是不同环节，不是把同一个 Token 原样转发到所有服务；图中省略具体凭证传递实现。
入口先验证身份。 外部客户端携带 OBO Token 时，接入层检查签名、签发方、有效期及受众，再解析真实操作人；浏览器走已认证登录入口。用户和项目等信息进入可信执行上下文，模型提交的工具参数不能覆盖 user_id、认证头或确认凭据。恢复执行和子 Agent 委派继续沿用所属任务的身份，不重新让模型声明。
平台动作再检查权限。 Platform Action 从可信上下文取得操作人、项目与运行标识，服务端检查项目权限、资源归属以及当前动作是否被授权。调用方自行填写的用户名不能证明身份；身份必须来自已验证的调用链。即使用户已经登录，资源版本、幂等记录和发布条件仍要分别检查；人工确认也不能替代权限授权。
访问下游服务时，使用该服务认可的委托凭证。 可信接入层确认用户授权后，为目标服务取得短期、限定范围的凭证，由受控执行层按目标协议携带，下游独立验证身份和权限。模型只提出动作与业务参数，不负责签发或选择身份。签名材料不交给 Skill，凭证不放进模型上下文、工具参数、命令正文或共享日志。
通过这条身份链路，用户可以从网页或外部 Agent 发起请求，下游仍按真实身份授权。即使模型选对了数据源，也要等权限检查通过后才能读取；绑定过期、证明无效或下游拒绝授权时，应停止调用并返回原因，不能改用管理员身份继续。
这套委托方式还要求下游配合验证。未接入相应身份协议的服务，不会自动获得识别和校验委托身份的能力。
1.5. 评测：怎么知道平台助手真的有用
功能接通之后，同一个任务有时能完成，有时反复查资料，有时漏掉验证，有时在错误版本上继续做。仅凭几次对话的印象，很难判断改动到底有没有效果。
为了比较改动前后的表现，我们单独建设评测系统，由它准备环境、重复执行任务并按标准评分；Agent 本身仍在待测的 Harness 中运行。这样测到的是模型、Harness 与环境共同作用的结果。即使模型不变，更换工具实现、上下文策略或预算，也可能改变结果。[3]
还要区分 Agent 任务评测与业务方案评测。前者看是否按要求交付资源、证据和结论，后者看方案处理数据的准确率、覆盖率和成本。例如用户要求诊断失败原因，Agent 准确解释“方案为何未达标”就可能完成任务；用户要求改出一个达标方案，同样的回答就还不够。验收必须回到原始目标。
一份诊断任务的验收记录可以这样组织：
[!note] 验收记录示意
- 原始目标：定位一次评测失败的原因。
- 已执行：读取对应版本的报告和失败样本。
- 交付检查：原因解释是否有样本支持，引用是否属于同一版本。
- 未验证项：修改后的方案尚未试跑。
- 判断：证据充分时可以通过诊断任务验收；还不能声称修复后的方案已经达标。
1.5.1. 任务集要覆盖正常路径，也要覆盖应该停下的情况
垂类 Agent 可以从现有人工验收任务、真实失败和高影响场景开始构建回归集。每个任务记录环境前置条件、允许操作、预期产物和判定规则，再逐步扩充。
| 任务类型 | 要验证的行为 | 不能只检查什么 |
|---|---|---|
| 信息充分的方案开发 | 完成实现、试跑与交付，版本一致 | 回答里有没有“完成”两个字 |
| 输入缺失或标准冲突 | 提出必要问题，保留已完成工作 | 是否仍能强行返回结果 |
| 参数错误与可恢复失败 | 根据错误修正，沿原资源继续 | 工具调用次数够不够多 |
| 提交超时、结果未知 | 查询已有任务，避免重复副作用 | 最后有没有某个成功任务 |
| 长等待与执行重建 | 恢复原任务，不重做已完成提交 | 会话有没有继续输出文字 |
| 越权或发布条件不满足 | 拒绝越界动作，说明实际阻塞 | 是否遵循一条固定调用轨迹 |
验收时，只要方法、权限和结果满足要求，就应允许 Agent 走不同的有效路径，不能因为它换了检索顺序就判失败。但要判断两条路径的表现是否可比，运行条件必须能够复现。因此，每次试验都要保留模型标识、提示词、Skill 与工具版本、输入快照、依赖配置和预算，并使用独立工作区。
留档时还要区分任务配置和实际模型请求。前者记录用户确认的目标、授权与版本，后者记录一次调用实际使用的模型、工具及上下文。在排查中间件组合问题时，需要检查完成全部装配后的请求；只保留装配前的配置，可能看不到后来注入的内容。
评测还必须覆盖用户实际使用的执行环境。OpenAI 把插件测试分成直接工具测试、独立循环和实际产品 Harness 三层，因为同一组工具在不同环境中，可能加载不同指令、受到不同权限限制，甚至无法被模型调用。[16] 对平台来说，工具契约测试通过后，我们还要在实际宿主中验证版本传递、长任务等待与恢复。 简化循环里的高分，不能代替交付环境中的验收。
1.5.2. 指标把完成、可靠性与资源消耗分开看
最基础的指标是任务成功率：满足该任务全部验收条件的试验次数，除以全部试验次数。计算总体成功率时，基础设施故障和超时也算失败，因为用户确实没有拿到结果。为定位问题，可以另外统计依赖正常时的表现，但要注明排除了哪些任务。
成功率之外，再看几类指标：
| 指标 | 记录什么 |
|---|---|
| 错误完成声明率 | 宣称完成的试验中，产物或业务状态未通过验收的比例 |
| 越权与重复副作用 | 发生的事件及影响，单独列出 |
| 人工介入与恢复 | 哪些任务需要接管，哪些失败可以恢复 |
| 耗时与费用 | 完成一次任务的总开销，包括失败和重试 |
统计费用时，还要计入子 Agent 和摘要调用，否则会低估完成任务的总成本。如果请求已经发出，却没有拿到完整用量回执，就将这笔费用记为待确认，不能按零处理。
一次成功还不足以说明稳定性，因此同一任务需要重复运行。这里要区分两个指标：pass@k 关注 k 次尝试中至少成功一次，pass^k 关注 k 次全部成功；前者看多次尝试能否找到成功结果，后者看重复交付是否稳定。[3]
如果产品允许尝试多次，还必须能从结果中选出真正满足要求的那一次，并计入全部尝试的费用。涉及写入的任务更要先保证幂等，否则一次评测中的重复尝试就可能创建多份业务资源。
1.5.3. 从失败轨迹定位问题，再决定改哪一层
下面这张表是我们日常的排查顺序，不是线上故障占比统计。
| 现象 | 先找什么证据 | 优先尝试的改动 |
|---|---|---|
| 一直查文档，迟迟不进入实现 | 是否缺关键输入，是否重复读取相同材料 | 缩短入口材料，补充必要事实与下一步 |
| 反复猜参数、重复创建资源 | 当前工具契约、错误码、已有资源的标识 | 改善参数定义、恢复指引与资源引用 |
| 看完代码就宣布完成 | 是否缺真实测试和同版本结果 | 明确验证入口与证据要求，保留服务端准入 |
| 测试过了，业务仍不达标 | 样本覆盖、规则分歧、评审偏差 | 修订业务方案或校准评测标准 |
| 长对话后用错版本 | 摘要、资源引用、服务端当前记录 | 单独保存资源标识与版本，必要时重新核对 |
| 超时重试启动了两个任务 | 请求标识、提交记录、结果未知时的处理方式 | 修复幂等与查询恢复路径 |
重试也需要先定位失败阶段。例如模型已经返回结果，只是用量记录写入失败，下一步应尝试恢复结果和补记回执；直接再请求一次模型，会增加调用成本。工具提交结果未知时，则要先查原任务。两种情况都抛出了异常，恢复动作却不同，不能统一处理成“再跑一遍”。这是设计恢复策略时需要验证的边界。
每轮改动尽量只验证一个主要假设。怀疑反复读资料导致超时，就先调整材料组织，再比较完成质量、读取次数和耗时。模型、工具和流程同时变化时，可以观察整体效果，但难以判断收益分别来自哪里。
补上一项机制后，也要检查它是否带来新的问题。例如，提醒模型避免重复尝试，可能减少无效调用，也可能打断必要的探索；增加强制阶段，可能补齐漏项，也可能增加成本。因此，我们先在开发任务集定位问题，再用未参与调参的任务集和既有回归集验证，最后决定是否保留。
进展看门狗的职责也据此作了限制。目前它只观察调用并提示重复请求，不据此判断任务已经完成。是否完成仍要检查实际产物与验收条件。
1.6. 模型变强之后，重新调整 Harness
模型升级后，我们开始回头检查已有的阶段判断和提醒：哪些仍然有用，哪些模型已经能自己完成。如果中间件还强制它按旧模型需要的步骤走，新能力就可能发挥不出来。平台做过一次这样的调整。
1.6.1. 哪些流程控制还需要保留
判断一项流程控制是否仍然必要，我们看三个问题：
- 模型现在能不能自己做到？ 先看实际执行记录中，它是否还需要这项提醒。已经能稳定完成的，可以尝试移除对应建议，再用回归验证。
- 它挡不挡模型的新能力？ 判断时要比较模型正在做的事与系统给出的提示。例如模型已经开始测试，按关键词判断阶段的逻辑却仍要求它继续开发，就可能把任务带回已经完成的步骤。
- 删掉之后有没有执行层兜底？ 要先区分流程建议和必须遵守的业务约束。若移除提示后某项约束就不再生效，应先在执行层补上校验。
1.6.2. 删了什么，为什么能删
最近我们从模型循环中移除了四项控制：
| 移除的控制 | 原本负责什么 | 问题出在哪 |
|---|---|---|
| 开发阶段判断 | 按关键词判断当前阶段，并注入阶段目标 | 模型已开始测试，系统却继续提示它开发 |
| 开发场景上下文组织 | 为开发场景单独拼装上下文 | 与通用上下文叠加，重复装载旧材料 |
| 条件性上下文重建 | 在特定条件下重建上下文 | 重建时机由固定条件决定，与真实状态不一致 |
| 巡检阶段控制 | 控制巡检流程的阶段推进 | 与开发共用入口时，两条链路的阶段互相干扰 |
较早的模型需要这些提示才能按步骤推进，但在后续运行中，我们发现了阶段误判、重复加载材料和流程互相干扰的问题。模型升级后已经能自行安排开发与验证，我们便逐项移除这些控制，再用原有任务检查是否退步。回归结果没有下降，才保留改动；出现退步，就查清原机制还有哪项作用不可缺少。
1.6.3. 保留执行约束，按场景配置能力
移除阶段判断后，动作范围校验仍然保留。工具入口根据真实身份和本次任务的授权范围，检查目标资源与参数；提交结果未知时，保留提交记录，按业务接口的幂等规则查询或恢复。这些规则不依赖模型选择了哪条路径。
Skill 刷新、工作区管理、进度观察和空响应恢复也继续保留，它们为模型提供可用的执行环境。判断是否需要一项能力，要看它解决的问题是否仍然存在。
另一个调整方向是按场景装配。例如只读代码审查需要文件读取和证据核对，通常不需要网页交互或报告发布工具。可以先配置角色所需的能力，再检查是否还加载了无关的指令和中间件。这是减少干扰、控制上下文开销的方法，效果仍要通过任务评测验证。
图 10｜Harness 职责调整示意。两侧均保留“模型判断 → 工具执行 → 结果反馈”循环，移除的是外围四项控制；运行支持与平台约束继续生效，改动通过回归评测后才保留。图中“防重复提交”表示幂等约束的一个应用，不代表单项改动的实测收益。
1.6.4. 效果
在模型升级与 Harness 调整之后，我们重跑了改动前评测所用的同一批内部任务：任务成功率有所提升，单任务耗时 减少约 40%。
这些结果来自上述内部任务。由于任务构成、样本量和统计时间窗还需补齐，目前只能据此描述这一轮的变化，不能推断其他任务集也有同样表现；换模型或换任务集后需要重测。
从执行记录看，移除中间件后，每轮需要加载的上下文更少，调用前后的判断步骤也减少了，这可能解释一部分耗时下降。不过，同期也更换了模型，不能把成功率和耗时的变化全部归因于移除中间件。要分清两者各自的贡献，还需固定模型，分别运行改动前后两版 Harness；这一步我们尚未完成。
1.6.5. 用对照实验检验设计判断
LangChain 在 2026 年 2 月固定模型、调整 Harness，将 Terminal-Bench 2.0 得分从 52.8% 提升到 66.5%，改动集中在验证、环境上下文和循环行为。[17] 这不能外推成我们平台的收益，但提供了一种实验方式：固定模型和任务集，比较 Harness 调整前后的表现。
Anthropic 在 2026 年 3 月的一轮实验中移除了 sprint 分段和 context reset，也尝试移除 planner，随后又将其加回；evaluator 则从每轮评分改为末尾单次。[13] 这些取舍说明，模型升级后需要重新检验每个组件承担的职责，尝试移除也可能证明它仍然必要。
Meta 对薄编排器与独立子 Agent 的讨论，以及 OpenAI 对环境和反馈循环的实践，也可以作为架构分工的参考。[18][19] 这些案例各有模型、任务和环境前提，具体采用哪种设计，仍要回到自己的任务集验证。
有些机制失效后不会报错，只是每轮多装载一段材料、多走一次无效判断。因此，升级时除了检查接口兼容，还要比较任务成功率、调用轨迹和耗时，再决定保留、修改或移除哪些机制。
1.7. 基于 Agent Runtime 接入四类应用
前面这些能力让我们可以在不同应用中复用 Agent，而不必每接一个场景就重写模型和工具循环。交互式助手、通用定时任务和 Agent 调查巡检共用 Deep Agents 构建入口，由同一个持久执行宿主驱动。方案包开发者则可以通过 Workflow 调用 Agent，将需要模型判断的步骤嵌入业务流程。
接入时，各应用仍要提供目标、Skill、允许使用的工具和结果要求，并确定何时触发、怎样编排、如何验收。下面分别介绍这四种用法。
| 应用 | 如何触发 | 应用自己维护的规则 | 交付内容 |
|---|---|---|---|
| 平台助手 | 用户提问与追问 | 会话连续性、资源引用、关键动作确认 | 回答、产物与未验证项 |
| 通用定时任务 | 时间或事件触发 | 定义版本、重复投递、在途任务处理 | 结构化结果与关联会话 |
| Agent 调查巡检 | 巡检计划与业务批次 | 业务窗口、来源、试跑激活与报告验收 | 调查报告、证据与问题记录 |
| 方案包 Workflow | 流程运行到 Agent 节点 | 节点依赖、输入输出、结果传递与失败处理 | 节点产物及多 Agent 协作结果 |
1.7.1. 平台助手：从用户目标开始
用户说“帮我分析昨天的评测为什么没通过”，平台助手读取当前项目和已有资源，按需加载 Skill，再决定查任务状态、看样本，还是请用户补充判断标准。用户可以从业务问题开始，不必先选工具、找参数。
在这个过程中，平台助手先从记忆中读取项目约定，再按 Skill 的说明调用平台工具。如果查询依赖一个尚未结束的外部任务，就交给执行宿主等待，结果返回后再继续分析。
分析完成后，用户还可能追问“刚才哪组样本问题最多”。这时必须知道“刚才”指的是哪次评测，原会话保存的资源引用就能帮助平台助手继续查询。用户若要求修改方案，再进入开发、试跑和验证；交付时说明所用版本、结果位置和尚未验证的内容，发布或激活仍由人确认。
1.7.2. 通用定时任务：把反复提出的目标保存下来
“每天上午 9 点汇总昨天的评测结果，列出失败任务和需要处理的问题。”这样的目标可以保存为定时任务，由调度器按时发起一次 Run。
定时任务会反复执行，因此要能查清每次使用了哪份配置。保存任务时，我们冻结指令、模型、Skill 版本、工具契约和参数；触发后，再将 Run 绑定到对应版本。用户后来修改任务，不会改变已经受理的执行。
配置固定后，还要在每次执行时检查授权是否仍然有效。通用任务只允许执行已获授权的非管理员只读动作，并继续核验当前身份和项目权限。
为避免重试创建多份任务，调度器给每次触发生成稳定标识，重复投递时复用已有执行记录。若同一任务尚未跑完，新的触发记为跳过；用户暂停计划后，不再触发新任务，但已受理的执行继续使用原配置。停机期间错过的时点则不逐次补跑。
任务完成后，结果保存在会话中，由平台服务发送通知。通知和任务执行分开重试：通知发送失败时，只重新投递，不重新运行任务。
1.7.3. 线上巡检任务：在共享执行上增加业务验收
线上巡检在周期运行之外，还要明确业务窗口、数据来源、抽样方法、结论证据和问题处置方式。定时触发可以复用调度能力，这些业务要求则要由巡检系统维护。
保存巡检计划时，先固定方法、参数、数据来源的授权和报告要求。用户用当前版本完成试跑并确认后，才能激活计划。正式执行时，巡检协调器创建批次并关联调查会话，再由 Runtime 驱动 Agent 准备数据、开展调查，处理其中的等待与恢复。
调查完成还不等于报告可以交付。适配层要先校验报告结构和证据引用，巡检系统再保存报告、问题记录及后续处置状态。
验收时还要看报告是否覆盖了要求、结论是否有样本支持，仅仅取数成功是不够的。这与「评测」一节强调的原则一致：执行成功之后，仍须核对原始目标。这里接入 Runtime 的是需要模型调查与判断的部分；固定检查和方案包托管巡检仍沿用原有链路。
1.7.4. 方案包 Workflow：把 Agent 作为节点，组织分工协作
方案包中的一些步骤可以预先确定，例如读取数据、调用评测和保存结果；另一些步骤需要根据输入作判断，例如分析失败原因、提出修改建议。这些环节可以通过 Workflow 调用 Agent，让固定流程与模型判断共同完成任务。
当一个任务需要多种角色时，Workflow 可以组织多个 Agent 分工。例如，分析 Agent 根据失败样本给出原因和证据，方案 Agent 据此提出修改建议，复核 Agent 再检查建议是否覆盖原问题。前一个节点的产物成为后一个节点的输入，协作关系由 Workflow 明确表达。这个例子说明的是一种编排方式，具体角色和节点应随任务配置。
图 11｜Workflow 与 Agent 的两层分工。上层是节点依赖与产物交接，下层展开一个 Agent 节点的内部循环；虚线表示局部展开，不是新增执行分支。角色与流程为示例，不表示固定的线上配置。
这里需要分清两层职责：Workflow 管节点之间的依赖与结果流转，Agent Runtime 管节点内部的模型判断与工具执行。 节点内仍可根据反馈调整步骤；何时进入下一个节点、失败后重试还是结束、什么结果算通过，则由流程定义和验收规则决定。方案包内部 Agent 保留独立托管循环，不能把这一入口等同于前三类应用的持久 Run 链路。
它与「SubAgent」一节的分工也不同：主 Agent 在执行中委派子任务，适合临时拆分调查或分析；Workflow 预先定义角色、依赖和交付关系，适合需要重复运行、检查中间产物的业务流程。两种方式可以结合，但节点之间应传递明确的结果与证据，避免依靠一段不断增长的聊天记录交接任务。
四类应用的交付要求不同，因此回归任务也要分别补充。测试平台助手时检查交付与追问，测试定时任务时检查触发、重试和版本绑定，测试巡检时核对来源、覆盖范围与报告证据，测试 Workflow 时检查节点输入输出、Agent 之间的结果传递和失败恢复。这样既能通过公共回归集检查 Runtime，也能通过各应用的任务集验证业务结果。
1.8. 结语
做平台助手的过程中，我们逐渐明确了三方的分工：模型根据反馈选择下一步，Runtime 提供上下文和工具、处理等待与恢复，业务系统检查资源和操作规则。排查一次失败时，也按这个分工检查：是模型判断错了、执行中断了，还是产物没有达到业务要求。
模型升级之后，我们还会重新检查这些分工。有些步骤模型已经能自己安排，就尝试移除相应控制；有些失败来自工具或反馈不足，就补上缺失的能力。每次调整都保留平台对权限、版本和幂等的检查，再通过评测确认任务是否更容易完成、失败后是否更容易恢复，以及总开销是否合理。
把这些共用能力放进 Runtime 后，我们可以继续接入平台助手、定时任务、线上巡检和方案包 Workflow，并通过 Workflow 组织多个 Agent 协作。接入新任务或更换模型时，也就有了两份可以复用的基础：已有实现，以及验证这些实现的任务集和执行记录。我们据此判断哪里够用、哪里需要改，再继续迭代。
1.9. 参考资料
原有外部资料核对日期：2026-10-20；记忆资料补充于 2026-10-27，Runtime 分层与上下文内容补充于 2026-10-28；基座选型、原生 Graph、OBO 及 Codex、Claude Code、Hermes 记忆设计补充于 2026-10-29。部分链接为持续更新的官方文档。
- [1] Anthropic：Building effective agents，2024-12-19。用于区分工作流与动态 Agent。
- [2] LangChain：The Anatomy of an Agent Harness，2026-03-10。
- [3] Anthropic：Demystifying evals for AI agents，2026-01-09。
- [4] Pi：当前官方仓库 与 Coding Agent。
- [5] Pi：How Pi works 与 Compaction Reference。
- [6] DeepSeek：Harness 官方介绍 与 官方仓库。
- [7] DeepSeek Harness：Architecture、Session、Tool execution pipeline 与 Agent presets。
- [8] OpenAI：Unrolling the Codex agent loop、Codex 开源仓库 与 Sandboxing。
- [9] OpenAI：Codex as a platform: build on the open agent harness，2026-08-19。
- [10] Anthropic：How Claude Code works。
- [11] Anthropic：Agent SDK overview。
- [12] Anthropic：Effective harnesses for long-running agents，2025-11-26。
- [13] Anthropic：Harness design for long-running application development，2026-03-24。删除 sprint 与 context reset、planner 与 evaluator 的取舍，以及“组件对应模型假设”的判断方法。
- [14] LangChain：Deep Agents overview、定制入口 与 官方架构说明。架构分工于 2026-10-28 经 Context7 补充核对。
- [15] LangGraph：Interrupts 与 Persistence。
- [16] OpenAI Cookbook：Harness-aware evaluation of plugins，2026-09-23。
- [17] LangChain：Improving Deep Agents with harness engineering，2026-02-17。固定模型、只改 Harness 的对照实验。
- [18] Meta Engineering：The Thin Orchestrator，2026-10-19。薄编排器与上下文隔离的专家子 Agent。
- [19] OpenAI：Harness engineering: leveraging Codex in an agent-first world，2026-02-11。把工程师的工作从写代码转向设计环境与反馈循环。
- [20] LangGraph：Add memory，2026-10-27 经 Context7 核对。用于说明按用户组织跨会话记忆，以及从持久存储读取内容供模型使用的方式。
- [21] OpenAI：Codex App Server 官方实现说明，2026-10-29 补充核对。用于会话、轮次和集成协议比较。
- [22] Anthropic：Agent SDK 会话管理，2026-10-29 补充核对。用于继续、恢复、fork 和跨宿主会话恢复的边界。
- [23] Codex：Memories、记忆管线说明 与 第一阶段抽取模板，2026-10-29 核对。用于说明后台抽取、整合、分层产物与无新增价值时不写入。
- [24] Claude Code：Memory，2026-10-29 经 Context7 核对官方文档。用于说明记忆索引、主题文件及内容类型。
- [25] Hermes Agent：Persistent Memory 与 记忆工具实现，2026-10-29 核对。用于说明有界常驻记忆、会话检索及后台改删审核。