Agent Harness 深度研究报告

完全由OpenClaw + Kimi-k2.5写成

执行摘要

Agent Harness（智能体驾驭系统）是2025-2026年AI领域涌现的关键架构概念，它代表了一层围绕大语言模型（LLM）的运行时基础设施，负责管理Agent的生命周期、上下文、工具调用和状态持久化。本报告通过分析15+个权威来源，深入研究了Agent Harness的定义、核心架构、主流实现以及与Agent Framework的区别。

核心发现：

• Agent Harness是"除模型本身之外的一切"——它提供工具执行、内存管理、错误恢复和状态持久化等能力
• 业界已从"模型-centric"转向"基础设施-centric"设计，认识到再好的模型也需要健壮的Harness才能发挥潜力
• OpenAI、Anthropic等前沿实验室已独立收敛到相同的洞察：更简单的Harness配合更好的模型优于复杂的编排
• APEX-Agents基准测试显示，即使是最先进的模型在专业任务上的Pass@1成功率仅为24%，主要失败原因是编排问题而非知识缺陷

1. Agent Harness 概述

1.1 什么是 Agent Harness

Agent Harness是包裹在大语言模型外层的软件基础设施，负责处理"除模型本身之外的一切"。正如一位AI架构师所定义的："Agent Harness是围绕LLM的完整架构系统，管理从意图捕获到规范、编译、执行、验证和持久化的整个上下文生命周期"^[1]。

简而言之，Harness是连接AI模型与外部世界的桥梁，使其能够：

• 使用工具（Tools）与外部环境交互
• 在步骤之间记住信息（Memory）
• 执行复杂的多步骤任务（Planning & Execution）
• 从错误中恢复（Error Recovery）

1.2 为什么需要 Agent Harness

直接调用OpenAI或Claude的API并不等于拥有了一个Agent。裸模型（Raw Model）存在以下问题^[2]：

Anthropic在其工程博客中指出："长时运行Agent的核心挑战是它们必须在离散的会话中工作，每个新会话开始时都失去了对之前发生的事情的记忆。这就像一家软件项目由轮班工作的工程师组成，每个新工程师到达时都对上一班发生的事情毫无记忆。"^[3]

2. 核心概念与定义

2.1 技术定义

根据多个权威来源的综合定义，Agent Harness是^[4][5][6]：

Agent Harness = 控制器循环 + 工具运行时 + 上下文/状态管理 + 安全护栏 +（可选）评估

具体而言，它控制以下五个方面：

1. 上下文管理（Context Management）：什么信息进入模型的上下文窗口、顺序如何、什么被逐出
2. 工具选择（Tool Selection）：模型可以调用哪些能力，这些接口如何设计
3. 错误恢复（Error Recovery）：系统如何处理失败的工具调用、推理死胡同和重试逻辑
4. 状态管理（State Management）：Agent如何在回合、会话和上下文窗口边界之间持久化进度
5. 外部记忆（External Memory）：信息如何存储和检索到超出上下文窗口的范围

2.2 Harness 的工作原理

典型的Agent Harness工作流程如下^[1][6]：

1. 意图捕获与编排（Intent Capture & Orchestration）
   ↓
2. 工具调用执行（Tool Call Execution）
   - 监控模型输出，识别工具调用
   - 暂停文本生成，执行请求的操作
   - 将结果反馈回模型上下文
   ↓
3. 上下文管理与记忆（Context Management & Memory）
   - 管理持久化任务日志
   - 上下文压缩（Compaction）
   - 确保模型始终拥有正确的信息
   ↓
4. 结果验证与迭代（Result Verification & Iteration）
   - 检查输出格式
   - 运行测试用例
   - 必要时提示模型修复问题
   ↓
5. 重复直到任务完成

2.3 两种常见含义

Agent Harness在实际使用中有两种常见含义^[6]：

• 运行时Harness（Runtime Harness）：用于构建/操作真实Agent（编码Agent、研究Agent、运维Agent）
• 评估Harness（Evaluation Harness）：用于运行任务套件并跨模型/变体测量性能

3. Agent Harness vs Agent Framework

3.1 概念区分

这是业界最容易混淆的两个概念。根据Salesforce的定义^[7]：

简单类比：模型是引擎，Harness是汽车。行业多年来一直在争论谁拥有最好的引擎，但几乎没有人建造一辆能保持在道路上的汽车。

