从 Codex、Claude Code 到 Agent Harness Engineering，重新理解智能体的工程化竞争力

过去两年，AI Agent 开发者最关心的问题一直在变化。

最初，我们讨论 Prompt Engineering：怎样写提示词，才能让模型理解任务？

后来，我们讨论 Tool Calling：怎样让模型调用搜索、数据库、浏览器和代码执行工具？

再后来，我们讨论 Multi-Agent：怎样让多个 Agent 分工合作，完成复杂任务？

而到了 2026 年，一个新的概念开始成为 Agent 工程领域的重要话题：

Harness Engineering。

如果说大语言模型是 Agent 的大脑，那么 Harness 就是围绕这个大脑构建的执行系统。

它决定模型能看到什么、能使用什么工具、如何执行任务、怎样处理失败，以及什么时候必须交还控制权。

这也带来了一个值得思考的问题：

未来 AI Agent 的竞争，究竟是在比谁拥有更强的模型，还是在比谁能让模型更可靠地完成任务？

我的判断是：模型能力仍然决定上限，但 Harness 越来越深刻地影响这个上限能否真正转化为生产力。

一、什么是 Agent Harness？

Harness 原本有“挽具”“安全带”“控制装置”等含义。

在 AI Agent 领域，可以把它理解为：

Agent Harness 是围绕大语言模型构建的运行、执行和控制系统，负责上下文管理、工具调用、状态维护、权限控制、任务恢复以及执行反馈。

一个大语言模型本身并不能真正修改文件、运行代码、打开浏览器或操作数据库。

它只能根据上下文生成内容，包括文本以及结构化的工具调用请求。

真正执行这些操作的是模型外部的软件系统。

例如，当我们让 Codex 修复一个 Bug 时，背后实际发生的事情可能是：

1. 理解用户的任务要求。

2. 检查当前代码仓库。

3. 搜索与 Bug 相关的代码。

4. 修改目标文件。

5. 执行测试。

6. 读取测试失败日志。

7. 根据错误再次修改代码。

8. 重新运行测试。

9. 汇总修改结果。

这已经不是一次简单的模型调用，而是一个持续运行的执行过程。

负责驱动整个过程的，就是 Harness。

一个最简化的 Agent 架构

             用户任务
                │
                ▼
        ┌─────────────────┐
        │  Agent Harness  │
        │                 │
        │  Context        │
        │  Agent Loop     │
        │  Tool Runtime   │
        │  Permissions    │
        │  State          │
        │  Recovery       │
        │  Observability  │
        └────────┬────────┘
                 │
          ┌──────┴──────┐
          ▼             ▼
       LLM Model      Tools
          │             │
          │        Shell / Browser
          │        Files / APIs
          │        Database
          └──────┬──────┘
                 │
                 ▼
             执行结果

模型负责理解、推理和决策。

Harness 负责把这些决策转化为可控、可执行、可验证的行动。

值得注意的是，Harness 不一定是单独部署的服务，也不等于某一个 Agent 框架。它可以是一套进程内运行时，也可以由多个基础设施组件共同构成。

二、为什么 Harness 开始变得重要？

一个有趣的现象是：

同样的模型，放进不同的 Agent 系统里，表现可能非常不同。

原因并不神秘。

模型接收到的上下文不同，拥有的工具不同，任务执行机制不同，失败处理方式不同，最终结果自然不同。

2026 年 8 月，OpenAI 发布了《Codex as a platform: build on the open agent harness》，介绍了如何将 Codex 底层 Harness 作为平台能力使用。

其中披露的一项实验尤其值得关注：

在 ARC-AGI-3 测试中，通过保留推理过程并引入上下文压缩，GPT-5.6 Sol 的成绩从 13.3% 提升至 38.3%，同时输出 Token 减少至原来的约六分之一。

这并不意味着换一个 Harness 就能让所有任务获得同样幅度的提升。它说明的是：在特定任务和评测条件下，运行系统的设计能够显著改变模型表现。

过去，我们可能会把 Agent 的失败归因于模型不够聪明。

但现在需要进一步追问：

