Harness Engineering：AI Agent 可靠性的工程底座Harness Engineering：AI

Harness Engineering：AI Agent 可靠性的工程底座

引言：给 AI Agent 搭建一座可控的试验场

比如我们要开发一套汽车自动驾驶系统，肯定不会直接把一辆还没充分验证的车开上真实道路，让它在复杂城市交通中自由发挥。相反，我们会先搭建仿真环境、测试跑道、故障注入系统和评测指标体系：同一段路况可以反复回放，同一个危险场景可以稳定复现，每一次刹车、转向和误判都能被完整记录。

AI Agent 的工程化也面临同样的问题。一个 Agent 看起来能对话、能调用工具、能写代码、能分析数据，但这并不意味着它已经可以进入生产环境。我们还需要回答一系列更工程化的问题

它调用工具的过程是否可以复现，而不是那么的黑盒？
它失败时能不能定位原因？

如果我们在 Agent 执行过程中两眼一抹黑，我们就对 Agent 的进一步优化无从下手。

而解决这些问题的工程体系，就是 Harness Engineering。它解决的是如何把 Agent 放进一个可控、可观测、可复现、可评测的工程环境中，从而让 Agent 从"能跑"走向"可验证地可靠"。

一、概念

什么是 Harness Engineering？

Harness 原本在软件工程中常见于 Test Harness，用于驱动被测系统运行、提供输入、捕获输出、模拟依赖并判断结果的一套测试工具。而在 AI Agent 语境下，Harness 被进一步扩展：它不仅用于测试，还用于运行、评测、回放、安全隔离、数据采集和实验管理。

可以把 Harness Engineering 理解为：

为 Agent 构建一套外部工程壳，使其可以在受控环境中接收任务、调用工具、访问数据、产生轨迹、接受评测，并在失败时可以被复现和分析。

这里的"壳"并不是简单包装一层 API，而是一套完整的工程系统，通常包括：

| 组件 | 功能 | | --- | --- | | 工具桩与模拟器（Tool Mocks / Simulators） | 模拟外部 API、搜索结果、网页环境、代码仓库或业务系统 | | 执行****沙箱（Execution Sandbox） | 隔离文件系统、网络、权限和副作用 | | 轨迹记录器（Trace Recorder） | 记录模型输入输出、工具调用、状态变化和错误 | | 评测器（Evaluator） | 根据规则、模型裁判或人工标注判断任务是否成功 | | 回放系统（Replay System） | 用同一任务和同一环境复现历史行为 |

简单来说，Harness Engineering 关注的是 Agent 的行为能不能被系统化地驱动、捕获、验证和治理。

Harness 就是"驾驭"

我们工程上不会去改模型本身，模型更像是地基，工程上真正能做的是在模型上层搭一套工程系统，让 AI 更好地完成任务。这个系统包括：

Prompt
Tool
Memory
Skill
Agent Loop
Trace、Eval、Replay 和 bad case 回归

Trace 让我们知道 Agent 到底做了什么，Eval 让我们知道它做得好不好，Replay 让我们能复现问题，bad case 分析让我们知道该优化 Prompt、Tool、Memory、Skill 还是 Loop。

**更准确地说，Harness Engineering 不是某一个单点技术，而是一套围绕 Agent 的工程化驾驭体系。Agent Loop、**ReAct 等是实现 Harness 的方法，不等同于 Harness 本身。

Harness 与 Agent Loop、Eval、Observability 的关系

Harness Engineering 经常和 Agent Loop、评测系统、可观测性系统放在一起讨论，但它们的职责并不完全相同。

| 对比维度 | Harness Engineering | Agent Loop | Evaluation | Observability | | --- | --- | --- | --- | --- | | 核心问题 | 如何构建可控的运行与验证环境 | Agent 如何一步步推进任务 | 结果和过程是否达标 | 系统运行时发生了什么 | | 作用范围 | 覆盖测试、运行、回放、评测、安全 | 主要覆盖任务执行过程 | 主要覆盖质量判断 | 主要覆盖日志、指标、Trace | | 输入 | 标准任务、环境夹具、工具模拟、真实流量 | 用户目标、状态、工具结果 | 轨迹、输出、参考答案 | 请求、日志、指标、事件 | | 输出 | 可复现实验、评测报告、回放轨迹 | 下一步动作或最终答案 | 分数、标签、失败原因 | Trace、Dashboard、告警 | | 典型场景 | 离线回归、能力验收、沙箱演练 | 在线任务执行 | 模型或 Agent 质量评估 | 生产故障定位 |