3.2 三层架构模型

现代Agent系统由三个互补层组成^[8][9]：

┌─────────────────────────────────────────────────────────┐
│                    Agent Harness                         │
│         (评估、测试、验证、预置工具和工作流)               │
├─────────────────────────────────────────────────────────┤
│                    Agent Runtime                         │
│      (执行引擎、状态持久化、容错、重试机制)                │
├─────────────────────────────────────────────────────────┤
│                   Agent Framework                        │
│      (开发框架、组件库、蓝图定义、工具编排)                │
└─────────────────────────────────────────────────────────┘

Agent Framework：提供构建Agent的开发工具包，定义提示词、工具调用和整体Agent循环。它是"蓝图"。代表：LangChain、Microsoft Semantic Kernel。

Agent Runtime：处理状态、持久化和多步骤执行的执行引擎，关注可靠性和编排。代表：LangGraph、 temporal.io。

Agent Harness：高层系统，包装框架和运行时，提供开箱即用的默认配置和测试套件。代表：Claude Agent SDK、DeepAgents。

3.3 关键区别总结

根据LangChain创始人的观点^[10]：

"像Agents SDK（以及早期的LangChain、CrewAI等）这样的框架，既不是声明式的也不是命令式的，它们只是封装。它们提供一个Agent封装（一个Python类），里面封装了很多用于运行Agent的内部逻辑。它们算不上真正的编排框架，仅仅是一种封装。这些封装最终会让你非常非常难以理解或控制到底在每一步传递给LLM的具体内容是什么。"

4. 主流实现对比

4.1 实现概览

4.2 Claude Agent SDK (Anthropic)

Anthropic在2025年2月发布的Claude Code是一个重要的里程碑。关键洞察^[3][11]：

• 提供文件系统导航（读、写、搜索、列出）和命令执行能力
• 使用上下文压缩（Compaction）策略允许Agent在不耗尽上下文窗口的情况下继续工作
• 采用Initializer Agent + Coding Agent的双部分解决方案处理长时任务
• 通过claude-progress.txt文件和git历史实现会话间的状态桥接

Initializer Agent：第一个会话使用专门提示词设置初始环境（init.sh脚本、进度文件、初始git提交）

Coding Agent：每个后续会话要求模型进行增量进展，然后留下结构化更新

4.3 LangGraph (LangChain)

LangGraph是一个低级别编排框架，用于构建、管理和部署长时运行的、有状态的Agent^[12]：

核心优势：

• 持久化执行：Agent可以持续通过故障运行，自动从上次中断的地方恢复
• 人机协作（Human-in-the-loop）：在任何执行点检查和修改Agent状态
• 全面记忆：短期工作记忆用于持续推理，长期持久记忆跨会话
• 调试与可观测性：通过LangSmith可视化执行路径和状态转换

设计理念：将Agent系统表示为节点和边的图结构，节点代表工作单元，边代表转移关系。虽然图结构是声明式的，但图的遍历路径可以完全动态。

4.4 OpenAI Agents SDK

OpenAI在2025-2026年推广的"Harness Engineering"概念^[13][14]：

OpenAI团队进行了一项实验：在五个月内，使用0行手动编写的代码构建和发布了一个软件产品的内部测试版。该产品现在有超过100万行代码，由3名工程师使用Codex驱动，平均每天每人3.5个PR。

关键学习：

• 工程师的主要工作不再是编写代码，而是设计环境、指定意图和构建反馈循环
• 当Agent挣扎时，将其视为信号：识别缺少什么（工具、护栏、文档），并让Codex自己编写修复
• 上下文管理是最大的挑战之一——给Codex一张地图，而不是1000页的说明书
• 使用结构化文档目录代替单一的AGENTS.md大文件

4.5 AutoGen (Microsoft)

AutoGen是一个用于构建AI Agent和应用的开源框架^[15]：

架构层次：

• AutoGen Studio：基于Web的UI，无需编写代码即可原型设计
• AgentChat：构建对话式单/多Agent应用的编程框架
• Core：事件驱动编程框架，用于构建可扩展的多Agent系统
• Extensions：与外部服务或其他库交互的组件实现

核心特点：

• 支持确定性/动态Agent工作流
• 多Agent协作研究
• 分布式Agent支持多语言应用
• 通过McpWorkbench支持Model-Context Protocol (MCP)服务器