• 模型是否拿到了正确的上下文？

• 它是否能访问完成任务所需的工具？

• 工具返回的信息是否容易理解？

• 它是否能识别自己的执行失败？

• 它能否在失败后重新规划？

• 它是否知道什么时候应该停止？

这些问题大部分不属于模型参数本身，而属于 Harness Engineering。

三、一个好的 Harness 应该包含什么？

我认为，现代 Agent Harness 至少需要六项核心能力。

1. Agent Loop：任务执行循环

Agent 最基本的能力是循环执行：

理解 → 决策 → 执行 → 观察 → 再决策。

伪代码如下：

async def run_agent(task, model, tools):
    messages = [
        {"role": "user", "content": task}
    ]

    for step in range(30):
        response = await model.generate(
            messages=messages,
            tools=tools.schemas()
        )

        if response.is_final:
            return response.content

        for call in response.tool_calls:
            result = await tools.execute(call)

            messages.append(
                response.tool_call_message(call)
            )

            messages.append(
                tools.result_message(call, result)
            )

    raise RuntimeError("Agent step limit reached")

这是一个示意实现，省略了工具权限、并发、错误处理、持久化和模型协议细节。

虽然代码很短，但它已经体现了 Harness 的基本思想：

模型不能直接控制整个系统。

模型提出行动，Harness 检查并执行行动，然后将结果送回模型。

生产环境中还需要控制循环次数、最大执行时间、Token 预算、取消操作和重复工具调用。

否则，一个不断重试的 Agent 可能消耗大量资源，却仍然无法完成任务。

2. Context Engineering：管理模型真正需要的信息

Context Engineering 是 Harness 的核心能力之一。

Agent 并不是拥有越多上下文就越好。

一个执行复杂任务的 Agent，可能需要处理：

• 用户指令

• 系统规则

• 历史对话

• 文件内容

• 工具输出

• 执行计划

• 错误日志

• 任务进度

如果全部直接塞进上下文窗口，很快就会产生信息冗余、成本上升以及关键约束被淹没的问题。

更合理的做法是让 Harness 管理上下文生命周期。

例如：

短期上下文： 当前步骤需要直接使用的信息。

工作记忆： 当前任务计划、已经完成的步骤和重要决策。

长期记忆： 跨任务保留的知识、偏好和历史经验。

外部知识： 通过检索或工具按需读取的资料。

核心原则是：

让 Agent 在正确的时间拿到正确的信息，而不是一次性拿到所有信息。

对于 Coding Agent，一个好的 Harness 应当知道什么时候读取 README、什么时候检索代码、什么时候查看测试日志。

上下文组织质量，往往直接影响执行效率。

3. Tool Runtime：安全可靠地执行工具

工具调用是 Agent 从语言模型变成行动系统的重要一步。

但工具不应该只是一个简单的函数列表。

生产级 Tool Runtime 至少应当处理：

• 工具注册与发现

• 参数 Schema 校验

• 身份认证与授权

• 超时与取消

• 错误分类与重试

• 日志与审计

• 结果大小控制

• 敏感操作审批

例如，Agent 请求执行：

rm -rf ./important-data

即使模型认为这是完成任务所需的操作，Harness 也不应该直接执行。

它必须先根据工具权限、工作目录限制和风险策略决定是否允许。

尤其需要注意，Prompt 中写“禁止删除重要文件”不能取代真正的权限控制。

安全边界必须由模型之外的确定性代码执行。

4. State & Persistence：管理长期任务

很多 Agent 演示只需要运行几十秒。

真实任务可能需要运行几十分钟，甚至跨越多次用户交互。

例如：

用户要求 Agent：

“分析代码仓库，修复所有相关测试失败，并提交一个 Pull Request。”

如果执行到第八步时网络中断，系统应该怎么办？

一个成熟的 Harness 需要具备：

Checkpoint： 保存关键执行状态。

Resume： 从已经确认的进度继续。

Retry： 对可恢复错误进行有限次数重试。

Idempotency： 避免恢复任务时重复执行危险操作。

