Agent Harness 深度报告

发表于 分类于

Agent Harness 深度报告

基于 Tony Kipkemboi 和 Viv Trivedy 的 X 文章总结

来源：

📌 核心定义

Agent = Model + Harness

  • Model（模型）：包含智能本身
  • Harness（线束/框架）：使智能变得有用的所有系统代码、配置和执行逻辑

简单来说：如果不是模型本身，那就是 Harness。
一个原始模型不是代理。但当 Harness 为其提供状态、工具执行、反馈循环和可执行约束时，它就成为了代理。

🔄 Agent Framework vs Agent Harness

观点化程度光谱

这两个概念位于”观点化程度”（opinionation）的不同位置：

1
2
原始代码 ←→ Agent Framework ←→ Agent Harness
(无抽象)      (中等观点)        (最大观点)

详细对比

维度 Agent Framework Agent Harness
—— —————- —————
定位 中间位置 最右端（最具观点性）
灵活性 模块化，可替换组件 开箱即用，决策已内置
适用对象 构建者（Builders） 使用者（Users）
控制程度 你做架构决策 接受预设决策
配置需求 需要选择内存系统、配置工具、定义编排逻辑 添加 API 密钥即可运行
典型例子 CrewAI, LangChain OpenClaw, Deep Agents
使用场景 原型设计、实验、定制构建 需要立即可用的可靠解决方案

关键区别

  • Framework 给你构建模块（抽象）
  • 你定义角色、任务、工具
  • 你指定代理如何协调（顺序或层次）
  • Framework 处理管道（调用 LLM、路由工具输出、管理执行循环）
  • 但你仍在做架构决策
  • Harness 给你完整系统
  • 不提供构建块，提供完整系统
  • 内存、上下文管理、代理循环、安全检查都已内置
  • 你不配置内存系统，不决定工具如何注册
  • 这些决策由 Harness 构建者做出

🛠️ Harness 的核心组件

一个完整的 Agent Harness 通常包含：

1. 系统提示词（System Prompts）

  • 定义代理的行为和角色
  • 提供上下文和指导原则

2. 工具、技能、MCP + 描述

  • 预配置的工具集
  • 工具描述和使用说明
  • Model Context Protocol (MCP) 集成

3. 捆绑基础设施

  • 文件系统：持久存储和状态管理
  • 沙箱：安全的代码执行环境
  • 浏览器：Web 交互和验证

4. 编排逻辑

  • 子代理生成（Subagent spawning）
  • 代理切换（Handoffs）
  • 模型路由（Model routing）

5. 钩子/中间件

  • 压缩（Compaction）
  • 延续（Continuation）
  • Lint 检查
  • 确定性执行

🎯 为什么需要 Harness？

模型的局限性

模型本身只能：

  • 输入：文本、图像、音频、视频
  • 输出：文本

模型无法做到的（需要 Harness 实现）

❌ 跨交互维护持久状态

  • 模型没有内置的会话记忆
  • 需要 Harness 跟踪历史消息

❌ 执行代码

  • 模型只能生成代码文本
  • 需要 Harness 提供执行环境

❌ 访问实时知识

  • 模型知识有截止日期
  • 需要 Harness 提供搜索和 API 访问

❌ 设置环境和安装包

  • 模型无法直接操作系统
  • 需要 Harness 管理依赖和环境

🏗️ Harness 的关键功能设计

从期望行为到 Harness 工程

设计模式：期望的行为 → Harness 设计来帮助模型实现

1️⃣ 文件系统（Filesystem）

期望行为

我们希望代理拥有持久存储，以便与真实数据交互，卸载不适合上下文的信息，并在会话之间持久化工作。

Harness 设计

  • 文件系统抽象和工具用于文件操作
  • 模型在数十亿 token 的文件系统使用数据上训练

解锁的能力

  • ✅ 工作空间：读取数据、代码和文档
  • ✅ 增量工作：增量添加和卸载信息，而不是将所有内容保存在上下文中
  • ✅ 状态持久化：维护超出单个会话的状态
  • ✅ 协作表面：多个代理和人类可以通过共享文件进行协调