4.6 CrewAI

CrewAI是一个面向企业的多Agent平台^[16]：

核心定位：

• 使企业能够操作执行复杂任务的AI Agent团队
• 支持自主、可靠且完全可控的执行

CrewAI AMP（Agent Management Platform）：

• 编排：高级AI Agent编排能力，Agent构建者专注于"做什么"而非"如何做"
• 构建与集成：可视化编辑器、AI辅助、API和自定义工具
• 观测与优化：实时追踪、Agent训练、自动和人在回路训练
• 管理与扩展：集中管理、监控、无服务器容器

企业案例：

• DocuSign：加速潜在客户首次接触时间75%
• General Assembly：课程设计流程开发时间减少90%
• PwC：代码生成准确率从10%提升到70%

4.7 对比分析

5. 架构设计分析

5.1 核心组件

根据多个来源的综合分析^[6][8][9]，一个完整的Agent Harness包含以下核心组件：

┌────────────────────────────────────────────────────────────┐
│                      Agent Harness                          │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│  Controller │   Tool      │   Context   │   Guardrails     │
│    Loop     │  Runtime    │  Manager    │   & Safety       │
├─────────────┴─────────────┴─────────────┴──────────────────┤
│                     State Store                             │
│              (Persistent Memory & Progress)                 │
└────────────────────────────────────────────────────────────┘

1. 控制器循环（Controller Loop）

• 重复调用模型的核心循环
• 实现Plan → Act → Observe → Update → Repeat的迭代模式

2. 工具运行时（Tool Runtime）

• 执行Shell命令、文件操作、Web API调用等
• 管理工具注册、调用、超时和重试

3. 上下文管理器（Context Manager）

• 决定什么信息进入上下文窗口
• 实现滑动窗口、关键信息摘要、噪音过滤

4. 安全护栏（Guardrails & Safety）

• 权限控制和验证
• 死循环熔断机制（MAX_ITERATIONS）
• 人机协作确认（Human-in-the-loop）

5. 状态存储（State Store）

• 持久化Agent进度
• 支持会话恢复和状态重放

5.2 关键设计模式

5.2.1 CodeAct 范式

CodeAct是一个重要的设计范式转变^[11]。与传统工具调用（输出JSON指定工具名称和参数）不同，CodeAct要求模型编写可执行的Python代码来执行动作。

优势：

• LLM在海量真实代码上训练，对Python更熟悉
• 代码允许任意控制流：循环、条件、重试逻辑
• 可以在单个动作步骤中动态组合多个工具调用

性能提升：在17个模型的多项基准测试中，CodeAct比传统工具调用成功率提高多达20%。

Hugging Face的smolagents、Cloudflare的Code Mode和Anthropic的Programmatic Tool Calling都采用了这一范式。

5.2.2 上下文压缩（Context Compaction）

长时运行Agent的关键技术^[3]：

• 定期汇总会话历史，将50页详细日志浓缩为几个关键要点
• 使用RAG（检索增强生成）只在需要时注入特定文档或数据点
• 保持推理过程专注和高效

5.2.3 增量进展模式

Anthropic推荐的增量进展模式^[3]：

1. 初始化阶段：创建功能列表文件（feature list），所有功能初始标记为"未通过"
2. 单次专注：每次会话只处理一个功能
3. 干净状态：要求模型在会话结束时提交git并写入进度摘要
4. 快速上手：每个新会话首先读取git日志和进度文件了解最近工作

5.3 架构权衡

工具数量 vs 性能

Vercel的反直觉发现^[17]：

• 旧架构：15个专业工具 → 80%成功率，274.8秒执行时间
• 新架构：2个通用工具（bash + SQL） → 100%成功率，77.4秒执行时间

洞察：专业工具在模型已有能力使用通用接口时会成为瓶颈。模型花费更多Token选择工具而不是执行任务。

抽象级别 vs 控制能力

LangChain创始人指出的权衡^[10]：

• 高级抽象（如Agent类）降低入门门槛
• 但封装最终会让你难以理解或控制每一步传入LLM的具体内容
• 最佳方式是将高级抽象视为Keras——提供简化入门的上层抽象，但确保它们构建在底层框架之上

6. 应用场景与最佳实践

6.1 典型应用场景

6.2 最佳实践

