Harness Design For AI Agents：一条真实链路讲清它是怎么工作的

一条真实的 Harness 链路：让它跑起来，再让它输出来

假设你正在搭建一个代码审查 Agent，它的核心任务是用 LLM 分析 PR diff，然后生成是否通过的结论。你不想每次测试都真的打开编辑器、创建 PR、等待 GitHub Webhook——你需要一个 Harness。

Harness Design for AI Agents 的核心思路是：把 Agent 的执行过程与外部世界隔离开，用可控的输入和断言来验证它的行为。这条链路分为三步：Mock 输入 → 执行 Agent → 断言输出。

第一步：Mock 输入，而不是真实外部调用

最常见的错误是直接让 Agent 连真实 API。Harness 的做法是提前录制或伪造外部响应。比如，对代码审查 Agent，你需要 mock GitHub 的 PR 数据、diff 内容、甚至 LLM 的返回。

一个容易失败的地方：mock 数据太干净。真实环境中的 PR 评论可能带有 @mention、空行、乱码，如果 harness 只用了格式化良好的样例，Agent 会在生产中出现各种意外。正确做法是至少包含 3 种变异：正常 diff、含大量注释的 diff、以及部分文件被删改的 diff。

第二步：让 Agent 在 Harness 中执行，并收集完整日志

不只是在终端观察 print 输出。Harness 应该捕获 Agent 的每一步思维链、每次工具调用、以及最终决策。例如，你的 Agent 内部可能调用了 analyze_diff 和 check_style 两个工具，Harness 需要记录每个工具的输入输出和耗时。

一个可执行做法：在 Agent 代码中埋入结构化日志，用 JSON 格式输出每个步骤的 context。测试时，Harness 既能断言最终结果，也能检查中间步骤是否合理。比如，断言 analyze_diff 的返回中是否包含函数签名变更。

第三步：断言输出，而不仅仅是「通过/不通过」

简单断言 Agent 的最终输出是 pass 还是 fail 远远不够。Harness 应该允许你检查输出的结构、内容甚至语气。例如，对于代码审查 Agent，可以断言：

输出必须包含 approved: true/false 字段
如果 diff 中有安全漏洞，评论必须包含词 "vulnerability"
如果 diff 仅涉及文档，Agent 必须跳过审查

一个容易失败的地方：断言写得太具体，导致 harness 和 Agent 强耦合。一旦 Agent 的输出格式调整，harness 就全挂了。建议断言定义在接口层，用 schema（如 Pydantic 或 JSON Schema）而不是硬编码字段路径。

真实场景：从 GitHub PR 到本地 Harness

我的一位同事曾用 Harness 测试他的代码审查 Agent。他 mock 了一个包含 SQL 注入修复的 PR diff，期望 Agent 的 approve 为 true，并且评论中出现 "LGTM"。第一次运行，Agent 确实 approve 了，但输出的是 "Looks good to me"，Harness 断言失败，因为用例大小写不匹配。他就此修复了 prompt，要求 Agent 始终使用 "LGTM"。

这个小例子说明：Harness 不仅能验证功能正确性，还能校验行为一致性。如果不在 harnees 中设定这些边界，Agent 在上线后可能用不同的表述混淆用户。

编辑器中展示一个 mocked 测试运行，代码中包含 mock 数据和断言逻辑。

容易失败的地方与错误理解

误解：Harness 是测试框架。实际上，Harness 更接近一个可控制、可重复的运行环境，而不仅仅是 assert 工具。它管理 mock、日志、断言、甚至 Agent 生命周期。
陷阱：Mock 数据缺少边缘情况。真实 LLM 可能返回很长的文本或空内容，mock 时需覆盖这些值。
陷阱：忽略时序依赖。有的 Agent 依赖步骤间时间间隔，harness 如果加速运行，可能改变行为。如需要，可以在 harness 中引入虚拟时钟。

笔记本电脑上显示的 QA 检查清单，列出 Harness 设计中需覆盖的边界条件。

如果你现在就要落地，第一步应该做什么

选定一个简单 Agent——比如单工具、单任务的 Agent（例如查询天气的 Agent）。
用 Python 写一个 Harness 类，包含 set_mock_response、run、assert_output 三个方法。
录制 3 种不同的真实用户查询，手动构造对应的 mock 输入。
运行 Harness，检查 Agent 输出是否符合预期。
故意引入一个错误（比如 mock 中缺少必要字段），观察 Harness 能否捕获失败。

完成这 5 步后，你就有了一套可复用的 Harness 基线，后续可以扩展断言粒度、引入日志收集等。

下一步去哪里继续系统化学习

如果你已经实践了上述步骤，接下来需要学习：如何将 Harness 集成到 CI/CD 流水线、如何设计多 Agent 协作场景的 Harness、以及如何将 Harness 与可观测性工具（如 Langfuse）结合。高质量原创付费文章和 AI 编程进阶课程会覆盖这些内容，帮你从普通开发者系统化转型为 Agent 工程师。