Harness EngineeringAI Agent 可靠性的工程底座引言给 AI Agent 搭建一座可控的试验场比如我们要开发一套汽车自动驾驶系统肯定不会直接把一辆还没充分验证的车开上真实道路让它在复杂城市交通中自由发挥。相反我们会先搭建仿真环境、测试跑道、故障注入系统和评测指标体系同一段路况可以反复回放同一个危险场景可以稳定复现每一次刹车、转向和误判都能被完整记录。AI Agent 的工程化也面临同样的问题。一个 Agent 看起来能对话、能调用工具、能写代码、能分析数据但这并不意味着它已经可以进入生产环境。我们还需要回答一系列更工程化的问题它调用工具的过程是否可以复现而不是那么的黑盒它失败时能不能定位原因如果我们在 Agent 执行过程中两眼一抹黑我们就对 Agent 的进一步优化无从下手。而解决这些问题的工程体系就是Harness Engineering。它解决的是如何把 Agent 放进一个可控、可观测、可复现、可评测的工程环境中从而让 Agent 从能跑走向可验证地可靠。一、概念什么是 Harness EngineeringHarness 原本在软件工程中常见于 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 更好地完成任务。这个系统包括PromptToolMemorySkillAgent LoopTrace、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 EngineeringAgent LoopEvaluationObservability核心问题如何构建可控的运行与验证环境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、耗时、成本、重试次数、失败原因为什么需要 TraceAgent 的问题通常不在最后的结果而在中间链路选错工具传错参数越权访问多轮状态中丢失上下文没有 Trace这些问题只能靠猜收益Agent 的失败可以被定位评测可以覆盖 Agent 的执行过程线上样本可以转化为训练和回归数据阶段四Evaluate评测目标把一次运行转化为可比较的质量判断。它不仅判断最终答案是否正确还要判断过程是否可靠、证据是否充分、工具使用是否合理。具体做法混合评测评测方式适用场景规则评测JSON schema、必须字段、禁止工具、权限边界、是否引用指定证据LLMJudge根因分析是否合理、答案是否覆盖用户意图、证据链是否完整人工评审财务、权限、发布、合规类高风险任务为什么不用单一的LLMJudge很多高风险的行为权限、安全、强事实条件需要有人工的确定性约束而开放式分析、总结质量、推理完整性又很难只靠规则判断。混合评测能把两类问题各自交给适合的方法。评测对象与方法的映射评测对象适合方法关注点工程收益输出格式规则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 和普通工程化测试有什么区别普通测试主要验证确定性程序逻辑例如函数输入a1, b2输出应为3。被测系统通常是稳定、可预测的。而 Harness Engineering 面向的是更复杂的智能系统尤其是 LLM 和 Agent。它的被测对象具有以下特点• 输出不确定同一输入可能产生不同输出 • 多步推理行为依赖于上下文和中间决策 • 外部依赖多工具调用、检索、API 交互 • 失败原因复杂可能是模型、Prompt、工具、Memory 任一环节的问题对于 Agent 来说Trace 就是黑箱飞行记录仪。没有它复杂任务失败后很难进行工程化修复。2. 如何设计高质量的 Agent 评测任务集高质量任务集应该覆盖真实需求、关键能力和边界风险而不是只收集简单成功案例。设计原则来自真实场景优先从线上真实请求、失败案例和高频任务中抽样覆盖能力维度例如工具调用、信息检索、代码修改、多轮澄清、安全拒答包含失败路径工具超时、权限不足、用户信息不完整维护期望结果每个用例至少要有可判定的成功标准而不是只有一段用户问题定期更新任务集要吸收新失败案例避免评测和真实场景脱节3. LLM Judge 在 Harness 中可靠吗如何使用LLM Judge 有价值但也不能无条件信任要分类讨论不适合只靠LLMJudge 的场景• 权限是否越界 • 是否调用了禁止工具 • 数值计算是否正确 • SQL 查询结果是否匹配 • 是否包含敏感字段适合用LLMJudge 的场景• 判断回答是否覆盖关键语义 • 评估解释是否清晰 • 判断分析结论是否与证据一致 • 对开放式报告质量打分 • 聚类失败原因推荐做法混合评测先用规则做硬约束格式、安全、工具调用、关键字段再用 LLM Judge 做语义评估质量、完整性、推理合理性对高风险样本人工抽检校准 Judge 的偏差评测 Judge 自身用人工标注集定期验证 Judge 一致性核心原则LLMJudge 只是评测助手真正的效果其实还要依靠人工打标。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 从能跑走向可验证地可靠。