基于OpenAI、Anthropic、Vercel等团队的工程实践^[3][13][17]：

6.2.1 环境设计原则

1. 提供地图而非百科全书

   • 使用简短的AGENTS.md（约100行）作为目录
   • 详细知识库存储在结构化的docs/目录中
   • 实现渐进式披露：Agent从小的、稳定的入口点开始，然后按需获取更多信息

2. 将知识推入仓库

   • 任何Agent在运行时无法访问的上下文都等于不存在
   • 将Slack讨论、会议决策等推入版本控制的文档
   • 使用可执行计划和决策日志

3. 强制执行机制

   • 使用专用linter和CI作业验证知识库是最新的
   • 定期运行"文档维护"Agent扫描过时文档

6.2.2 上下文管理最佳实践

1. 分离静态规则和动态技能

   • Rules（静态）：始终生效的准则，如代码风格规范
   • Skills（动态）：按需加载的能力，避免污染上下文窗口

2. 自主上下文获取

   • 给Agent配备grep或语义搜索工具
   • 让Agent根据需求自己查找相关代码（RAG）

3. 上下文压缩策略

   • 滑动窗口：仅保留最新的N轮对话
   • 摘要替换：触发轻量级模型对旧历史进行总结
   • 噪音过滤：截断或折叠冗长的中间执行日志

6.2.3 工具设计原则

1. 优先使用通用工具

   • 使用bash、cat、find、ls等标准Unix工具
   • 这些与模型的训练数据更匹配

2. 简化工具接口

   • 减少工具数量，提高可靠性
   • 让模型通过组合简单工具完成复杂任务

3. 提供清晰的工具描述

   • 不准确或模糊的工具描述是Agent失败的常见原因

6.2.4 可靠性保障

1. 死循环熔断

   • 设定MAX_ITERATIONS（如10次）
   • 防止Agent在一个bug上无限尝试

2. 人机协作

   • 对高危操作（删除文件、提交代码）请求确认
   • 允许用户实时影响Agent（编辑工具参数、审批调用）

3. 容错机制

   • 使用持久化工作流和可配置重试
   • 支持从故障点恢复而非从头开始

6.2.5 评估与优化

1. 构建评估套件

   • 定义评估数据集
   • 自动优化Agent配置

2. 流式传输与可观测性

   • 启用Token流、节点更新流
   • 捕获详细运行时指标

3. 回归测试

   • 在部署前运行回归套件
   • 检测提示词更新后的性能退化

6.3 技术栈推荐

根据场景选择框架^[2]：

7. 发展趋势

7.1 从模型-centric到基础设施-centric

2025年中期之前，组织追求更强大的前沿模型。到2026年，行业意识到即使最先进的模型也无法克服缺乏Agent脚手架的问题^[7]。

关键洞察：在达到一定能力阈值后，改进Harness比更换模型产生更好的回报。

7.2 Harness Engineering 的兴起

"Harness Engineering"作为一个新兴工程学科正在形成^[13][14]：

• 工程师的主要工作从编写代码转向设计环境、指定意图和构建反馈循环
• 当Agent挣扎时，不是"再试一次"，而是"缺少什么能力，如何让它对Agent可理解和可执行"

7.3 三层模型的标准化

Agent Framework → Runtime → Harness 的三层架构正在成为行业标准^[8][9]：

• 类似于软件工程中的 Code → Runtime → CI/Test Harness 模式
• 这种分层模型将成为构建企业级Agentic工作流的标准模式

7.4 简化Harness的趋势

多个独立团队（OpenAI、Anthropic、Manus）已收敛到相同洞察^[17]：

• 更简单的Harness配合更好的模型优于复杂的编排
• 减少工具数量，使用通用接口（bash、文件系统）
• 复杂的编排往往导致更多失败点

7.5 技术栈的收敛

随着编码越来越侧重于引导代码生成而非直接输入，AI可能推动我们走向更少的技术栈^[14]：

• 开发者口味在细节层面的重要性降低
• 可能优先选择具有良好Harness可用的栈
• 代码库结构和拓扑可能成为新的抽象层

7.6 未来展望

1. Harness as a Service (HaaS)：Agent Harness可能成为一种可订阅的服务，提供开箱即用的可靠运行时环境

2. 标准化协议：Model Context Protocol (MCP) 等标准化协议将促进不同Harness之间的互操作性