Human-in-the-loop： 在需要审批时暂停，而不是直接放弃任务。

这里尤其需要区分两种状态。

一种是模型对话状态，另一种是实际执行环境状态。

保存了消息历史，并不意味着文件系统、数据库事务或浏览器页面也已经恢复。

因此，长任务恢复需要将 Harness 状态与外部环境状态协调起来。

5. Sandbox & Permissions：限制Agent的行动边界

Agent 的自主性越高，执行边界就越重要。

一个 Coding Agent 可能具备：

• 读取仓库代码

• 修改文件

• 执行 Shell 命令

• 安装依赖

• 访问网络

• 创建分支

• 提交代码

这些能力带来了生产力，也带来了安全风险。

比较合理的设计是采用分级权限：

Level 1：只读

允许读取文件、搜索代码和检查日志。

Level 2：受限写入

允许在指定工作区修改文件。

Level 3：受限执行

允许在沙箱中运行测试和命令。

Level 4：外部副作用

例如提交代码、发送消息、修改线上数据，需要额外授权。

隔离环境也不能只考虑文件系统。

还需要考虑网络访问、进程权限、密钥暴露、资源耗尽和跨任务数据泄漏。

此外，工具返回的网页、代码注释、文档内容都是潜在的不可信输入，不能因为它们进入了模型上下文，就自动获得更高权限。

6. Observability & Evaluation：让Agent能够被验证

传统软件通常执行相对确定的逻辑。

Agent 的不同之处在于，模型可能选择不同的执行路径。

因此，日志中仅仅记录最终回答还不够。

需要记录：

• 每一步模型调用

• 使用的模型与版本

• Token 和成本

• 工具请求及执行结果

• 状态变更

• 失败原因

• 关键审批

• 最终任务完成情况

真正有效的 Harness，不只是能够执行任务，还应该能够解释任务在哪里失败，以及如何验证修复是否有效。

对于 Coding Agent，编译、测试和静态检查是非常重要的客观反馈。

对于 Research Agent，则需要验证来源真实性、事实准确率以及引用是否支持结论。

对于业务 Agent，需要验证实际业务状态是否正确改变。

Agent 的最终质量指标应该是任务成功率，而不是模型输出看起来有多聪明。

四、Codex 给 Harness Engineering 带来了什么启示？

2026年2月，OpenAI 发表了《Harness engineering: leveraging Codex in an agent-first world》。

文章介绍了一项内部工程实验：

一个小型工程团队主要通过 Codex Agent 开发软件，不手动编写生产代码。

在约五个月时间里，项目积累了百万行量级的代码，并完成约1500个 Pull Request。

团队估计，这项工作所需时间约为传统手写代码方式的十分之一。

这些数字来自特定团队、特定项目的实践估算，不能直接推断所有企业都能获得相同收益。

但这个案例最重要的启示并不是“AI可以写多少代码”。

而是工程师的工作重心发生了改变。

过去，工程师主要负责：

理解需求
   ↓
设计方案
   ↓
编写代码
   ↓
测试代码
   ↓
修复问题

而在 Agent-first 的开发方式中，工程师越来越多地负责：

定义目标与验收标准
          ↓
设计 Agent 工作环境
          ↓
提供工具与上下文
          ↓
构建自动验证机制
          ↓
观察执行结果
          ↓
改进 Harness

这里存在一个关键转变：

当 Agent 执行失败时，工程师不应该只想着重新写一遍 Prompt，而应该检查整个执行系统缺少了什么能力。

例如，Agent 经常修复不了前端 UI Bug，可能不是模型不理解代码，而是它无法真实地启动浏览器、查看界面、读取控制台错误。

解决方案不是反复要求模型“认真检查”，而是给它浏览器自动化能力、截图工具以及可验证的测试环境。

OpenAI 的实践还强调了一个思想：

让仓库知识成为 Agent 可以直接读取、验证的事实来源。

包括设计决策、架构约束、测试规则、运行方式和历史计划，都应该尽量以可发现、可版本化的形式存在。

这比维护一份不断膨胀的巨型提示词更有价值。