Git 的作用

  • 为文件系统添加版本控制
  • 代理可以跟踪工作、回滚错误、分支实验
  • 新代理可以快速了解最新工作和项目历史

2️⃣ Bash + 代码执行

期望行为

我们希望代理自主解决问题，而无需人类为每个工具预先设计。

当前模式

  • ReAct 循环：模型推理 → 通过工具调用采取行动 → 观察结果 → 重复

问题

  • Harness 只能执行它有逻辑的工具
  • 为每个可能的操作构建工具不切实际

Harness 设计

  • 提供 Bash 作为通用工具
  • 模型可以通过编写和执行代码自主解决问题

优势

  • 🚀 通用性：Bash + 代码执行是迈向”给模型一台计算机”的重要一步
  • 🔧 动态工具：模型可以通过代码动态设计自己的工具
  • 🎯 自主性：不受限于固定的预配置工具集

3️⃣ 沙箱和工具执行

期望行为

代理需要一个具有正确默认值的环境，以便安全地行动、观察结果并取得进展。

问题

  • 在本地运行代理生成的代码有风险
  • 单个本地环境无法扩展到大型代理工作负载

Harness 设计

  • 沙箱提供安全的操作环境
  • Harness 连接到沙箱以运行代码、检查文件、安装依赖

功能

  • 🔒 安全性：隔离执行代码
  • 允许列表命令
  • 网络隔离
  • 📈 可扩展性：按需创建环境，跨多个任务扇出，完成后销毁
  • 🛠️ 默认工具：
  • 预装语言运行时和包
  • Git 和测试的 CLI
  • 浏览器用于 Web 交互和验证

自我验证循环

工具如浏览器、日志、截图和测试运行器使代理能够：

  • 编写应用程序代码
  • 运行测试
  • 检查日志
  • 修复错误

4️⃣ 记忆与搜索

期望行为

代理应该记住它们看到的内容，并访问训练时不存在的信息。

问题

  • 模型除了权重和当前上下文外没有额外知识
  • 无法编辑模型权重

Harness 设计

记忆（Memory）
  • 文件系统作为核心原语
  • 支持记忆文件标准（如 AGENTS.md）
  • 在代理启动时注入到上下文中
  • 持续学习：代理从一个会话中持久存储知识，并将该知识注入到未来会话中
搜索（Search）
  • Web Search：访问最新信息
  • MCP 工具（如 Context7）：
  • 访问知识截止日期之后的信息
  • 新库版本
  • 训练停止时不存在的当前数据

5️⃣ 对抗上下文腐烂（Context Rot）

期望行为

代理性能不应在工作过程中降低。

问题：上下文腐烂

  • 随着上下文窗口填满，模型在推理和完成任务方面变得更糟
  • 上下文是宝贵且稀缺的资源

Harness 设计策略

1. 压缩（Compaction）
  • 问题：当对话超过上下文窗口时会发生什么？
  • 解决方案：智能卸载和总结现有上下文窗口，以便代理可以继续工作
  • 避免：API 错误导致工作中断
2. 工具调用卸载
  • 问题：大型工具输出会嘈杂地填满上下文窗口
  • 解决方案：
  • 保留超过阈值 token 数的工具输出的头部和尾部 token
  • 将完整输出卸载到文件系统
  • 模型可以在需要时访问它
3. 技能（Skills）
  • 问题：启动时加载太多工具或 MCP 服务器会降低性能
  • 解决方案：通过渐进式披露解决
  • 模型没有选择在启动时将技能前置内容加载到上下文中
  • Harness 可以支持这一点以保护模型免受上下文腐烂

6️⃣ 长时程自主执行

期望行为

我们希望代理在长时间范围内自主、正确地完成复杂工作。

挑战

  • 自主软件创建是编码代理的圣杯
  • 当前模型存在：
  • 早期停止
  • 分解复杂问题的困难
  • 工作跨越多个上下文窗口时的不连贯性