3. 自适应Harness：能够根据任务类型和模型能力自动调整配置的智能化Harness

4. 领域特定Harness：针对特定行业（法律、医疗、金融）优化的专用Harness

8. 结论

Agent Harness代表了AI应用架构的重要演进。本报告通过分析15+个权威来源，得出以下核心结论：

8.1 关键发现

1. Harness是生产级Agent的关键：裸模型不足以构建可靠的Agent系统。APEX-Agents基准显示，即使是最先进的模型在专业任务上成功率仅24%，主要失败源于编排问题而非知识缺陷。

2. 模型与Harness的正确关系：模型是引擎，Harness是汽车。行业已从追求更好的引擎转向建造能在道路上行驶的汽车。

3. 三层架构是行业标准：Framework（构建）→ Runtime（执行）→ Harness（评估）的分层模型正在成为标准。

4. 简化优于复杂化：反直觉的是，减少工具数量、使用通用接口、简化Harness结构往往产生更好的结果。

5. Harness Engineering是一门新学科：工程师的角色正在从编写代码转向设计环境和反馈循环。

8.2 实践建议

对于希望采用Agent Harness的组织：

1. 不要从零开始：优先考虑成熟的Harness解决方案（如Claude Agent SDK、LangGraph）

2. 重视上下文管理：投入时间设计上下文策略，这是Agent可靠性的关键决定因素

3. 建立评估体系：在部署前建立系统的评估和回归测试机制

4. 渐进式采用：从简单场景开始，逐步积累Harness工程经验

5. 关注基础设施：在模型选择之外，同等重视Harness的设计和优化

8.3 展望未来

Agent Harness概念虽然还处于早期阶段，但已经显示出成为AI基础设施核心组件的潜力。随着更多组织从实验转向生产部署，对健壮、可扩展、可观测的Harness的需求将持续增长。 Harness Engineering可能成为软件工程的一个专门分支，就像DevOps和SRE一样。

参考资料

报告生成时间：2026年3月3日
研究来源：17个权威技术博客、工程文档和学术资源
语言：中文

1. Parallel. "What is an agent harness?" https://parallel.ai/articles/what-is-an-agent-harness ↩ ↩

2. 掘金. "AI协作核心 - Agent Harness". https://juejin.cn/post/7596710680897552390 ↩ ↩

3. Anthropic. "Effective harnesses for long-running agents." https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents ↩ ↩ ↩ ↩ ↩

4. AI Assisted Software Development. "Agentic Harness." https://ai-assisted-software-development.com/agentic-harness/ ↩

5. Salesforce. "What Is an AI Agent Harness?" https://www.salesforce.com/agentforce/ai-agents/agent-harness/ ↩

6. Dev.to/epappas. "The Agent Harness Is the Architecture." https://dev.to/epappas/the-agent-harness-is-the-architecture-and-your-model-is-not-the-bottleneck-3bjd ↩ ↩ ↩ ↩

7. Salesforce. "Agent Harness: The Infrastructure for Reliable AI." ↩ ↩

8. Analytics Vidhya. "Agent Frameworks vs Runtime vs Harnesses." https://www.analyticsvidhya.com/blog/2025/12/agent-frameworks-vs-runtimes-vs-harnesses/ ↩ ↩ ↩

9. C-Sharp Corner. "Understanding Agent Frameworks, Runtimes, and Harnesses." https://www.c-sharpcorner.com/article/understanding-agent-frameworks-runtimes-and-harnesses-in-modern-ai-systems/ ↩ ↩ ↩

10. 李乾坤博客. "agent框架." https://qiankunli.github.io/2025/04/26/agent_framework.html ↩ ↩

11. AgileLab. "The Rise of the Agent Harness." https://agilelab.substack.com/p/the-rise-of-the-agent-harness ↩ ↩

12. LangGraph GitHub. https://github.com/langchain-ai/langgraph ↩

13. OpenAI. "Harness engineering: leveraging Codex in an agent-first world." https://openai.com/index/harness-engineering/ ↩ ↩ ↩

14. Martin Fowler. "Harness Engineering." https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html ↩ ↩ ↩

15. AutoGen Documentation. https://microsoft.github.io/autogen/stable/ ↩

16. CrewAI. https://www.crewai.com/ ↩

17. Dev.to/epappas. Vercel案例研究部分。 ↩ ↩ ↩