五、Harness、Agent Framework 和 MCP 到底有什么区别？

这三个概念经常被混在一起。

但它们解决的问题并不完全相同。

概念	主要职责	典型内容
LLM	推理、理解和生成	模型本身
Agent Framework	提供开发抽象与编排组件	LangGraph、Agents SDK
Agent Harness	实际运行Agent并管理执行过程	Codex Harness、专用Agent Runtime
MCP	标准化工具与资源接入	MCP Server、MCP Client
Sandbox	隔离高风险执行操作	Container、受限执行环境
Workflow Engine	管理确定性工作流和长期任务	Temporal、任务调度系统

这里有一个重要区别：

Framework 是开发者使用的抽象，Harness 是 Agent 实际运行时依赖的控制系统。

它们并不是互斥关系。

一个 Framework 可能自带 Harness 能力。

一个 Harness 也可以使用 Framework 提供的部分组件。

MCP 则主要解决工具和外部资源的连接协议问题，不负责定义完整的任务生命周期。

因此，选择 LangGraph 或 OpenAI Agents SDK，并不等于自动解决了全部 Harness 工程问题。

仍然需要根据场景建设权限控制、沙箱、状态恢复、评测和运行监控。

六、如果从零开发一个 Harness，应该怎么设计？

我建议采用渐进式架构，而不是一开始构建一个无所不能的 Agent 平台。

第一阶段：实现最小Agent Loop

只实现四件事：

1. 模型调用。

2. 工具调用。

3. 工具结果反馈。

4. 执行终止条件。

这个阶段的目标是验证任务是否能够完成。

第二阶段：加入上下文管理

增加：

• 对话历史

• 文件检索

• Token预算

• 上下文压缩

• 执行计划

• 工作记忆

避免随着任务变长，上下文无限增长。

第三阶段：引入执行安全

增加：

• 工具权限

• 参数校验

• Shell沙箱

• 网络访问限制

• 人工审批

• 执行审计

这是从Demo走向实际产品的重要门槛。

第四阶段：引入任务状态

增加：

• Checkpoint

• 任务恢复

• 执行超时

• 用户取消

• 幂等处理

• 失败重试

这个阶段的系统才具备承载复杂任务的基本条件。

第五阶段：建立反馈闭环

增加：

• 执行Trace

• 自动测试

• 质量评测

• 成本监控

• 错误分类

• 失败案例回归

让每次失败能够成为下一次优化的输入。

最终形成：

               User / API
                   │
                   ▼
             Agent Runtime
                   │
       ┌───────────┼───────────┐
       │           │           │
       ▼           ▼           ▼
    Context     Agent Loop    State
    Manager                   Store
       │           │           │
       └───────────┼───────────┘
                   │
                   ▼
             Tool Gateway
                   │
         ┌─────────┼──────────┐
         ▼         ▼          ▼
       MCP       Sandbox     Business
       Tools                  APIs
         │         │          │
         └─────────┼──────────┘
                   │
                   ▼
             Observability
              & Evaluation

对于技术选型，可以考虑：

• Agent Runtime：OpenAI Agents SDK、LangGraph或自研轻量循环。

• 状态存储：PostgreSQL。

• 缓存和任务队列：Redis。

• 长期可靠执行：Temporal等工作流系统。

• 工具接入：Function Calling + MCP。

• 执行环境：Docker或独立受限容器。

• 可观测性：OpenTelemetry + Langfuse。

• 自动评测：业务测试集 + Agent轨迹评测。

需要强调，这是一种参考架构，不是所有项目都必须引入这些组件。

简单的内部工具型Agent，可能只需要一个轻量Harness和几个经过验证的工具。

七、Harness Engineering 的真正难点是什么？

在实际工程中，我认为有三个问题最值得关注。

1. 如何让Agent知道自己错了？

模型生成一段看起来正确的代码，不等于代码真的可以运行。

Agent 提供一份市场研究报告，也不等于报告中的事实都被正确核实。

因此，Harness 应该尽可能引入外部可验证的反馈。

例如：

编程任务依赖测试与编译。