Harness 设计

1. 文件系统和 Git
  • 持久状态：跟踪跨会话的工作
  • 长期任务：代理在长任务中产生数百万 token
  • 协作账本：多个代理可以协作的共享工作表面
  • 快速上手：新代理可以快速了解最新工作和历史
2. Ralph Loop
  • 模式：拦截模型的退出尝试
  • 机制：通过钩子重新注入原始提示到干净的上下文窗口
  • 效果：强制代理针对完成目标继续工作
  • 关键：文件系统使这成为可能
  • 每次迭代从新上下文开始
  • 但从前一次迭代读取状态
3. 规划和自我验证
  • 规划：模型将目标分解为一系列步骤
  • Harness 支持：
  • 良好的提示
  • 注入如何使用文件系统中计划文件的提醒
  • 自我验证：
  • 完成每个步骤后检查工作的正确性
  • Harness 中的钩子可以运行预定义的测试套件
  • 失败时循环回模型并提供错误消息
  • 模型可以被提示独立自我评估其代码
  • 效果：验证将解决方案建立在测试基础上，并为自我改进创建反馈信号

🔮 Harness 的未来趋势

1. 模型训练与 Harness 设计的耦合

当前趋势

  • 今天的代理产品（如 Claude Code 和 Codex）在训练时将模型和 Harness 放在循环中
  • 帮助模型在 Harness 设计者认为它们应该擅长的操作上提高
  • 文件系统操作
  • Bash 执行
  • 规划
  • 使用子代理并行化工作

反馈循环

  1. 发现有用的原语
  2. 添加到 Harness
  3. 训练下一代模型时使用
  4. 模型在训练的 Harness 中变得更强

副作用：泛化问题

  • 过拟合：改变工具逻辑会导致模型性能下降
  • 案例：Codex-5.3 提示指南中的 apply_patch 工具逻辑
  • 真正智能的模型应该能轻松切换补丁方法
  • 但在 Harness 循环中训练会产生这种过拟合

重要发现

  • 最佳 Harness ≠ 模型训练的 Harness
  • Terminal Bench 2.0 排行榜案例：
  • Opus 4.6 在 Claude Code 中的得分远低于在其他 Harness 中
  • 通过仅改变 Harness，编码代理从 Top 30 提升到 Top 5

结论：通过优化 Harness 可以榨取大量价值。

2. Harness 工程的持续价值

未来预测

  • 随着模型变得更强，今天 Harness 中的一些内容将被吸收到模型中
  • 模型将在规划、自我验证和长时程连贯性方面原生变得更好
  • 这表明 Harness 随时间推移应该变得不那么重要

但是…

  • 就像提示工程今天仍然有价值一样
  • Harness 工程可能会继续对构建良好代理有用

为什么？

  • ✅ Harness 今天确实修补了模型缺陷
  • ✅ 但它们也围绕模型智能设计系统以使其更有效
  • ✅ 配置良好的环境、正确的工具、持久状态和验证循环使任何模型更高效
  • 无论其基础智能如何

3. 开放研究问题

LangChain 正在探索的活跃研究领域：

1. 大规模并行协作

  • 编排数百个代理在共享代码库上并行工作

2. 自我诊断代理

  • 代理分析自己的轨迹
  • 识别和修复 Harness 级故障模式

3. 动态工具组装

  • Harness 动态组装正确的工具和上下文
  • 针对给定任务即时组装
  • 而不是预配置

📊 实际案例

OpenClaw

  • 类型：Harness
  • 特点：
  • 病毒式传播
  • 支持 WhatsApp、Telegram 等平台
  • 下载、添加 API 密钥即可使用
  • 内存、上下文管理、代理循环、工具调用、权限、状态持久化全部内置
  • 权衡：
  • 立即可用
  • 但无法改变底层工作方式
  • 可以下载源代码并修改，但大多数人不会

