Agent Harness 原语分类

雪踏乌云2.8万 曝光 · 125 收藏

大模型包含推理、生成和语言理解能力，但仅有模型还不能构成一个能够长期工作的 Agent。

让模型真正进入现实环境、持续完成任务的，是模型周围的 Agent Harness。

Harness 可以被理解为一套运行时系统：它负责组织上下文、提供工具、执行动作、保存状态、控制权限、观察结果，并在模型与真实世界之间形成反馈循环。

为了设计和比较不同 Agent Harness，我们需要一套相对完整的原语分类。这里首先要区分两个概念：

  • Agent 能力是系统最终表现出来的行为，例如规划、记忆、执行代码和自我验证。
  • Harness 原语是实现这些能力的基础机制，例如文件系统、工具协议、状态存储、审批策略和测试钩子。同一种能力通常由多个原语组合产生。例如，“长期自主执行”不是某一个工具带来的，而是持久化状态、目标管理、上下文压缩、故障恢复、规划和验证共同作用的结果。

通过分析 Codex 源码，本文从 Agent 与信息、环境、人类及其他 Agent 的关系出发，将 Agent Harness 原语划分为八类：

  1. 感知原语
  2. 认知与编排原语
  3. 记忆与上下文原语
  4. 行动原语
  5. 协作原语
  6. 治理原语
  7. 持续执行原语
  8. 验证与交付原语这八类原语共同构成一个生产级 Agent 的完整能力闭环。

一、感知原语：让 Agent 看见真实世界

模型只能直接处理当前上下文中的信息。现实世界中的文件、网页、日志、界面和运行状态，必须先经过 Harness 转换为模型能够读取的上下文。

感知原语负责回答：

Agent 如何知道现在发生了什么？

典型原语包括：

  • 文件和目录读取
  • 代码与文本搜索
  • Web Search 和网页读取
  • 浏览器 DOM、无障碍树和页面状态
  • 图像、截图和视觉输入
  • 日志、测试输出和终端输出
  • 数据库、API 和企业数据连接器
  • 文件监听与环境状态更新
  • 当前分支、工作区和进程状态检测文件系统是最基础的感知界面，但不是唯一界面。随着 Agent 从编码扩展到通用计算机操作，浏览器、截图、GUI、结构化文档和外部系统查询都会成为重要感知原语。感知能力还涉及信息可信度。对话历史只能提供线索，当前工作区、测试结果和外部系统状态才可能是事实来源。因此，一个可靠的 Harness 不只是把信息交给模型，还要标明信息的来源、时间、权限和权威性。在 Codex 中，文件系统、Shell 输出、Web Search、Browser、Screenshot、MCP、Connectors 和 World State 都属于这一层。

二、认知与编排原语：组织模型的推理过程

推理能力主要来自模型，但 Harness 可以决定模型在什么条件下推理、获得哪些提示，以及如何把复杂目标组织成可执行过程。

认知与编排原语负责回答：

Agent 应该如何思考、分解和选择下一步？

典型原语包括：

  • System Prompt 和开发者指令
  • 任务目标与完成条件
  • 结构化计划和 TODO 状态
  • 工具描述与调用规范
  • Tool Search 和工具选择
  • 工作模式，例如执行模式、规划模式和审查模式
  • 子任务分解
  • 子 Agent 路由与角色分配
  • 反思、批评和独立复核提示
  • 停止条件与完成审计Harness 并不能替代模型推理，但可以给推理建立结构。例如，计划工具把“下一步做什么”从一段自然语言变成 pending、in_progress 和 completed 的明确状态；目标机制则把“什么时候算完成”从模型的主观判断变成持久化的生命周期。工具描述同样属于认知原语。工具名称、参数结构、返回格式和提示方式都会影响模型能否正确选择工具。模型与 Harness 共同训练后，这种接口设计甚至会直接影响模型性能。在 Codex 中，update_plan、Goals、Collaboration Modes、Tool Search、Skills、Prompt Templates 和 Subagent Routing 都属于这一层。