成熟的 Agent 系统通常不是只拥有某一个组件，而是把这几者组合起来。

二、Harness 解决了什么问题？

Harness Engineering 的价值，不在于让 Agent 变得更聪明，而在于让 Agent 的聪明可以被验证、约束和****持续改进。

1. Agent 的不可复现问题

LLM 和 Agent 系统天然存在不确定性：

Prompt 中的上下文可能因为裁剪策略而变化
多步任务中前一步的小差异会放大成后续的大差异

没有 Harness，工程师很难复现用户反馈的问题："昨天 Agent 明明给了错误答案，今天同样问题又对了。"这种不可复现会严重拖慢调试和迭代。

Harness 的解法是把任务运行所依赖的关键变量固定下来（开发测试阶段）：

• 固定输入任务 • 固定模型版本和参数 • 固定工具返回或使用录制的工具快照 • 固定初始状态和 Memory • 固定文件系统与数据库快照 • 记录完整 Trace，支持回放

这样，一次失败就不再是转瞬即逝的黑箱现象，而是可以反复运行、逐步定位的工程样本。

2. 能力退化不可见问题

Agent 系统经常会更新：

更换模型
修改系统 Prompt
新增或删除 Skill

这些变化可能会提升某些场景，但也可能悄悄破坏其已有能力。如果没有 Harness，团队往往只能等线上用户反馈才知道系统退化。

Harness 的价值是建立回归测试集：

# 每次发布前自动运行 regression_suite.run() if regression_suite.fail_rate > threshold: block_deployment()

这和传统软件工程中的单元测试、集成测试、CI/CD 回归测试本质相同，只是被测对象从确定性代码变成了概率型 Agent。

3. 工具调用风险问题

Agent 的能力很大程度来自工具，但工具也是风险来源：

执行危险的命令（比如 rm -rf）
写数据库
访问敏感信息

如果模型直接连接这些工具，风险会非常高。Harness Engineering 会在工具调用边界加入控制层：

• 权限检查 • 沙箱执行 • 执行前校验 • 工具 Mock • 高风险动作二次确认

这使得 Agent 即使产生错误决策，也不至于直接造成不可控后果。

4. 评测只看结果的问题

传统 LLM 评测常常只看最终答案。但 Agent 的质量不仅取决于最终输出，还取决于过程：

耗时用了 5 分钟，对用户来讲其实很痛苦
调用了不必要的 20 次工具
读取了不该访问的数据

Harness 可以记录完整执行轨迹，并对过程进行评测：

• 工具选择是否正确？ • 是否遵循权限边界？ • 是否有冗余步骤？ • 是否遵循 Skill 的 SOP？

这种过程评测才是实现 Agent 可靠性的关键。

三、原理与架构分析

Harness Engineering 的核心，是把 Agent 的运行过程变成一个可控实验。一个可控实验必须明确：输入、环境、执行器、观测、评测和对比基线。

核心能力矩阵

| 能力 | 目标 | 实现方式 | 为什么重要 | 工程收益 | | --- | --- | --- | --- | --- | | Trace | 记录完整过程 | 记录 Action、Observation、状态变化、工具参数、错误和成本 | 只看最终答案无法解释失败原因，也无法做过程评测 | 可调试、可审计、可诊断 | | Evaluate | 判断是否达标 | 用规则、LLM Judge、人工评审评估结果和过程 | Agent 的质量不只看答对，还要看证据、路径、安全和效率 | 质量可量化，回归可拦截 | | Replay | 复现与对比 | 固定上下文和工具返回重跑，或替换模型/Prompt 做 what-if | 线上问题如果不能复现，就无法稳定修复和验证 | 失败可复盘，优化可验证 |

阶段一：Fixture

目标：把一个"用户请求"升级成"一个可重复运行的工程用例"。

Fixture 不只包含任务文本，还要定义 Agent 运行时看到的世界：

当前时间、用户角色
Memory、文件系统
工具列表、工具返回
权限边界
最终应该满足的结果

具体做法是把任务拆成三类输入：

| 输入类型 | 内容 | | --- | --- | | 业务输入 | 用户原始请求、相关文档、代码仓库、数据库快照 | | 运行上下文 | 当前时间、用户身份、组织权限、历史对话、长期记忆 | | 验证条件 | 必须提到哪些证据、必须调用哪些工具、禁止执行哪些动作、最终输出格式 |

