1. Harness工程化为什么Agent的可靠性要先解决脚手架问题做AI Agent开发的人前三个月基本都在跟不确定性死磕。模型输出飘忽、工具调用时好时坏、多轮对话跑到第三轮就开始偏离上下文这些坑我全踩过。后来我发现问题不一定出在Agent本身更多时候出在Agent外面那层壳——业内叫Harness也就是我们把模型、工具、记忆、权限、策略这些组件装起来的运行框架。Harness这个词翻译成测试夹具也好运行脚手架也罢本质上是同一件事它既规定了Agent能做什么、能碰什么、出错怎么兜底也决定了我们能不能稳定地观察和度量Agent的行为。很多团队把精力花在调prompt、换模型上却忽略了Harness层本身就是一个需要被严格验证的软件系统。Agent的可靠性一半靠模型能力另一半靠Harness的约束与容错。如果Harness自身不稳定模型再强也会被底层bug拖垮。这篇文章我想聊的就是围绕AI Agent Harness建立一套可靠性测试体系的方法。它适合正在做Agent应用、被线上事故和不稳定测试折磨过的工程师也适合刚入门、想搞清楚Agent上线前到底该怎么验证的朋友。内容不追求面面俱到只讲我实际验证过、确实能落地的思路和动作。1.1 从能跑通到能扛住Harness在Agent开发中的真实定位先给一个容易混淆的概念做区分Harness和Agent不是一回事。Agent是那颗大脑负责推理、规划、决定下一步调用哪个工具Harness是承载大脑的身体负责提供工具清单、执行工具调用、收集结果、管理上下文窗口、限制权限、处理超时和异常。换句话说用户跟Agent对话时用户看到的是Agent在回答问题实际上所有请求都要先经过Harness。Harness把你的业务逻辑、工具API、安全策略、模型参数全部串起来。这就意味着Harness的任何一环出问题Agent的表现都会出问题而且出的问题往往比模型本身的问题更难排查——因为模型的问题有迹可循Harness的问题却经常表现为玄学。我见过一个真实案例某个Agent工具调用的JSON Schema写错了导致模型每次返回的合法参数都被校验层拒绝系统连续重试三次后报错。表面上看是模型不行实际上模型每次都给对了是Harness的参数校验写得太死。这类问题如果没有一套针对Harness的测试体系光靠线上监控根本发现不了。1.2 为什么传统的单元测试和集成测试都不够用传统软件测试的思路是输入固定、输出可预期但Agent的输出天然带随机性。同一个问题问十次模型可能给出十种不同措辞工具调用路径也可能不同。如果把传统断言直接套到Agent上测试结果会频繁抖动最后团队只能靠加大样本量来碰运气这显然不科学。更麻烦的是Agent是带状态、带工具、带外部依赖的系统。它可能调用你的数据库、第三方API、文件系统还可能在前一轮对话的基础上继续执行。传统测试框架很难模拟这种动态环境。所以严格来说我们需要的不只是测试用例而是一套测试体系——它要解决用例怎么设计、环境怎么隔离、结果怎么判定、回归怎么跑、线上问题怎么反哺测试集这一整个闭环。这正是Harness测试体系的价值所在。它把模型能力验证和工程可靠性验证分开前者交给评估集和千次抽样后者靠确定性测试和故障注入来保障。两条线互相支撑又不互相污染。理解了这一点后面所有的设计都不会跑偏。2. Agent Harness测试体系的整体设计我搭这套体系的时候第一个原则就是分而治之。不要试图用一个万能的测试框架解决所有问题而是把测试目标拆成几个可以独立验证的层次每一层用最合适的工具和方法去测。分层的另一个好处是出了问题你能快速定位层次不用每次都是全链路排查。2.1 测试体系的分层架构我把Harness测试体系分成四层第一层是组件层针对Harness内部的每个独立模块做测试。比如工具注册表、参数校验器、上下文压缩器、记忆管理器、重试策略、超时控制这些都是纯代码逻辑可以用传统单元测试全覆盖。这一层是整个体系的根基Harness的bug大多能在这层被拦下来。第二层是编排层测试Harness如何调度一次完整的Agent执行。比如给定一个用户请求Harness是否正确地组装了系统提示词是否正确调用了LLM是否正确解析了工具调用的返回结果是否把最终回复正确地交还给了用户。这一层需要Mock掉LLM本身用固定的模型响应来驱动编排逻辑保证测试的确定性。第三层是场景层也是Agent测试的核心。把典型用户场景设计成端到端任务用真实或半真实的LLM跑完整流程验证Agent在真实条件下的任务完成率和路径质量。这一层允许结果有概率波动但通过统计方法控制置信度。第四层是韧性层专门做故障注入和异常测试。模拟工具超时、模型接口500、上下文超长、工具返回脏数据、用户中途打断等异常情况验证Harness在恶劣条件下能不能正确降级、重试、报错或者优雅退出。每层测试的定位不同跑的频率也不同。组件层和编排层每次提交都跑全量场景层每天定时跑韧性层每周至少跑一次全量。这样既保证了快速反馈又不会让CI时间爆炸。2.2 测试用例的组织方式与场景目录测试用例的维护成本是测试体系能否长期运转的关键。我的做法是所有用例都走场景目录的方式管理每个用例包含四类信息——业务描述、前置条件、输入数据、预期结果约束。这样写出来的用例别人接手时不用翻文档也能看懂。举个例子一个典型的用例是这样组织的{ case_id: tool_call_schema_drilldown_001, title: 多级下钻查询时工具参数必须严格匹配Schema, preconditions: { mock_llm: false, tool_stubs: [query_employee_db], context_size: medium }, input: { user_query: 帮我查一下华东区销售团队上季度的季度目标完成率 }, expected: { task_success: true, tool_call_sequence: [query_region, query_team, query_target], final_answer_contains: [完成率] } }注意这里的预期结果约束不是硬性的字符串相等而是结构化断言。工具调用序列可以允许合理偏差最终答案只要包含关键语义、不包含明显错误信息就算通过。这样设计是为了在严格性和容错性之间找平衡——太严格会把模型的合理路线差异误判为失败太宽松又会让bug溜过去。场景目录我会按业务域、复杂度、风险等级三个维度打标签。每次模型升级或者Harness改版直接按标签筛选出对应子集做回归效率高出不少。2.3 可靠性验证的几个核心维度可靠性这个词很宽泛落到测试上我通常拆成五个维度来验证每个维度都有各自的验证重点和对应手段验证维度关注什么用什么手段测正确性任务结果是否准确完整、工具参数是否合法场景层端到端用例 结构化断言稳定性同样输入多次执行结果方差是否可控固定样本重复跑统计成功率分布鲁棒性异常输入、歧义指令下能否合理处理韧性层故障注入 异常输入集效率工具调用轮数、token成本、端到端耗时性能指标采集 基线对比安全合规权限边界、数据隔离、越权动作专用安全沙箱用例脱敏数据正确性是最基础的维度对应场景层的任务成功率。稳定性关注的是波动同一个问题回答十次五次对五次错成功率50%但方差极大这种Agent上线风险很高。鲁棒性对应韧性层重点验证异常条件下的降级行为。效率这个维度很多团队会忽略但上一版跑3轮工具调用改完模型要跑7轮就算结果对了成本也翻倍测试体系应该报警。安全合规必须用独立的沙箱环境跑绝不能拿真实业务数据去验证。3. 可靠性验证方法论核心方法与实操要点方法论的层面我想重点讲三个技术也是这套体系里我觉得最有价值的三个确定性验证、故障注入、以及长稳压测。这三板斧用好了Harness的可靠性至少能上一个台阶。3.1 确定性验证Mock、录制回放与固定种子LLM输出不确定但Harness的代码逻辑必须是确定的。所以编排层测试有一个铁律永远不要用真实的LLM响应来测试编排逻辑而是把所有模型调用Mock掉喂固定响应。Mock的思路很简单写一个假的LLM客户端按预设顺序返回固定的文本或工具调用JSON。这样每次执行都是完全确定性的跑了100次和跑1次结果一样测试失败一定是代码问题而不是模型抽风。这有点像是拍电影时的替身演员——正式拍摄用真人但排练走位时必须用假人否则每次走位都不一样你根本分不清是剧本问题还是演员发挥问题。更进一步的做法是录制回放。把线上真实请求的LLM请求-响应对录制下来存成回放文件测试时用回放数据代替真实模型调用。这样既保留了真实分布的多样性又保证了每次运行的一致性。我现在常用的流程是先从生产环境抽一批有代表性的请求做录制回放测试通过后新的模型版本在上线前用这批回放数据做对比看看行为有没有退化。固定种子的方式也可以辅助但要注意对于LLM内置解码的随机性种子不一定完全有效。我在实际项目中固定种子更多是用在测试数据的生成上保证每次生成的测试用例集一致而不是指望它把模型输出也锁死。3.2 故障注入让Harness学会在坏天气里飞行故障注入是我个人最喜欢的部分也是很多团队最忽略的部分。大家习惯了happy path测试工具正常返回、模型正常响应、网络正常畅通但线上环境什么时候正常过第三方API随时可能超时数据库连接可能突然断开模型服务可能限流工具返回的数据可能带奇怪的字符。一个只在晴天飞过的飞行员是不配应对雷暴天气的。韧性层测试的核心方法就是主动把这些故障注入到Harness中验证它能不能扛住。注入方式我常用三种代码注入、代理注入、环境模拟。代码注入是直接在测试中抛异常比如让某个工具桩直接抛出TimeoutError看Harness是否触发重试代理注入是通过一个代理层随机延迟或丢弃请求模拟网络抖动环境模拟则是在容器级别限制CPU、内存、带宽模拟资源紧张的场景。三种方式由浅入深建议从代码注入开始逐步加大故障强度。这里有一个关键点故障注入不是把系统搞挂就完事而是要验证正确降级路径。比如工具超时后Harness应该重试两次再放弃放弃时应该给用户返回暂时无法获取数据而不是让它卡在那里转圈也不是让它报一个开发者才看得懂的堆栈错误。这些降级路径都要写进用例的预期约束里一条一条核对。我在实际执行时会专门做一个降级行为对照表把每种故障类型对应的期望行为写清楚测试直接按表断言。3.3 长稳测试与压力测试跑7×24小时盯内存和上下文Agent系统的崩溃往往不是瞬间发生的而是长时间运行后积累出来的。上下文窗口越用越长导致token超限、记忆存储越写越多导致查询变慢、循环调用一直没结束导致资源泄漏这些都需要长稳测试来暴露。我的做法是搭建一套长稳流水线用脚本模拟一批虚拟用户会话每轮会话执行完整的提问-工具调用-回复链路。跑7×24小时每隔5分钟记录一次关键指标内存占用、CPU使用率、平均响应时延、工具调用失败率、上下文长度变化趋势。跑完把趋势图画出来任何一条曲线出现持续上扬都说明存在资源累积问题。压测那部分核心指标是并发会话数和单会话内连续交互次数。我会把并发从10逐步升到50、100观察吞吐量和错误率的变化曲线找到Harness的瓶颈点。这里提醒一句压测环境最好用Mock模型否则模型服务的成本和时延波动会污染你的压测数据你根本分不清是Harness不行还是模型服务不行。长稳测试跑完之后一定要做结果基线归档。把每次的内存基线、时延基线和失败率基线存下来下次跑完直接对比任何超过10%的劣化都要自动告警。否则你花了三天跑完一轮长稳数据看一眼就丢那这轮测试的价值就白费了大半。4. 关键指标与评估体系用数字给可靠性画像测试体系跑起来了但怎么衡量它的效果怎么让团队知道Agent的可靠性到底行不行这就需要一个明确的指标评估体系。我的经验是指标不能贪多也不能只看任务成功率必须分层设计。4.1 任务成功率之外还要看什么任务成功率是最直观的指标但它有天然的缺陷成功定义模糊、样本波动大、而且它不告诉你失败的原因。同一个任务模型用的是A路径还是B路径都成功了但A路径绕了12次工具调用B路径只用了3次成功率都是100%成本却差了四倍。所以我额外关注三组辅助指标工具调用质量包括工具名选得对不对、参数校验通过率、无效调用比例、工具调用死循环次数。这组指标能精准反映Harness编排和工具层的问题尤其适合用来定位之前提过的假成功场景。执行效率平均工具调用轮数、中位延迟、P95延迟、单任务token消耗。这组指标帮助你在模型升级或prompt调整时量化评估变快了还是变慢了。我见过一次模型升级后在评测集上分数涨了但token消耗涨了40%这种隐性成本不靠指标根本发现不了。恢复能力故障注入场景下的恢复成功率、平均恢复时间、降级路径触发率。这组指标反映系统的韧性我建议每个版本都必须带韧性指标上线不然就等于带着安全隐患裸奔。4.2 指标怎么量化口径怎么统一量化口径不统一是测试指标失去公信力的第一大杀手。我做了一个约定所有指标都通过测试报告自动产生不做人工打分不搞线下Excel统计。人一介入口径就开始漂移今天算的是中位数明天换成平均值后天又混进了手动确认的用例最后数据根本没法纵向对比。每个测试用例执行完测试框架会输出结构化结果包括用例ID、通过/失败、耗时、工具调用日志、token数量、失败原因分类。这些结果汇总到统一的指标模型里按天、按版本聚合。聚合时注意区分统计维度——按版本看趋势按场景看覆盖按工具看质量三个维度互相补充缺一个都容易得出片面结论。还要区分硬指标和软指标。硬指标是必须达到的比如工具参数校验通过率不能低于99%、故障恢复成功率不能低于95%、P95延迟不能超过某个阈值这些写成代码断言跑CI的时候直接卡门禁。软指标是趋势类的比如token消耗下降了多少、工具调用轮数有没有改善这些不进门禁但进周报供团队做决策参考。硬指标保证下限软指标引导优化两者分工明确。4.3 回归基准与红线机制测试体系一定要有红线意识。什么叫红线就是一旦某些指标跌破阈值发布流程必须被拦停绝对不能带着劣化上线。我见过太多团队测试报告显示指标下降了30%但某个需求必须今天上于是大家带着问题上线最后出事再来补救。为了对抗这种惯性我把红线机制做进了CI硬指标不达标pipeline直接报红合并请求不允许通过。一开始团队会觉得卡得太死但跑了两三个版本之后大家发现红线上线前的恐慌式修复少了很多反而更高效了。这不是技术问题而是流程决心问题。回归基准也很重要。每次模型升级、Harness改版、工具API变更都要触发一次回归跑分和基准版本对比。我建议每次回归至少跑三遍同用例集取中位数作为对比基线避免单次运行的随机波动影响判断。如果某个改动导致一两个用例反复失败不要急着改代码先确认是自己测试环境的问题还是真的回归了——这个经验我后面还会细说。再补充一个实用小技巧把回归基准做成可视化对比图横轴是版本纵轴是关键指标每个版本一个点。团队每周例会扫一眼图哪些指标在恶化一目了然比翻测试报告高效太多。可视化是最容易被忽视的团队协作工具它让所有人都能用同一张图说话。5. 实操过程从零搭建一套Harness测试流水线理论讲了不少落地才是关键。这一部分我把从零搭建Harness测试流水线的过程完整走一遍包括工程结构、关键代码、CI接入手把手讲清楚每一步在做什么和为什么这么做。5.1 环境准备与工程结构我先说结论测试代码和业务代码必须分仓库或者分模块管理严禁混在一起。Agent项目迭代快业务代码频繁改如果测试代码耦合在业务仓库里一个紧急hotfix就会把测试集弄得乱七八糟。而且测试的依赖和业务依赖差别很大混在一起容易把测试工具带进生产镜像。我常用的工程结构是这样的agent-harness/ ├── agent/ # 业务代码Agent核心逻辑 │ ├── core/ │ ├── tools/ │ └── memory/ ├── harness/ # Harness层编排、校验、容错 │ ├── runtime.py │ ├── schema_validator.py │ └── retry_policy.py ├── tests/ │ ├── unit/ # 组件层单元测试 │ ├── orchestration/ # 编排层测试Mock LLM │ ├── scenarios/ # 场景层端到端测试 │ ├── resilience/ # 韧性层故障注入测试 │ ├── fixtures/ # 测试数据、录制回放文件 │ └── conftest.py ├── report/ # 测试报告输出目录 └── scripts/ ├── run_all_tests.sh └── collect_metrics.py依赖管理我建议用poetry或者uv把开发依赖pytest、httpx mock、录制回放库和运行依赖分开。这样CI里安装依赖更快也不会把测试工具带到生产镜像里。这条在微服务架构下尤其重要镜像体积每大一倍发布耗时和出错的概率都在涨。环境层面最省心的是用Docker容器跑测试每个测试环境一个独立的容器里面预置好Mock服务和临时数据库。跑完就销毁保证环境干净可复现。我踩过最大的坑就是本地环境能过、CI环境挂掉后来排查发现是本地的工具mock服务还开着CI里没有启动。所以我在所有场景测试的fixture里都强制要求显式声明依赖服务缺了直接报错不让它有隐式依赖的机会。5.2 测试驱动编写与断言设计Mock LLM的编排层测试我写了一个简单的fake客户端class FakeLLMClient: def __init__(self, responses: list): self._responses list(responses) self._index 0 def chat(self, messages, **kwargs): resp self._responses[self._index] self._index 1 return resp用法非常简单把一次完整Agent执行过程中期望的LLM返回按顺序注入然后测试Harness是否按预期流程走完。比如第一个响应让Agent调用query_region工具第二个响应让Agent调用query_team工具第三个响应要求Agent生成最终答案。每个响应之间的状态衔接正好顺带验证了Harness的上下文管理是否正确。断言设计上我坚持一个原则断言业务效果不锁死实现细节。举例来说工具调用顺序可以有合理替换比如先查query_team再查query_region只要最终答案正确且没有非法操作就应该通过。千万别写成第3步必须调用X工具这种僵化断言一次合理的模型优化就会把你的测试大批量打红团队会因此恨上测试体系之后对红测试视而不见体系就废了。场景层的端到端测试我会用真实的LLM服务跑但会加一些约束固定模型版本、固定temperature为0、固定max_tokens。每次跑完不追求100%通过而是统计成功率跟上一版基线对比。成功率掉超过5个百分点就自动触发告警并把失败样本打进一个case库供人工分析。case库积累多了你会发现很多偶发失败其实是同一类问题的重复出现那时候fix起来非常快。5.3 接入CI/CD与结果可视化CI接入的核心是分策略执行不要一股脑全跑。全量测试跑一次要是超过20分钟开发者每次提交都等这么久要么他们绕过CI要么CI形同虚设。我的pipeline设计是单元测试和编排层测试每次push都全量跑3分钟内必须完成超时就优化测试集别让开发者等太久。韧性层测试每次合并到主干前跑全量耗时较长可以放在合并请求的异步任务里。场景层测试每天凌晨定时跑全量出结果后自动生成日报。结果可视化这块我强烈建议不要只看pytest的终端输出。把测试结果导出成JSON然后用Grafana或者轻量级的报告模板生成一个看板成功率趋势、各层通过率、失败用例分布、关键指标变化曲线。每次CI结束自动更新看板。团队不需要打开终端翻日志打开一个网页就能看到Agent当前的健康度这才叫测试体系而不只是测试脚本。这里再插一句刚开始搭看板的时候先别追求炫酷三个图就够了——成功率趋势折线图、失败原因分布柱状图、关键耗时指标箱线图。跑两周之后你自然知道还需要加什么让需求驱动看板迭代而不是一开始就堆一堆用不上的组件。6. 常见问题与排查技巧实录最后这部分我把自己在搭建和维护这套Harness测试体系过程中遇到的典型问题整理出来。这些问题看起来都很小但每一个都曾经让我的测试集整片飘红或者让线上问题在测试里完全隐身。6.1 测试不稳定Flaky Test的五大来源Flaky Test是测试体系最大的敌人它会快速消耗团队的信任。一旦大家觉得测试挂了可能是玄学就算真的出了问题也没人当回事了。下面是我归纳的五大来源和对应解法来源典型现象解决对策环境残留单个用例能过全量跑就挂每个用例独立容器或独立临时目录断言前做状态重置超时太紧偶尔超时重跑就过超时时间设为基线P95的1.5倍用Wait For条件代替固定Sleep顺序依赖用例之间存在隐式先后关系每个用例必须独立可跑fixture强制初始化全套前置条件Mock遗漏某个工具调用真实打到外部服务启动时做全局工具桩覆盖检查未桩的工具直接fail fast样本偏差成功率和上次对比波动大样本量不少于30个用置信区间判断不拿小样本下结论环境残留和顺序依赖是最隐蔽的因为它们只在全量跑的时候出现单独跑一个目录根本复现不了。我建议从第一天就养成每个用例自带全套前置条件的习惯宁可多写几行fixture也别省这几分钟的运行时间。6.2 Agent假成功问题怎么识别假成功是我最警惕的测试陷阱测试显示任务成功了但实际上Agent根本没完成用户的目标。比如用户问帮我查一下华东区销售团队上季度的完成率Agent最后回复我查到了华东区销售团队的数据但上季度完成率暂时无法获取您需要我进一步查询吗——这在某些宽松断言下会被判为成功但实际上用户要的核心信息根本没给到。识别假成功的关键是三层断言第一层最终回复是否包含关键实体第二层关键工具调用是否真的执行并返回了有效数据第三层最终回复是否直接回答了用户的原始问题。这三层都要通过才算真成功。只有第一层是很多测试用例的现状看起来答非所问的情况就会被漏过去。我在设计场景层用例时专门维护了一个关键信息清单每个任务必须要出现的关键数据点列清楚测试断言直接检查这些数据点是否出现在最终回复里。比如上面那个查完成率的用例关键信息清单就是华东区销售团队上季度完成率数值。四个要素缺一个断言直接判失败不给话术绕过去留机会。6.3 排查实录一次Harness超时问题的完整复盘最后讲一个具体的复盘案例。有段时间场景层测试频繁出现工具调用超时的失败第一次我以为是偶发结果连续三天每天都挂成功率掉到60%以下。排查第一步看失败用例的时间分布。发现全部集中在每天上午10点到11点之间。第二步看这个时候线上在做什么。原来团队每天早上定时跑数据同步任务数据库负载飙升测试环境的工具查询也跟着变慢触发了超时。第三步确认是Harness的超时设置问题还是测试隔离问题。最后定位是测试环境跟数据同步任务共享了同一个数据库实例导致工具查询被挤占。解决方式有两个层面短期把测试环境迁到独立数据库实例并给工具调用超时设置加上合理的缓冲长期把数据同步任务和测试环境的资源隔离做成硬性规范。这个案例想说明的是很多测试失败不是你代码的问题而是环境相互干扰的问题。遇到测试失败别急着改业务代码先问三个问题——是环境问题吗是测试本身的问题吗最后才考虑是不是真的业务回归。这个排查顺序能省下大量无效工作时间我后来把它写进了团队的新人手册。另外还有一个小技巧每次新增用例时顺手记录一下它的易碎点——哪个外部依赖最容易影响它、哪个断言最容易误报。等真正出问题的时候这个记录能帮你少走很多弯路。这些细节才是测试体系真正沉淀下来的资产。最后说一点个人的体会Harness测试体系不是一次性搭建完就一劳永逸的工程它跟你Agent的业务一起演化。工具多了场景目录要跟着扩模型换了回归基线要重建线上出了新事故一定要在24小时内把这个事故场景固化成一个回归用例绝不让同一个坑在测试集里缺席两次。做到这一点你的测试体系才真正成了团队可靠性的护城河而不只是一堆看起来很忙的脚本。