Agent Harness 深度研究报告

1. 核心定义：什么是 Agent Harness？

Agent Harness 是包裹在 AI 模型外部的运行时基础设施，它管理模型的生命周期、上下文、工具调用和与外部世界的交互。它不是"大脑"本身，而是为大脑提供工具、记忆和安全限制的运行环境。

类比理解

关键区分：Framework vs Runtime vs Harness

• Framework（如 LangChain）：开发零件库，提供构建 Agent 的工具和模块
• Runtime（如 LangGraph）：执行引擎，管理 Agent 的运行时状态
• Harness：完整的运行时环境，包含上下文管理、工具编排、安全护栏、持久化等

2. 为什么需要 Agent Harness？

生产环境的现实挑战

行业共识：瓶颈在基础设施，不在模型

五个独立团队得出相同结论：

1. OpenAI：3 人用 5 个月让 Codex 生成了 100 万行代码（零手写），关键不是提示工程，而是 Harness
2. Anthropic：16 个 Claude 实例并行，2000 个 session 完成 10 万行 C 编译器，负责人 Carlini 说："大部分精力花在设计 Claude 周围的环境上"
3. Huntley：自治循环发布 MVP，但每一步都需要高级工程师的判断引导
4. Horthy：提出"Harness Engineering"，发现上下文利用率超过 40% 后性能显著下降
5. Vasilopoulos：2026 年论文验证，三层上下文架构在 10.8 万行代码库上防止了单文件指令集无法处理的失败

3. Agent Harness 的核心组件

3.1 上下文工程（Context Engineering）

问题：简单地把所有数据塞给模型不可扩展。

解决方案：分层上下文 + 渐进式披露

关键技术：

• 压缩：将 50 页日志压缩为关键 bullet points
• 注入：使用 RAG 仅在需要时注入相关文档
• 频繁有意压缩（Frequent Intentional Compaction）：保持上下文利用率在 40-60% 的"智能区"

3.2 工具编排与护栏（Tool Orchestration & Guardrails）

Harness 控制 AI 与业务系统之间的网关，遵循严格流程：

1. 拦截请求：捕获模型使用工具的意图
2. 验证权限：检查 Agent 是否被授权执行该操作
3. 执行工具：在安全的隔离环境中运行命令
4. 清理输出：去除不必要的技术术语
5. 反馈给模型：精炼的结果返回给模型继续推理

3.3 人机协作（Human-in-the-Loop）

对于敏感操作，Harness 创建"中断点"：

• 起草给高价值客户的邮件 → 暂停等待人工审核 → 人工点击"发送"
• 删除客户数据 → 需要二次确认
• 大额金融交易 → 人工最终审批

3.4 状态持久化

• 内存外存分离：进度持久化到文件系统，而非依赖对话历史
• 会话恢复：系统崩溃后可以从断点继续
• 任务锁：多 Agent 协作时通过文件锁定协调

4. Harness Engineering 的四大支柱

支柱 1：上下文架构（Context Architecture）

• 分层加载，渐进披露
• 每个 Agent 只携带与其当前任务相关的上下文
• 避免信息过载导致的"愚蠢区"

支柱 2：Agent 专业化（Agent Specialization）

• 专注的 Agent + 受限工具 > 通用 Agent + 完整访问权限
• Carlini 的编译器项目后期，Agent 分化出：核心编译、去重、性能优化、代码质量、文档等专业角色
• 专业化是一种上下文管理策略

支柱 3：持久内存（Persistent Memory）

• 文件系统作为记忆，而非对话历史
• 使用 progress.txt、IMPLEMENTATION_PLAN.md 等工件
• 每个新会话从文件系统重建上下文

支柱 4：结构化执行（Structured Execution）

• 明确的阶段划分：理解 → 规划 → 执行 → 验证
• 思考与打字分离：研究规划在受控阶段完成，执行针对已验证的计划
• 自动化反馈：测试、Linter、CI 提供验证

5. 主流 Agent Harness 实现

5.1 Claude Code SDK（Anthropic）

定位：目前最成熟的 Harness 之一

核心特性：

• 2896 token 的系统提示 + 20 个内置工具
• 专业化子 Agent：Plan（633 tokens）、Explore（516 tokens）、Task（294 tokens）
• MCP 工具支持（虽然采用 eager loading，正在改进为 Tool Search）
• 检查点系统（Checkpoints）：安全回滚

架构：

用户输入 → Agent Loop → 工具调用/执行 → 状态更新 → 流式返回

HaaS（Harness as a Service）：
从 client.chat.completions.create() 到 client.responses.create() 再到 agent.query()，核心原语正在从 LLM API 转向 Harness API。

5.2 Codex Harness（OpenAI）

定位：OpenAI 官方 Harness，支持多平台统一体验

架构组件：

• App Server：JSON-RPC over stdio/WebSocket
• Harness：Firecracker microVM 沙箱
• 核心线程：持久化会话容器

协议：

• 双向 JSON-RPC（JSONL 格式）
• 原语：Item（最小 I/O）、Turn（一轮工作）、Thread（会话容器）

关键实践：

• AGENTS.md 作为动态反馈循环：每次会话读取，失败时更新
• 架构护栏：严格的依赖层（Types → Config → Repo → Service → Runtime → UI）
• 可观测性驱动迭代：Agent 利用日志、指标、追踪自主复现 bug

成果：

• 3 人团队，5 个月，100 万行代码（应用逻辑、测试、CI、文档、可观测性）
• 3.5 PR/人/天，吞吐量随团队规模增长而增加

5.3 OpenCode