Mock 数据的作用：固定工具世界的返回。例如测试故障分析能力，就让 get_metrics 稳定返回错误率峰值，让 query_logs 稳定返回异常栈，让 get_deploy_history 稳定返回发布时间线。Agent 仍然需要自己决定该调用什么工具、如何理解返回、如何组合证据。

为什么要这么做？

因为 Agent 的行为高度依赖上下文和工具返回。如果搜索结果、日志数据、系统时间和权限状态都在变，那么同一个用例跑出不同结果时，团队无法判断到底是模型变了、Prompt 变了，还是外部世界变了。

收益：评测从"凭感觉问几个问题"变成"有输入、有环境、有预期、有边界的测试资产"。高质量 Fixture 可以长期复用，成为回归测试、模型升级评估和线上问题复盘的基础。

# Fixture 示例 { "task": "分析过去24小时生产环境错误率上升的原因", "context": { "time": "2025-01-15T10:00:00Z", "user_role": "SRE", "permissions": ["read_metrics", "read_logs", "read_deploy_history"] }, "mocks": { "get_metrics": {"error_rate": 0.15, "baseline": 0.02}, "query_logs": ["NullPointerException at ...", "Connection timeout ..."], "get_deploy_history": {"last_deploy": "2025-01-14T22:00:00Z"} }, "expectations": { "must_call": ["get_metrics", "query_logs"], "must_mention": ["部署时间", "错误类型"], "forbidden_tools": ["delete_logs"] } }

阶段二：Run

目标：让 Agent 在受控边界内真实执行任务。

这里的重点是用 Harness 控制 Agent 与外部世界之间的所有关键边界：

固定模型版本和采样参数
设置最大循环步数和最大成本
把文件操作放进沙箱
对工具参数做 schema 校验
对高风险工具做权限检查或人工确认
每一步执行后保存状态

测试环境 vs 生产环境：

| 环境 | 工具调用 | | --- | --- | | 测试环境 | 导向 Mock 数据 | | 真实运行环境 | 导向真实服务代理，并记录请求和响应摘要 |

为什么做这么复杂？

Agent Loop 具备自主性（有点黑盒，我们不知道它内部做了什么），它可能：

多次调用工具
反复尝试
读取敏感数据
触发有副作用的动作

如果没有 Run 阶段的控制层，测试时会不可复现，生产中会不可治理。

收益：Agent 可以像真实运行一样行动，但不会脱离工程边界。团队既能观察真实决策路径，又能控制风险、成本和资源消耗。

阶段三：Trace

目标：把 Agent 的黑箱执行过程变成可分析的数据。

对于 Agent 系统来说，只保存最终答案远远不够，因为同一个答案可能来自正确证据，也可能来自错误工具调用后的碰巧命中。

具体记录四类信息：

| 信息类型 | 内容 | | --- | --- | | 决策输入 | 关键 Prompt、系统指令、检索到的 Memory、用到的工具 | | 模型动作 | 每一步输出了什么 action、调用了哪个工具、参数是什么 | | 环境反馈 | 工具返回、错误、权限拦截、状态变化 | | 运行指标 | token、耗时、成本、重试次数、失败原因 |

为什么需要 Trace？

Agent 的问题通常不在最后的结果，而在中间链路：

选错工具
传错参数
越权访问
多轮状态中丢失上下文

没有 Trace，这些问题只能靠猜

收益：

Agent 的失败可以被定位
评测可以覆盖 Agent 的执行过程
线上样本可以转化为训练和回归数据

阶段四：Evaluate（评测）

目标：把一次运行转化为可比较的质量判断。

它不仅判断最终答案是否正确，还要判断过程是否可靠、证据是否充分、工具使用是否合理。

具体做法：混合评测

| 评测方式 | 适用场景 | | --- | --- | | 规则评测 | JSON schema、必须字段、禁止工具、权限边界、是否引用指定证据 | | LLM Judge | 根因分析是否合理、答案是否覆盖用户意图、证据链是否完整 | | 人工评审 | 财务、权限、发布、合规类高风险任务 |

为什么不用单一的 LLM Judge？

很多高风险的行为（权限、安全、强事实条件）需要有人工的确定性约束；而开放式分析、总结质量、推理完整性又很难只靠规则判断。混合评测能把两类问题各自交给适合的方法。

评测对象与方法的映射：