数据分析任务依赖数据校验和计算验证。

业务操作任务依赖实际业务状态确认。

不要要求模型仅凭自己的语言判断任务是否成功。

2. 如何避免Agent不断重复错误？

如果每次失败后，Harness 都把原始任务重新发给模型，可能会得到相同的失败路径。

更合理的处理方式是记录：

• 已尝试过的方法

• 失败的具体原因

• 工具返回的证据

• 已经确认的约束

• 下一步允许的行动

然后在必要时调整执行策略。

这里需要的是有边界的恢复机制，而不是无限循环。

3. 如何让Agent长期保持工程质量？

AI生成代码的速度可以很快，但高速生成也可能快速积累技术债务。

例如重复的工具函数、不一致的架构风格、过度复杂的抽象以及失效文档。

OpenAI 的 Codex 工程实践强调，将架构约束转化为可执行的静态检查，并通过自动化任务持续整理技术债务。

这很值得借鉴。

Harness 不仅应该帮助 Agent 完成当前任务，还应该帮助 Agent 遵守整个系统的长期工程约束。

否则，短期开发速度的提升可能被长期维护成本抵消。

八、未来的竞争：Model Engineering 还是 Harness Engineering？

过去，Agent 相关产品经常比拼使用哪个大模型。

但在模型持续迭代、基础能力逐渐普及的背景下，仅仅接入一个强模型，很难构成长期差异化优势。

同一个模型，在不同产品中的实际表现，可能因为以下因素产生很大差异：

上下文质量。 是否能快速找到真正相关的信息。

工具能力。 是否拥有完成任务的有效操作手段。

执行环境。 是否能够安全地运行代码、浏览页面和操作文件。

恢复能力。 是否能从中断和失败中继续执行。

反馈质量。 是否能用客观证据验证执行结果。

权限边界。 是否能够在控制风险的前提下提高自主性。

因此，未来优秀的 Agent 产品不仅需要优秀的模型，还需要专门为目标任务设计的 Harness。

例如：

Coding Agent 需要深入理解代码仓库、终端、测试与版本控制。

Research Agent 需要搜索、浏览、来源核实与信息综合能力。

Data Agent 需要SQL执行、数据质量检查、计算验证和图表生成能力。

Browser Agent 需要网页状态理解、交互恢复和敏感操作审批。

它们可以共享某些基础运行组件，但很难只用同一套通用 Prompt 获得最优表现。

这意味着一个趋势：

通用模型负责提供智能基础，领域化 Harness 负责将智能转化成稳定的业务能力。

九、我的观点：不要只做一个Agent，要设计它的工作环境

如果今天让我从零开始开发一个 Agent 产品，我不会先花大量时间讨论应该设计几个 Agent 角色。

我会先回答五个问题：

第一，这个Agent最终要完成什么可验证的任务？

第二，它需要哪些信息和工具才能完成任务？

第三，什么操作必须由系统限制或人工审批？

第四，任务失败后如何恢复，避免重复产生副作用？

第五，我们通过什么指标判断它比上一版更好？

这些问题的答案，基本决定了 Harness 的设计方向。

Prompt Engineering 仍然重要。

模型选型仍然重要。

Multi-Agent 协作也有其价值。

但它们都不能代替可靠的执行系统。

真正有价值的 Harness Engineering，是把模型的不确定性放进一个具有清晰边界、可观测、可恢复、可验证的工程体系中。

结语

AI Agent 的发展，正在推动软件工程的职责发生变化。

以前，我们花大量时间告诉计算机每一步应该怎么做。

现在，我们越来越多地告诉 Agent 想要什么结果，并为它构建能够完成任务的工作环境。

在这个过程中，工程师的价值并没有消失，而是逐渐向架构设计、任务定义、安全控制和反馈系统转移。

未来优秀的工程师，不仅要知道怎样调用模型，更要知道怎样设计一个能让模型可靠工作的系统。

这就是 Harness Engineering 真正值得关注的原因。

模型决定Agent有多聪明，Harness决定这些智能能否真正变成可靠的行动。