三、记忆与上下文原语：管理有限的上下文窗口

模型的上下文窗口既是工作内存，也是稀缺资源。Harness 必须决定哪些信息进入上下文、哪些信息保存到外部，以及上下文即将耗尽时如何继续。

记忆与上下文原语负责回答：

Agent 如何记住重要信息，又不被过多信息淹没？

典型原语包括：

  • 对话历史
  • Rollout 或事件日志
  • 会话恢复和分叉
  • AGENTS.md 等项目记忆文件
  • 用户偏好与长期记忆
  • 文件系统中的中间产物
  • 语义检索、关键词检索和引用
  • Context Injection
  • Compaction 和历史摘要
  • 工具输出截断
  • 大型输出文件卸载
  • Skills 渐进式披露
  • Deferred Tools 和按需工具加载
  • 上下文预算与优先级这里至少包含三种不同记忆：
  • 工作记忆：当前上下文中正在使用的信息。
  • 情节记忆：之前发生过的对话、工具调用和任务事件。
  • 语义或程序记忆：稳定知识、项目规范、用户偏好和可复用工作流程。文件系统是重要的记忆原语，但文件不会自动进入模型上下文。只有配合检索、选择、摘要和上下文注入，持久化数据才会转化为 Agent 可以使用的记忆。在 Codex 中，这一层由 Rollout JSONL、SQLite Thread Store、AGENTS.md、Memory、Compaction、Skills 和 BM25 Tool Search 等机制共同实现。

四、行动原语：让模型改变真实世界

只有感知和推理的模型仍然只是一个顾问。行动原语让模型能够执行命令、修改文件、调用服务，并对现实环境产生影响。

行动原语负责回答：

Agent 能够对环境做什么？

典型原语包括：

  • 文件创建、修改、移动和删除
  • apply_patch 等结构化代码编辑
  • Bash、PowerShell 和代码执行
  • Git、测试框架和构建工具调用
  • 浏览器点击、输入和导航
  • API 和 MCP 工具调用
  • 数据库读写
  • 云服务与企业系统操作
  • 动态编写并执行临时工具
  • 长时间运行进程和交互式终端Bash 与代码执行是通用行动原语。它们允许模型根据当前任务临时创建工具，而不必要求 Harness 设计者提前实现所有可能的操作。专用工具依然有价值。结构化工具可以提供更明确的参数、更好的权限控制、更稳定的返回值和更容易审计的语义。成熟 Harness 通常同时提供通用执行工具和高价值专用工具。在 Codex 中，Shell、Exec、PTY、Apply Patch、Browser、MCP、Plugins 和 Connectors 构成了行动层。

五、协作原语：让 Agent 与人和其他 Agent 共同工作

自主并不等于脱离人类。高质量 Agent 系统需要让用户能够理解、控制和纠正执行过程，也需要让多个 Agent 在复杂任务中协调工作。

协作原语负责回答：

Agent 如何与用户及其他 Agent 建立共同工作状态？

典型原语包括：

  • 中间进度更新
  • Commentary 与 Final Answer 区分
  • 用户中途 Steering
  • 澄清问题和结构化输入请求
  • 批准、拒绝和修改动作
  • 暂停、恢复和中断
  • 计划共享和状态展示
  • 子 Agent 创建与任务委派
  • Agent 间消息
  • Agent 状态查询和等待
  • 共享文件系统与共享工作账本
  • 结果汇总、冲突发现和责任归属多 Agent 并不只是“同时启动多个模型”。真正的协作还需要任务依赖、并发限制、父子关系、通信协议、结果归并和冲突处理。同样，人机协作也不只是最终展示答案。用户需要在 Agent 工作期间看到关键进展，并能够在不破坏当前任务状态的情况下调整方向。在 Codex 中，Commentary Phase、Follow-up Steering、Approvals、Request User Input、Agent Registry、Spawn、Message、Wait 和 Interrupt 都属于协作原语。