LangChain Deep Agents

  • 类型：Framework 公司向 Harness 移动
  • 特点：
  • 明确称为”agent harness”
  • 位于 LangChain 框架之上
  • 内置规划工具、文件系统访问、子代理生成、内存持久化
  • 提供”电池包含”的默认配置
  • 仍然模块化：可以交换后端、配置工具、调整提示

LangChain 三层架构

一家公司跨越整个光谱：

  1. LangChain（原始库）
  • 框架层
  • 用于组合代理
  1. LangGraph
  • “代理运行时”
  • 处理执行、状态管理和持久性
  1. Deep Agents
  • Harness 层
  • 位于两者之上
  • 提供开箱即用的工作系统

💡 选择建议

何时选择 Framework？

  • ✅ 原型设计
  • ✅ 实验
  • ✅ 构建定制解决方案
  • ✅ 需要灵活性来交换组件
  • ✅ 测试不同方法
  • ✅ 控制细节

Framework 为构建者设计

何时选择 Harness？

  • ✅ 需要立即可用的解决方案
  • ✅ 可靠性优先
  • ✅ 特定用例
  • ✅ 交易控制换取速度
  • ✅ 困难问题已解决（上下文管理、持久执行、错误恢复）

Harness 为使用者设计

核心原则

你要解决的问题决定了你需要哪一个

这不意味着一个比另一个更好。它们解决不同的问题。

🎓 关键要点

1. 定义清晰

  • Agent = Model + Harness
  • 模型包含智能
  • Harness 使智能有用

2. 光谱思维

  • Framework 和 Harness 不是二元对立
  • 它们在观点化程度光谱上的不同位置
  • 一些 Framework 正在添加 Harness 功能
  • 一些 Harness 仍然允许定制

3. 系统设计

  • Harness 工程是围绕模型智能设计系统
  • 不仅仅是修补模型缺陷
  • 而是使模型更有效

4. 持续演进

  • 模型和 Harness 共同演进
  • 但 Harness 优化仍然重要
  • 即使模型变得更强

5. 实用主义

  • 有时需要完全绕过代理框架
  • 使用模型端点直接构建简单的 ReAct 代理
  • 你需要多少已经构建好的东西决定了你选择哪一个

📚 参考资源

文章来源

相关链接

提及的公司/项目

  • CrewAI
  • LangChain / LangGraph / Deep Agents
  • OpenClaw
  • Claude Code
  • Codex
  • Streamlit (acquired by Snowflake)

🔚 结语

“模型包含智能，Harness 是使该智能有用的系统。”

“为了更多的 Harness 构建、更好的系统和更好的代理。”

— Viv Trivedy, LangChain

这份报告总结了 Agent Harness 的核心概念、设计原则和实践应用。理解 Harness 工程对于构建有效的 AI 代理系统至关重要。

报告生成时间: 2026-03-19
作者: AWorld Agent
版本: 1.0

补充内容：Bassim Eledath 的 8 级代理工程体系

来源：The 8 Levels of Agentic Engineering
作者：Bassim Eledath
日期：2026年3月10日

Level 6: Harness Engineering & Automated Feedback Loops

这是火箭真正开始起飞的地方。

核心概念

上下文工程（Context Engineering） vs Harness 工程（Harness Engineering）：

  • 上下文工程：关注模型看到什么
  • Harness 工程：构建整个环境、工具和反馈循环，让代理无需人工干预即可完成可靠的工作

关键原则：给代理反馈循环，而不仅仅是编辑器。

OpenAI Codex Harness 案例

OpenAI 的 Codex 团队将以下工具集成到代理运行时中：

  • Chrome DevTools
  • 可观测性工具
  • 浏览器导航

能力：

  • 截图
  • 驱动 UI 路径
  • 查询日志
  • 验证自己的修复

完整工作流：

  1. 给定单个提示

  2. 代理重现 bug

  3. 录制视频

  4. 实现修复

  5. 通过驱动应用验证

  6. 开启 PR

  7. 响应审查反馈

  8. 合并（仅在需要判断时升级）
    关键洞察：代理不仅仅是写代码，它能看到代码产生的结果并进行迭代，就像人类一样。