| 评测对象 | 适合方法 | 关注点 | 工程收益 | | --- | --- | --- | --- | | 输出格式 | 规则 | JSON、字段、模板是否合规 | 防止下游解析失败 | | 必要事实 | 规则 | 是否提到关键版本、日志、指标 | 防止遗漏核心证据 | | 推理质量 | LLM Judge | 结论是否由证据支持 | 发现"答对但理由错" | | 安全合规 | 规则 + 人工 | 是否越权、是否触发危险动作 | 降低生产风险 | | 用户体验 | LLM Judge + 人工 | 是否清晰、可执行、完整 | 提升真实可用性 |

收益：团队可以用同一套 Fixture 判断是否真的变好，而不是只看几个示例的主观感受。

阶段五：Replay（回放）

目标：把一次运行沉淀成可反复使用的实验样本。

用相同任务、相同上下文和相同工具返回重新执行，观察 Agent 是否能复现当时行为，或者在新模型、新 Prompt 下是否改善。

两种回放方式：

| 方式 | 做法 | 用途 | | --- | --- | --- | | Exact Replay | 固定模型版本、上下文、工具返回和 Memory | 复现线上失败，定位问题 | | What-if Replay | 保持任务和环境不变，替换模型/Prompt/工具描述/策略 | 验证修复方案和优化效果 |

为什么需要 Replay？

线上问题经常具有瞬时性：

搜索结果会变
用户上下文会更新

如果不把当时的关键变量记录下来，问题很快就无法复现。

收益：线上失败可以变成回归测试的资产。每次修复后都可以用 Replay 验证，避免同类问题在下一次模型或 Prompt 升级中重新出现

四、落地案例

代码 Agent 的 Harness 实践

代码类 Agent 需要读取代码、修改文件、运行测试、修复错误。Harness 提供了完整的工程化支撑。

隔离与安全：

• 每个用例使用独立临时目录 • 禁止访问仓库外文件 • 限制网络访问 • 记录每次文件 diff

评测指标：

• 单元测试是否通过 • 是否只修改允许范围内文件 • diff 是否过大 • 是否引入无关重构 • Agent 是否正确解释修改原因

典型流程：

Harness 创建临时仓库
Agent 读取代码并修改
Harness 运行测试
Agent 根据测试失败继续修复
Harness 收集最终 diff、测试结果和轨迹

这样的话，代码 Agent 的能力可以被像传统软件一样做回归测试，而不是只看演示效果。

小说 Agent 的创作修改 Harness

小说类 Agent 需要列出大纲设定、写章节、统一文风。Agent 可能会写崩核心人设、破坏已有剧情逻辑、忽略大纲约束。这对于读者来说是不可接受的。

Harness 设计思路：

任务夹具：

• 指定章节之前的全部文本、核心人物详细档案、世界观设定文档、已铺设伏笔清单及时间线 • 明确任务类型（续写、修改、润色、补全）、具体作用范围及预期目标 • 公开的基础要求（字数、视角、格式）与隐藏的一致性测试点（人物行为逻辑、剧情连贯性） • 禁止引入的内容类型、必须保留的关键情节、输出格式规范

执行环境：

• 为每个独立任务创建专属的创作沙箱 • 限制 Agent 只能访问任务包内提供的素材 • 屏蔽不受控的外部网络访问，防止抄袭与无关内容引入 • 完整记录 Agent 的每一次修改操作、版本变更及思考轨迹

多维度评估指标：

| 维度 | 评估内容 | | --- | --- | | 合规性 | 是否在指定范围内修改、是否满足字数与格式要求、是否违反内容禁忌 | | 一致性 | 人物设定是否保持统一、剧情是否存在矛盾、伏笔是否得到妥善处理、时间线是否准确 | | 质量 | 修改幅度是否合理、是否引入冗余内容、文风是否与原文匹配、Agent 能否清晰说明创作决策理由 |

通过这套 Harness 体系，小说创作 Agent 的能力可以进行标准化的定量评估与持续迭代优化，而非仅依赖单次演示的主观效果。

五、面试题与解答

1. Harness Engineering 和普通工程化测试有什么区别？

普通测试主要验证确定性程序逻辑，例如函数输入 a=1, b=2，输出应为 3。被测系统通常是稳定、可预测的。

而 Harness Engineering 面向的是更复杂的智能系统，尤其是 LLM 和 Agent。它的被测对象具有以下特点：

• 输出不确定：同一输入可能产生不同输出 • 多步推理：行为依赖于上下文和中间决策 • 外部依赖多：工具调用、检索、API 交互 • 失败原因复杂：可能是模型、Prompt、工具、Memory 任一环节的问题