六、治理原语：控制 Agent 的权限与风险

行动能力越强，治理越重要。一个能够运行任意代码、访问网络和修改文件的 Agent，如果没有权限边界，就不能安全地进入真实生产环境。

治理原语负责回答：

Agent 被允许做什么，谁为动作授权，发生问题后如何追溯？

典型原语包括：

  • 文件系统沙箱
  • 网络隔离与域名策略
  • 命令允许和拒绝规则
  • 风险分类
  • 用户审批策略
  • 企业强制要求
  • 工作区信任
  • 身份认证与凭证管理
  • Secrets 隔离
  • 最小权限 Token
  • 插件和连接器权限
  • 审计日志
  • Prompt Injection 防护
  • 进程硬化和资源隔离沙箱只是治理的一部分。完整治理链通常是：

模型提出动作 ↓ 策略判断动作风险 ↓ 检查用户和企业权限 ↓ 必要时请求审批 ↓ 在沙箱中执行 ↓ 记录动作和结果

治理能力不能被模型原生智能完全替代。即使模型变得非常可靠，身份、权限、隔离和审计仍然必须由模型之外的确定性系统执行。

在 Codex 中，Sandbox Policy、Approval Policy、Exec Policy、Requirements、Guardian、Network Proxy、Keyring、Secrets 和 Process Hardening 共同构成治理层。

七、持续执行原语：让 Agent 跨越时间和故障

复杂任务不会在单次模型调用中完成。Agent 需要跨多个 Turn、多个上下文窗口，甚至多个会话持续工作。

持续执行原语负责回答：

Agent 如何一直工作到目标完成，而不是因为上下文、错误或进程结束而丢失任务？

典型原语包括：

  • 持久化任务目标
  • 计划与进度状态
  • Turn 和 Thread 生命周期
  • 自动续跑循环
  • 定时器、等待和事件唤醒
  • 会话恢复与 Fork
  • 重试、退避和超时
  • 取消与安全终止
  • 幂等工具调用
  • 中间检查点
  • Git 版本历史
  • Token、时间、成本和并发预算
  • 阻塞、暂停、限额和完成状态
  • 多上下文窗口之间的状态重建经典 Ralph Loop 通过拦截模型退出并重新注入目标来延续任务。更结构化的实现可以把目标保存为持久状态，在每次 Turn 结束后检查目标是否完成，再决定继续、暂停、阻塞或结束。持续执行还必须防止无限循环。预算、重复失败检测、阻塞审计和停止条件与“继续工作”同等重要。在 Codex 中，Goals、Thread Store、Rollout、Compaction、Stop Hooks、Resume、Fork、Timeout、Usage Limit 和 Agent Concurrency Limit 都属于持续执行原语。

八、验证与交付原语：证明工作正确并形成成果

Agent 完成了动作，不代表任务已经正确完成。Harness 必须提供观察结果、发现错误、反馈修复，并最终生成可审查成果的机制。

验证与交付原语负责回答：

Agent 如何证明结果正确，并把工作可靠地交给用户？

典型原语包括：

  • 单元测试、集成测试和端到端测试
  • 编译、类型检查和 Lint
  • 日志、退出码和错误输出
  • 浏览器检查与截图
  • 数据一致性检查
  • 独立 Reviewer 或 Critic Agent
  • Stop Hook 和测试门禁
  • 完成条件逐项审计
  • Diff 和 Patch 展示
  • Git Commit、Branch 和 Pull Request
  • 回滚与失败恢复
  • 结构化输出
  • 文档、报表、图片和其他 Artifact
  • 证据引用和来源追踪自我验证循环通常表现为：

实现 ↓ 运行测试或观察环境 ↓ 读取失败证据 ↓ 定位并修改 ↓ 重新验证 ↓ 满足完成条件后交付

