一文搞懂 AI Agent Harness:它是什么,为什么重要,以及开发者需要建立哪些认知?

一文搞懂 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 还需要:

  1. 判断工具是否存在。
  2. 校验参数是否合法。
  3. 检查当前操作是否具有权限。
  4. 执行实际工具。
  5. 处理超时或错误。
  6. 将执行结果反馈给模型。

因此:

模型负责选择或请求工具,执行系统负责校验、执行并反馈结果。

这里有一个关键区别:

模型认为应该执行某个操作,并不代表这个操作一定合法、一定成功,或者一定符合业务规则。

真正的工具执行必须受到可信软件系统的约束。

认知四: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 真正串起来。

相关推荐
Flynt12 小时前
AI 写的 Three.js 大屏,为什么越跑越卡?我在 Node 里复现了它的内存曲线
前端·ai编程·three.js
J船长12 小时前
AI 知识库的主流做法是 RAG,RAG怎么做
ai编程
小虎AI生活12 小时前
哇塞~24小时开机的WorkBuddy免费领,速来
aigc·ai编程
郑世录16 小时前
codex 接本地模型,单次输出卡在 3208 token:一份照着做就能改的完整教程
ai编程
JavaGuide17 小时前
Gemini 真的变强了,写代码做视频的能力接近 Claude Opus5.5 了!
前端·ai编程
qinglongcn17 小时前
四面统一:记忆/Session/观测/Cron
agent·ai编程
qinglongcn17 小时前
从 metadata 键到独立列
agent·ai编程
YanisJiang18 小时前
别只把 AI 聊天当成「又一个网页」:把状态驱动的陪伴内核接到你自己的项目里
ai编程
AI入职记20 小时前
RAG 一个请求吃掉 8 个核,chat 只要 0.16 个
后端·ai编程