对于 Agent 来说，Trace 就是黑箱飞行记录仪。没有它，复杂任务失败后很难进行工程化修复。

2. 如何设计高质量的 Agent 评测任务集？

高质量任务集应该覆盖真实需求、关键能力和边界风险，而不是只收集简单成功案例。

设计原则：

来自真实场景：优先从线上真实请求、失败案例和高频任务中抽样
覆盖能力维度：例如工具调用、信息检索、代码修改、多轮澄清、安全拒答
包含失败路径：工具超时、权限不足、用户信息不完整
维护期望结果：每个用例至少要有可判定的成功标准，而不是只有一段用户问题
定期更新：任务集要吸收新失败案例，避免评测和真实场景脱节

3. LLM Judge 在 Harness 中可靠吗？如何使用？

LLM Judge 有价值，但也不能无条件信任，要分类讨论：

不适合只靠 LLM Judge 的场景：

• 权限是否越界 • 是否调用了禁止工具 • 数值计算是否正确 • SQL 查询结果是否匹配 • 是否包含敏感字段

适合用 LLM Judge 的场景：

• 判断回答是否覆盖关键语义 • 评估解释是否清晰 • 判断分析结论是否与证据一致 • 对开放式报告质量打分 • 聚类失败原因

推荐做法：混合评测

先用规则做硬约束：格式、安全、工具调用、关键字段
再用 LLM Judge 做语义评估：质量、完整性、推理合理性
对高风险样本人工抽检：校准 Judge 的偏差
评测 Judge 自身：用人工标注集定期验证 Judge 一致性

**核心原则：**LLM Judge 只是评测助手，真正的效果其实还要依靠人工打标。

4. 如何处理 Agent 输出的不确定性？同一个用例每次结果不完全一样怎么办？

Agent 的不确定性肯定不能完全消除，但可以适当控制和约束。

常见策略：

• 固定模型参数：降低 temperature，固定 top_p 等采样参数 • 固定环境：工具返回、时间、Memory、文件系统都使用快照 • 多次运行取分布：同一用例运行 N 次，观察成功率和方差 • 设置容忍区间：例如数值误差允许在 1% 内 • 区分硬失败和表达差异：格式错误是硬失败，措辞不同不一定失败

稳定性指标（适用于关键任务）：

stability_score = 通过次数 / 总运行次数

一个用例如果平均得分高但稳定性低，仍然不适合直接上线。

5. 如何判断一个 Agent Harness 是否成熟？

可以从五个维度判断：

| 维度 | 评估标准 | | --- | --- | | 可复现性 | 同一用例可以在相同环境下反复运行；工具返回、Agent 的上下文 Memory 和文件快照可固定；失败案例可以被回放 | | 覆盖度 | 覆盖核心能力；覆盖失败路径；覆盖安全边界；覆盖线上高频任务 | | 评测质量 | 有明确通过标准；规则评测和语义评测结合；高风险用例有人工校准；能输出可解释失败原因 | | 工程集成 | 接入 CI/CD；支持批量运行；支持版本对比；支持报告和门禁 | | 治理能力 | Trace 可审计；敏感信息可脱敏；成本可控；权限和副作用可约束 |

成熟的 Harness 不只是一个大模型评测工具，而是 Agent 工程化迭代的基础设施。

六、总结：Harness Engineering 是 Agent 可靠性的工程底座

Harness Engineering 的核心价值，是让 Agent 从一个看起来能工作的工具，变成一个可以被持续验证、稳定迭代和安全上线的工程系统。

三种关键能力

| 能力 | 价值 | | --- | --- | | 复现能力 | 失败不再是偶发现象，而是可回放样本 | | 评测能力 | 效果不再凭主观感觉，而是有指标和基线 | | 治理能力 | 工具调用、权限、安全和成本都能被约束 |

与 Agent 核心组件的关系

Harness 与 ReAct、Memory、Skill、Agent Loop 等并不冲突，而是承接它们：

ReAct 让 Agent 有动态推理能力
Memory 让 Agent 有长期上下文
Skill 让 Agent 有可复用流程
Agent Loop 让 Agent 能持续执行任务
Harness Engineering 让这一切可以被测试、回放、评测和治理

核心问题

"我们能不能稳定复现它的成功？能不能解释它的失败？能不能证明新版本没有退化？能不能在出错前拦住危险动作？"

只要能系统性回答这些问题的能力，就是 Harness Engineering 的价值所在。它让 AI 的黑盒变成白盒，让 Agent 从"能跑"走向"可验证地可靠"。