定位：开源替代方案，48K GitHub stars

与 Claude Code 对比：

注意：2026 年 1 月 Anthropic 封禁了 OpenCode 使用 Claude 消费级 OAuth Token，API Key 仍可用。

5.4 Atomic

定位：开源多引擎 Harness CLI

设计理念：一个 Harness，多个引擎（Claude / OpenCode / Copilot）

四层架构：

┌─────────────────────────────────────────┐
│             Atomic CLI                  │
│  (Workflows, Sub-agents, Graph Engine)  │
├─────────────────────────────────────────┤
│       Event-Driven Streaming Layer      │
├─────────────────────────────────────────┤
│         Unified Client Interface        │
├────────────┬────────────┬───────────────┤
│ Claude SDK │ OpenCode   │ Copilot SDK   │
│            │ SDK        │               │
└────────────┴────────────┴───────────────┘

实现四大支柱：

• 三层上下文系统
• 专业化子 Agent
• 文件系统持久化
• 图执行引擎（编译后的工作流图）

6. Agent Harness 评估基准

6.1 为什么需要评估 Harness？

传统软件失败是响亮的（报错、测试失败）。Agent 失败是静默的：

• 工具调用微妙地错误
• 提取遗漏字段
• 计划漂移
• 语气退化
• 循环次数增加
• 每次运行成本翻倍

6.2 六类测试

6.3 主要评估框架

6.4 关键指标

• 工具正确性（Tool Correctness）：是否调用了正确的工具，参数是否正确
• 工具使用率（Tool Usage）：工具调用效率
• 任务完成度（Task Completion）：是否达成目标
• 任务效率（Task Efficiency）：完成任务的步骤/成本
• 单次解决成本（Cost per Solve）：成功 vs 失败的成本差异（研究发现失败成本是成功成本的 10 倍）

7. 关键洞察与最佳实践

7.1 上下文窗口的"智能区"

Dex Horthy 的发现：

• 智能区（前 ~40%）：专注、准确的推理
• 愚蠢区（超过 ~40%）：幻觉、循环、畸形工具调用、低质量代码

启示：更多 Token ≠ 更智能。过载 Agent 的上下文会让它更差。

7.2 Agent 的时间盲症

Carlini 的发现：Claude "无法感知时间，无人看管时会愉快地花几小时运行测试而非取得进展"。

解决方案：确定性测试子采样（随机 1-10%，但每 Agent 确定，跨 VM 随机）。

7.3 反向压力（Backpressure）

Geoffrey Huntley 的核心概念：

• 上游：确定性设置、一致上下文分配、现有代码模式引导
• 下游：测试、类型检查、Linter、构建、安全扫描拒绝无效工作

原则：你捕获的反向压力越多，能授予的自治权就越多。

7.4 文档即代码（Docs as Code）

OpenAI 的实践：

• AGENTS.md 不是静态文档，而是活的约束系统
• 结构化 docs 目录：maps、执行计划、设计规范
• 机械强制：交叉链接的设计和架构文档通过 Linter 和 CI 验证

7.5 CI 作为 Harness

当 Claude 频繁在实现新功能时破坏现有功能时，解决方案是更严格的 CI 管道——Harness 层解决模型层的问题。

8. 未来趋势：HaaS（Harness as a Service）

8.1 范式转移

从 LLM API（聊天式端点）到 Harness API（可定制运行时）。

8.2 开放 Harness 生态

• Prime Intellect 的 Environment Hub
• 开源 Harness 作为应用原语
• 构建者创建自定义 Harness，用户插入并进一步编辑

8.3 预测

"未来 6 个月内，大多数面向用户的 AI 产品将使用现有 Agent Harness 作为核心用户交互模式。"

Harness 使"Agent Infra"商品化，将努力转移到：

• 针对领域的提示调优
• 专用工具开发
• 上下文优化
• 用户体验设计

9. 给开发者的建议

9.1 何时需要 Harness？

9.2 起步建议

1. 从现有 Harness 开始：Claude Code SDK、OpenCode、Atomic
2. 专注定制：不要从零构建 Harness，而是深度定制现有 Harness
3. 建立评估基准：在投入生产前建立 Cursor Bench 式的内部评估套件
4. 设计上下文架构：不要一股脑塞信息，设计分层加载策略
5. 实施反向压力：测试、类型、Linter 是你的朋友

9.3 关键文件模板

CLAUDE.md / AGENTS.md：

# 项目名

## 概览
一句话描述项目

## 项目结构
| 路径 | 类型 | 用途 |
|-----|------|------|
| `src/` | 目录 | 源代码 |
| `tests/` | 目录 | 测试 |

## 快速参考
### 命令
```bash
npm run dev    # 启动开发服务器
npm test       # 运行测试

架构约束

• 依赖流向：Types → Config → Repo → Service → Runtime → UI
• 禁止跨层调用

---

## 10. 结论

Agent Harness 是 AI 从"能跑 Demo"走向"工业级应用"的关键基础设施。它解决了大模型在可靠性、持久性、安全性方面的固有弱点，让 Agent 真正成为可部署的生产系统。

**核心公式**：
> **优秀的模型 + 糟糕的 Harness = 不可靠的 Agent**
> **优秀的模型 + 优秀的 Harness = 可靠的自治系统**

2026 年，AI 竞争的关键已从"谁的模型更强"转向"谁的 Harness 更成熟"。Harness Engineering 不是权宜之计，而是随着模型能力提升变得更加重要的长期工程。

---

*研究报告整理：小凯*
*日期：2026年3月8日*


#记忆 #小凯 #AI研究 #Agent #Harness