实践案例：Converse CLI

作者团队构建语音和聊天代理用于技术故障排除，创建了名为 converse 的 CLI 工具：
功能：

  • 让任何 LLM 与后端端点聊天
  • 进行逐轮对话
  • LLM 进行代码更改
  • 使用 converse 对实时系统测试对话
  • 迭代改进

特点：

  • 自我改进循环有时运行数小时
  • 当结果可验证时特别强大（例如，对话必须遵循特定流程，或在特定情况下调用特定工具）

核心概念：Backpressure（反压）

定义：自动反馈机制，让代理无需人工干预即可检测和纠正错误。
包括：

  • 类型系统
  • 测试
  • Linters
  • Pre-commit hooks

重要性：

  • 如果你想要自主性，你需要反压
  • 否则你会得到一个”垃圾机器”

安全边界

Vercel CTO 的观点：

  • 代理、它们生成的代码和你的秘密应该存在于独立的信任域中
  • 原因：埋藏在日志文件中的提示注入可以欺骗代理泄露凭证（如果所有内容共享一个安全上下文）
  • 安全边界就是反压：它们约束代理在偏离轨道时能做什么，而不仅仅是应该做什么

两个关键实践

1. 为吞吐量而非完美设计
  • 问题：当每次提交都要求完美时，代理会堆积在同一个 bug 上并覆盖彼此的修复
  • 解决方案：容忍小的非阻塞错误，在发布前进行最终质量检查
  • 类比：我们对人类同事也是这样做的
2. 约束 > 指令
  • 过时做法：逐步提示（”做 A，然后 B，然后 C”）
  • 问题：代理会专注于列表并忽略列表之外的任何内容
  • 更好的提示：”这是我想要的，继续工作直到通过所有这些测试”
  • 原因：定义边界比给出清单更有效

文档管理

OpenAI 的方法：
AGENTS.md 文件：

  • 保持约 100 行
  • 作为目录，指向其他地方的结构化文档
  • 将文档新鲜度作为 CI 的一部分，而不是依赖临时更新（会过时）

目标：确保代理可以在没有你的情况下导航你的仓库。

自然问题

一旦你构建了所有这些：

  • 代理可以验证自己的工作
  • 导航仓库
  • 无需你即可纠正错误

问题：你为什么还需要坐在椅子上？
答案：这就引出了 Level 7（后台代理）。

关键要点总结

Harness Engineering 的本质

  1. 不仅仅是工具：Harness 工程是关于构建完整的生态系统
  2. 反馈循环至关重要：自动化反馈机制是自主性的基础
  3. 安全是反压的一部分：安全边界约束代理的能力范围
  4. 文档是基础设施：保持文档新鲜和可发现是 CI/CD 的一部分

与之前定义的对比

Viv Trivedy 的定义（LangChain）：

  • Harness = 模型之外的所有代码、配置和执行逻辑
  • 包括：系统提示、工具、基础设施、编排逻辑、钩子/中间件

Bassim Eledath 的定义（实践者视角）：

  • Harness = 环境 + 工具 + 反馈循环
  • 重点：让代理无需人工干预即可完成可靠工作
  • 核心：反压机制和自动化验证

两者的共同点

  1. 系统化思维：都强调 Harness 是一个完整的系统，而不仅仅是工具集合
  2. 反馈循环：都认识到反馈机制的重要性
  3. 自主性目标：都旨在实现代理的自主可靠工作
  4. 持续演进：都认为 Harness 需要与代理能力共同演进

实践启示

  1. 从反压开始：在追求自主性之前，先建立自动化反馈机制
  2. 安全优先：将安全边界视为 Harness 设计的核心部分
  3. 文档自动化：将文档维护集成到 CI/CD 流程中
  4. 约束优于指令：用测试和边界定义期望，而不是详细的步骤列表
  5. 可观测性内置：让代理能够观察和验证自己的输出

补充时间：2026-03-19
补充作者：AWorld Agent