一文搞懂 AI Agent Harness:它是什么,为什么重要,以及开发者需要建立哪些认知?
学习 AI Agent 时,有一个概念,无法避免:Harness。
我们经常讨论大模型、Prompt、Function Calling、MCP、Skill、Agent,但如果想真正理解 Codex、Claude Code 这类 AI 编程工具是如何工作的,Harness 是一个绕不开的概念。
它到底是什么?与 Agent 有什么区别?为什么同样的大模型,在不同 AI 工具中的表现可能差别很大?
本文从软件工程的角度,结合 AI 编程工具的实际使用场景,梳理 Harness 的核心原理,以及开发者应该建立的工程认知。
一、Harness 到底是什么?
Harness 原意是"马具、挽具",在 AI Agent 工程中,通常指:
支撑智能体运行的一组执行与控制机制,包括模型调用编排、上下文管理、工具执行、状态维护、安全约束和可观测性等。
可以这样理解:
- LLM(大模型) :负责理解、推理、生成和提出决策建议。
- Agent(智能体) :利用模型(LLM)和工具(指 Agent 可以调用的外部功能或接口),围绕目标执行任务的智能系统。
- Harness(执行框架) :支撑 Agent 运行,负责组织、执行和控制任务过程的工程机制。
例如 Codex、Claude Code 这类 AI 编程工具,背后不只是一个大模型,还需要大量工程系统来支持它工作。
模型提供智能能力,Harness 负责让这些能力在真实软件环境中被安全、可控、可观测地执行。
需要说明的是,Harness 并没有完全统一的行业定义。有些团队将其称为 Agent Runtime,也有些团队将 Harness 理解为包含运行环境、工具、上下文和安全机制的完整执行基础设施。
因此,理解 Harness 的关键不是纠结名称,而是理解它在 Agent 系统中承担的工程职责。
二、Harness 在 AI 系统中处于什么位置?
假设用户向一个 AI 编程工具提出任务:
"帮我修复 Android 项目中的一个 Bug。"
一个简化的系统架构如下:
markdown
用户目标
│
▼
┌────────────────────────┐
│ Agent Harness │
│ │
│ 上下文管理 │
│ 工具管理与执行 │
│ 执行循环 │
│ 安全控制 │
│ 状态管理 │
│ 可观测性 │
└────────────────────────┘
│
│ 模型调用 / 响应
▼
┌────────────────────────┐
│ LLM │
│ │
│ 理解、推理、决策 │
└────────────────────────┘
│
│ 工具调用请求
▼
┌────────────────────────┐
│ Agent Harness │
│ │
│ 校验 → 执行 → 反馈 │
└────────────────────────┘
│
▼
继续执行 / 完成
这张图表达的是一次典型的模型调用与工具执行过程。实际运行中,Harness 与 LLM 可能多次交互,而不是简单地自上而下执行一次。
Harness 主要负责六类工作:
| 核心模块 | 主要职责 |
|---|---|
| 上下文管理 | 管理历史消息、相关文件、上下文压缩 |
| 工具管理 | 文件读取、代码修改、终端执行、搜索 |
| 执行循环 | 模型决策、工具执行、结果反馈 |
| 安全控制 | 权限、沙箱、人工确认 |
| 状态管理 | 任务进度、检查点、恢复 |
| 可观测性 | 日志、耗时、Token、错误 |
这里最重要的认知是:
大模型具备推理能力,并不意味着它天然具备执行真实任务的能力。
从模型能够分析问题,到系统能够完成复杂任务,中间还需要一整套工程机制。
Harness 正是这些机制的重要载体。
三、通过 Codex 理解 Harness 的工作过程
假设我们向 Codex 提出一个任务:
"检查我的 Android 项目,修复登录页面的崩溃问题。"
一个典型的执行过程如下。
第一步:准备上下文
Harness 将用户任务、项目规则和当前上下文发送给大模型。
模型需要知道:
- 用户希望解决什么问题。
- 当前项目是什么。
- 有哪些可用工具。
- 可以执行哪些操作。
- 存在哪些限制。
第二步:模型决定下一步行动
模型分析任务后,认为需要读取 LoginActivity.kt。
此时,模型通常不是直接操作文件系统,而是提出工具调用请求。
第三步:Harness 执行工具
Harness 接收到工具调用请求后,检查权限和参数,并调用文件读取工具。
读取成功后,将文件内容返回给模型。
第四步:模型分析并提出修改
模型根据读取到的代码分析崩溃原因,决定需要修改哪些代码。
Harness 执行允许的修改操作。
第五步:运行测试
代码修改完成后,模型可能决定执行 Gradle 测试。
Harness 负责运行测试命令,并收集执行结果。
第六步:根据结果继续执行
如果测试失败,模型可以继续分析错误并尝试修复。
如果测试通过且任务目标已经满足,则结束任务并返回结果。
整个过程可以概括为:
模型决策 → Harness 执行 → 结果反馈 → 模型继续决策。
这也是 Agent Loop(智能体执行循环)的基本思想。
需要注意,以上是概念化的执行过程,用于说明 Agent Harness 的工作机制,并不代表 Codex 内部实现的全部细节。
四、开发者必须建立的 5 个核心认知
理解 Harness,不只是记住一个定义,更重要的是建立下面五个工程认知。
认知一:Agent 不是简单地调用一次 LLM
普通 AI 聊天通常是:
用户 → LLM → 回答
而具备工具调用能力的 Agent,其典型执行过程是:
用户 → LLM → 工具 → 结果 → LLM → 工具 → ... → 完成
这意味着 Agent 可以根据任务需要,持续采取行动,而不只是生成一次回答。
Harness 负责管理这个过程,包括:
- 执行循环。
- 最大执行步数。
- 超时控制。
- 失败重试。
- 结束条件。
不过,并不是所有 Agent 都必须进行多轮循环。对于简单任务,Agent 也可能在一次模型调用后直接完成。
是否需要多轮执行,取决于任务复杂度和系统设计。
如果缺少合理的执行控制,Agent 可能反复执行无效操作,造成成本浪费,甚至产生安全风险。
认知二:从 Prompt Engineering 到 Context Engineering
Prompt Engineering(提示词工程)主要关注如何设计模型指令,让模型更准确地理解和执行任务。
Context Engineering(上下文工程)则关注一个更广泛的问题:
模型在每一次执行时,究竟应该看到哪些信息?
除了 Prompt,还可能包括:
- 历史对话。
- 当前任务目标。
- 项目规则。
- 相关代码。
- 工具执行结果。
- 外部知识。
- 已完成的任务状态。
例如,一个 Codex 对话持续很长时间,逐渐接近模型的上下文窗口限制。
此时,Harness 可以采用一些常见策略:
1. 上下文压缩(Compaction)
将较早的对话整理为摘要,尽量保留重要目标、约束和已完成工作。
2. 选择性上下文(Context Selection)
不把整个项目的全部文件发送给模型,而是选择当前任务相关的代码和资料。
3. 外部持久化(Persistent State)
将重要状态保存到文件或数据库,在后续任务中按需重新读取。
但需要注意:
上下文压缩并不能保证完全没有信息损失。
因此,对于长期运行的 Agent,重要事实最好有可以重新读取的持久化来源,而不是只依赖压缩后的对话摘要。
Prompt Engineering 和 Context Engineering 并不是对立关系。
Prompt 本身就是上下文的一部分,而 Context Engineering 关注的是如何管理模型需要的全部信息。
对于复杂 Agent 系统,上下文管理往往直接影响任务成功率、响应质量和 Token 成本。
认知三:Function Calling 不等于工具执行成功
假设我们为模型提供了一个名为 run_tests 的工具。
模型可能返回类似下面的工具调用信息:
json
{
"name": "run_tests",
"arguments": {
"module": "app"
}
}
这是简化后的示例,具体 API 的工具调用消息结构可能不同。
这里需要理解:
Function Calling 返回的是模型提出的工具调用请求,并不意味着工具已经执行。
接下来,Harness 还需要:
- 判断工具是否存在。
- 校验参数是否合法。
- 检查当前操作是否具有权限。
- 执行实际工具。
- 处理超时或错误。
- 将执行结果反馈给模型。
因此:
模型负责选择或请求工具,执行系统负责校验、执行并反馈结果。
这里有一个关键区别:
模型认为应该执行某个操作,并不代表这个操作一定合法、一定成功,或者一定符合业务规则。
真正的工具执行必须受到可信软件系统的约束。
认知四:Harness 必须建立安全边界
假设 Agent 决定执行下面这条命令:
bash
rm -rf ~/Documents
一个成熟的 Harness 不应该仅仅因为模型提出请求,就无条件执行。
它需要根据预先定义的安全策略进行判断。
常见的安全机制包括:
- 沙箱隔离。
- 文件访问范围限制。
- 命令执行权限。
- 敏感操作人工确认。
- 工具调用审计。
这里还涉及一个重要的 AI 安全问题:
Prompt Injection(提示词注入)。
例如,Agent 在读取网页或项目文件时,可能遇到恶意内容,试图诱导模型执行不安全的操作。
这些内容来自不可信的数据源,不能直接获得系统指令级别的权限。
因此,Harness 需要结合权限控制、信任边界和工具执行策略,降低不可信内容影响实际操作的风险。
需要注意,单纯依靠 Prompt 告诉模型"不要执行危险命令"并不足以构成可靠的安全边界。
模型可以提出行动建议,但最终的执行权限必须由可信的软件系统控制。
认知五:Harness 本身也需要评测
很多人讨论 AI 效果时,只关注模型回答是否正确。
但对于 Agent 系统,仅仅评测回答质量是不够的。
还需要评测整个任务是否真正完成。
例如,一个 AI 编程 Agent 生成了看起来正确的代码,并不代表 Bug 已经修复。
我们还需要检查:
- 任务完成率。
- 工具调用成功率。
- 平均执行步数。
- Token 和 API 成本。
- P95 任务耗时。
- 错误恢复率。
- 越权操作发生率。
假设我们对 Harness 进行了改造,引入更好的上下文管理机制。
如何证明改造有效?
可以使用同一批测试任务、相同模型、相同工具环境和相同评测标准,对比改造前后的任务成功率、耗时和成本。
由于模型输出可能存在波动,必要时还应该进行多次测试,避免根据单次结果得出结论。
这就是从"会调用 AI API",走向"具备 AI 系统工程能力"的关键。
五、Harness、Agent、MCP、Skill、Workflow 有什么区别?
这些概念经常一起出现,但并不属于同一个层次。
| 概念 | 核心职责 |
|---|---|
| LLM | 提供语言理解、推理与生成能力 |
| Agent | 围绕目标选择行动、使用工具 |
| Harness | 运行并约束 Agent 的执行过程 |
| MCP | 标准化连接外部工具和数据源的协议 |
| Skill | 可复用的任务指导、知识或操作规范 |
| Workflow | 预先定义或编排的业务执行流程 |
需要补充的是:
MCP(Model Context Protocol)是一种用于连接 AI 应用与外部工具、数据源的开放协议,并不是 Agent 必须使用的组件。
Skill 在不同产品中的实现形式可能不同,通常用于封装可复用的任务说明、操作步骤或专业知识,并不是所有 AI 系统都遵循同一种 Skill 标准。
继续使用 Android Bug 修复的例子:
- LLM:分析代码,判断可能的崩溃原因。
- Agent:决定先读取日志还是搜索代码。
- Harness:管理执行循环、文件权限和测试。
- MCP:可以用于连接外部开发工具或服务。
- Skill:提供 Android 崩溃排查规范。
- Workflow:规定修复完成后必须运行测试和代码审核。
这些技术可以组合使用,并不是相互替代的关系。
六、开发者,需要掌握到什么程度?
可以将 Harness 的学习分成三个等级。
Level 1:理解原理
能够解释:
- LLM、Agent、Harness 的关系。
- Agent Loop 如何运行。
- Function Calling 如何工作。
- 上下文管理为什么重要。
- Harness 为什么需要安全控制。
这是 AI 应用开发的基础认知。
Level 2:能够实现
能够独立开发一个简单的 Agent Harness。
至少包括:
- 模型 API 接入。
- 工具注册和调用。
- Agent 执行循环。
- 基础上下文管理。
- 日志记录。
- 错误处理。
不一定需要复杂框架。
使用 Python、Kotlin 或其他熟悉的语言,都可以实现一个最小版本。
通过实际开发,能够真正理解模型与执行系统之间的协作关系。
Level 3:能够负责生产系统
需要进一步考虑:
- 多用户隔离。
- 权限体系。
- 任务恢复。
- 模型路由。
- 效果评测。
- 成本监控。
- 故障降级。
- 安全审计。
这个阶段的重点已经不再是"如何调用模型",而是:
如何让 AI 系统在真实业务环境中稳定、安全、可控地运行。
对于有多年软件研发经验的技术负责人,建议至少达到 Level 2,并具备 Level 3 的架构设计认知。
七、总结
Harness 是理解 AI Agent 工程化非常重要的一个概念。
如果只记住一句话:
大模型提供核心推理与生成能力,而 Harness 通过上下文管理、工具执行、状态控制、安全约束和可观测性,将模型能力转化为可交付、可评测的 Agent 系统。
理解 Harness 后,我们会发现:
开发 AI Agent,并不只是调用一个 LLM API,也不只是设计几个 Prompt。
它本质上仍然是一项系统工程。
我们需要考虑执行流程、工具设计、权限管理、上下文、错误恢复、日志、监控和效果评测。
这些恰恰与传统软件工程有着非常紧密的联系。
对于希望从客户端开发、后端开发逐步转向 AI 应用开发或技术负责人的工程师来说,Harness 是一个很好的切入点。
刚学习,下一步,最值得做的事情,是亲手实现一个最小 Agent Harness:使用一个 LLM、两个工具和一个执行循环,把 Prompt、Function Calling、Context、Agent 与 Harness 真正串起来。