验证必须尽可能依赖外部证据，而不是模型对自己输出的主观评价。测试结果、实际截图、数据库状态和可运行产物，比“代码看起来正确”更可靠。

在 Codex 中，Shell 测试、Browser、Screenshot、Logs、Stop Hooks、Goal Completion Audit、Diff、Git 和 Artifact 输出共同形成验证与交付层。

九、八类原语如何构成 Agent 闭环

八类原语并不是彼此独立的功能列表，而是一个持续运转的循环：

┌────────────治理────────────┐ │ 权限、身份、隔离、审计 │ ▼ │ 感知 → 认知与编排 → 行动 → 验证与交付 ↑ │ │ │ │ ▼ ▼ │ └──── 记忆与上下文 ← 持续执行 ←──┘ │ ▼ 人类与多 Agent 协作

一次典型任务可能经历以下过程：

  1. 感知原语读取工作区、需求和运行状态。
  2. 记忆原语注入项目规则和历史工作。
  3. 认知原语形成目标、计划并选择工具。
  4. 治理原语检查动作权限。
  5. 行动原语修改文件、执行命令或操作浏览器。
  6. 验证原语运行测试并观察结果。
  7. 持续执行原语决定继续、重试、暂停或完成。
  8. 协作原语向用户报告进展，或把子任务交给其他 Agent。
  9. 最终结果通过 Diff、Commit、PR 或 Artifact 交付。任何一类原语缺失，Agent 都可能表现出明显缺陷：
  • 没有感知，只能依赖用户复制粘贴。
  • 没有记忆，跨会话会丢失状态。
  • 没有行动，只能给出建议。
  • 没有治理，无法安全进入真实环境。
  • 没有持续执行，复杂任务容易过早停止。
  • 没有验证，Agent 可能把错误结果当作成功。
  • 没有协作，用户无法理解或控制执行过程。

十、Agent Harness 的成熟度阶梯

基于上述原语，可以把 Agent Harness 粗略分为六个成熟度等级。

Level 0：对话模型

  • 只有文本输入与输出
  • 不访问真实环境
  • 不保存跨会话状态

Level 1：工具 Agent

  • 具备文件读取和工具调用
  • 能执行简单命令
  • 仍以单轮任务为主

Level 2：有状态 Agent

  • 具备持久化会话和工作区
  • 支持计划、记忆和上下文压缩
  • 可以恢复之前的任务

Level 3：可靠 Agent

  • 具备沙箱、审批和权限控制
  • 能运行测试并根据失败反馈修复
  • 能处理超时、重试和部分失败

Level 4：协作 Agent

  • 支持用户中途 Steering
  • 支持多 Agent 委派与通信
  • 能共享任务状态并汇总结果

Level 5：长周期自治系统

  • 目标和状态跨会话持久化
  • 能在预算和治理约束下持续运行
  • 能动态发现工具和上下文
  • 能用外部证据验证完成条件
  • 能处理异步事件、失败恢复和正式交付当前 Codex 已经覆盖 Level 4 的大部分能力，并在 Goals、Compaction、Hooks、Plugins 和多 Agent 等方向上进入 Level 5，但距离“数百 Agent 自动协作、自主分析 Trace 并修复 Harness”的完全自治系统仍有距离。

结语

Agent Harness 的价值，可以归纳为四件事：

  1. 让模型看到真实世界。
  2. 让模型能够安全地改变真实世界。
  3. 让工作跨越上下文、故障和会话持续存在。
  4. 让结果能够被观察、验证、治理和交付。因此，一个更完整的 Agent 定义是：
一个在 Harness 提供的感知、记忆、行动、协作、治理和验证机制中，围绕持久目标持续运行的模型系统。

本文学习参考

Agent = Model + Harness 的最常用定义 https://www.langchain.com/blog/the-anatomy-of-an-agent-harness

Codex 源码结构分析 https://github.com/openai/codex