2.1 Agent Harness：Agent 的运行框架#

Harness 可以理解为 Agent 外部的运行与控制框架。

它不只是一个 Prompt，而是决定 Agent 如何工作的整套配置和基础设施。

通常包含：

例如，一个财务尽职调查 Agent 不仅需要知道如何分析财务资料，还需要遵守一些明确规则：

• ARR 必须使用指定来源的数据。
• 不同口径的 ARR 不能随意混用。
• 客户集中度必须按照合并后的母公司口径计算。
• 没有 CAC Payback 数据时，不允许编造数值。
• SOC 2 Type I 和 Type II 必须正确区分。

这些规则既可以写进 Prompt，也可以由代码验证器强制执行。

关键认识：Prompt 负责引导模型，Harness 负责把 Agent 的行为约束、工具执行和结果验证组织起来。

2.2 Trace：记录 Agent 实际做了什么#

Trace 是一次 Agent 执行任务的完整追踪记录。

假设用户问：

帮我查询飞书项目的最新状态，并创建一个跟进任务。

一次 Trace 可能包含：

1. 用户输入。
2. Agent 接收任务。
3. 模型生成工具调用。
4. Agent 调用飞书查询接口。
5. 工具返回项目状态。
6. 模型生成创建任务的工具调用。
7. 飞书 API 实际执行创建操作。
8. 工具返回任务 ID。
9. Agent 向用户回复结果。

每一步还可以记录耗时、输入输出、异常和调用关联关系。

其中，Trace 里的 Span 表示一次具体操作，例如模型调用、工具执行或某个处理步骤。

一个 Trace 可以包含多个 Span，组成一条完整的执行链路。

Trace 的价值在于：它让开发者能够根据实际执行证据分析 Agent，而不是只看最终回答。

例如：

• 最终回答说“任务创建成功”，但 Trace 中没有工具执行记录。
• 工具调用确实发生了，但 API 返回了权限错误。
• API 创建成功，但模型没有正确读取工具返回的任务 ID。

这三种情况的最终表现可能相似，但根本原因完全不同，需要采用不同的修复方式。

2.3 Feedback：对 Agent 行为进行评价#

Trace 只能告诉我们发生了什么，不能自动决定这种行为是否符合业务要求。

因此，还需要 Feedback。

Feedback 可以来自两个渠道：

人工反馈

由开发者、业务专家或用户判断：

• 哪个行为是错误的？
• 为什么错误？
• 正确行为应该是什么？
• 哪些结论绝对不能出现？

模型反馈

利用 LLM 分析多条 Trace，识别反复出现的问题，例如：

• 经常忽略某个重要数据源。
• 遇到缺失信息时容易过度推断。
• 在工具失败后仍然报告成功。
• 多次出现相同类型的引用错误。

人工反馈提供业务判断，模型反馈帮助归纳和扩展问题覆盖范围。

需要注意，模型生成的反馈只是分析结果，不一定正确，仍然需要验证。

2.4 Eval：把“做得好不好”变成可测试的标准#

Eval 是用于评估 Agent 行为的测试用例或评测任务。

传统软件测试通常检查明确的输入输出：

1
输入：2 + 3
2
预期输出：5

但 Agent 的输出可能具有一定自由度，因此评测不仅要检查结果，还需要判断行为是否符合预期。

例如：

1
测试场景：飞书创建任务失败
2

3
输入：
4
用户要求创建一个跟进任务。
5

6
实际情况：
7
飞书 API 返回权限错误。
8

9
预期行为：
10
Agent 必须明确告知用户创建失败。
11

12
禁止行为：
13
Agent 不得声称任务已经创建成功。
14

15
通过条件：
16
回复明确表达失败，且没有虚构任务 ID。

Eval 的作用，是将一次性的错误转化为可以反复执行的测试。

这样，即使以后修改 Prompt、模型配置或工具代码，也可以重新运行同一组测试，判断之前的问题是否再次出现。

2.5 Regression Test：防止修复旧问题时引入新问题#

假设 Agent 经常在工具执行失败后谎报成功。

开发者修改了成功状态判断逻辑，解决了这个问题，但又导致正常成功时无法识别工具返回结果。

这就是回归问题。

因此，不能只测试刚刚修复的错误，还需要重新运行以前积累的测试集。

Eval 用来定义什么是正确行为，Regression Test 用来持续验证这些正确行为没有被后续修改破坏。

4.1 故意构造数据冲突#

文章设计了几个具有代表性的业务场景。

场景一：ARR 数值冲突

资料中存在多个不同口径：

• 董事会材料中的 ARR：4300 万美元。
• 财务控制资料中的 ARR：3690 万美元。
• 按 bookings 调整后的 ARR：4080 万美元。

Agent 不能简单地挑选一个看起来合理的数字，而应该识别数据来源、口径和可信度。

场景二：客户集中度

某个重要客户存在多个实体，分别记录在不同文件中。

合并到母公司层级后，该客户的 ARR 为 1240 万美元，而公司整体 ARR 为 3690 万美元。

客户集中度为：

如果 Agent 只看单个客户实体，就可能低估实际集中风险。

场景三：指标缺失

资料中出现未经验证的 NRR 122%，但没有足够证据将它当作正式指标。

同时，CAC Payback 缺失。

正确行为不是猜测 CAC Payback，也不是把未经验证的 NRR 当成确定事实，而是明确指出证据不足。

场景四：合规状态混淆

资料显示：

• SOC 2 Type I：已完成。
• SOC 2 Type II：仍在进行中。

Agent 不能将 Type I 已完成直接推导为 Type II 已完成。

4.2 为什么要故意制造这些问题？#

如果测试数据过于简单，Agent 可能只需要提取数字和生成摘要就能通过。

但真实 Agent 面对的是有冲突、有缺失、有歧义的数据。

因此，测试数据应该包含那些容易让 Agent 犯错的情况，例如：

• 多个来源相互冲突。
• 指标口径不同。
• 同一客户存在多个实体。
• 重要数据缺失。
• 资料只支持部分结论。
• 表面上合理但实际上不成立的推断。

测试数据的价值，不只是验证 Agent 能否完成任务，更是暴露它在哪些条件下会失败。

5.1 两种不同的验证器#

文章设置了两个验证脚本。

验证器一： check_evidence_coverage.py

检查证据覆盖情况，例如：

• 引用的文件是否存在。
• 需要引用的地方是否缺少引用。
• 输出是否包含预期的证据关联。

验证器二： validate_output_contract.py

检查输出契约，例如：

• 必需文件是否生成。
• JSON 是否符合预期结构。
• 引用路径是否合法。
• 输出格式是否满足约定。

这两种验证器关注的是不同问题。

前者主要关注证据覆盖，后者主要关注交付格式和结构约束。

5.2 验证器的关键局限#

必须区分三个层次：

1. 文件存在： Agent 确实生成了所需文件。
2. 引用存在： Agent 确实附上了来源。
3. 证据支持结论： 来源中的内容真的能够证明 Agent 的结论。

前两项相对容易用代码检查，第三项则更困难。

例如，Agent 在报告中写道：

公司已经完成 SOC 2 Type II 认证。

它引用的文件确实存在，引用路径也正确，但文件实际写的是 Type II 仍在进行中。

如果验证器只检查文件和引用路径，这个错误就可能通过。

因此，验证器不能只检查“有没有引用”，还需要逐步检查“引用是否支持结论”。

这也是文章后续提出强化验证器的重要原因。

6.1 Trace 记录什么？#

文章中的 TraceRecord 保存了任务级别的信息，例如：

• trace_id
• sdk_trace_id
• label
• question
• answer
• output_dir
• mode

这些字段将用户问题、运行结果和 SDK 生成的 Trace 关联起来，方便后续定位和分析。

此外，文章还将 Agents SDK 的执行 Span 导出为 OpenTelemetry 风格的 JSONL 数据，提供给后续的分析工具使用。

这里的关键是：Trace 不只是最终回答的存档，还应该保留足够的执行过程，让后续系统可以分析 Agent 为什么产生这个结果。

6.2 从执行结果中发现问题#

例如，Agent 计算得出：

• 每月现金消耗约 290 万美元。
• 现金跑道约 11 个月。
• 财务控制口径的 ARR 为 3690 万美元。
• 母公司层级客户集中度约为 33.6%。

对于缺失的 CAC Payback，Agent 应该明确指出资料不足，而不是自行推测。

这些运行结果既是业务任务的交付内容，也是后续评估和改进的数据来源。

五次运行可以帮助演示完整闭环，但不能代表 Agent 已经在所有场景中可靠。

7.1 人工反馈#

人工反馈需要将“这个回答不好”转化为结构化信息。

例如：

1
{
2
  "feedback_id": "feedback_001",
3
  "trace_id": "trace_001",
4
  "question": "What is the company's ARR?",
5
  "source_type": "human",
6
  "theme": "source_of_truth",
7
  "summary": "Agent selected an unsupported ARR figure.",
8
  "required_observations": [
9
    "Distinguish board-reported ARR from finance-controlled ARR",
10
    "Explain which source is used"
11
  ],
12
  "prohibited_claims": [
13
    "Treating an unverified ARR figure as authoritative"
14
  ]
15
}

这是用于说明字段含义的示例。

结构化反馈可以清楚地表达：

• 哪次执行出现问题。
• 问题属于什么类型。
• 为什么这是一个问题。
• 正确行为应该包含什么。
• 哪些错误结论不允许出现。

这样，反馈就不再只是一段无法直接利用的主观评论，而可以成为后续生成 Eval 的输入。

7.2 LLM Feedback#

人工通常只会审查有限数量的执行记录，而模型可以帮助分析更多 Trace。

例如，对多条 Trace 进行归纳后，发现 Agent 反复出现以下问题：

• 过度相信未经验证的数据。
• 忽略来源之间的冲突。
• 没有明确说明缺失信息。
• 将形式上存在的引用误认为有效证据。

模型可以把这些重复模式整理为问题类别，帮助扩展测试覆盖范围。

但模型的归纳结果不能直接视为事实。

如果它误判了某次执行，后续生成的 Eval 也可能跟着出错。因此，人工判断仍然是重要的质量控制环节。

8.1 Eval 包含什么？#

文章中的 Eval 数据包含以下信息：

• eval_id：测试用例标识。
• title：测试名称。
• scoring_method：评分方式。
• expected_behavior：预期行为。
• source_trace_id：来源 Trace。
• rubric：评判标准。
• deterministic_assertions：确定性断言。
• pass/fail examples：通过与失败示例。

其中，source_trace_id 很重要，因为它将测试用例与真实失败或相关执行记录关联起来。

开发者不仅知道测试失败了，还能回到原始 Trace 理解测试为什么存在。

8.2 三种评分方式#

第一种：Deterministic（确定性评分）

通过程序直接检查明确的条件。

例如：

• 必须生成指定文件。
• JSON 必须能够解析。
• 必须包含某个字段。
• 工具调用失败后，不允许返回成功状态。
• 没有成功执行证据时，不允许将任务标记为完成。

优点是结果稳定、可重复。

局限是只能检查能够明确表达为程序规则的条件。

第二种：LLM Judge（模型评审）

让另一个模型根据评分标准判断输出是否正确。

例如，判断 Agent 是否正确解释了两个财务数据来源之间的冲突。

优点是能够评估复杂的自然语言行为。

局限是评审模型本身也可能出错，同一输出也可能受到模型、提示词和评审标准的影响。

第三种：Hybrid（混合评分）

同时使用程序断言和模型评审。

例如：

• 程序检查是否存在引用。
• 程序检查必需字段。
• 模型判断引用内容是否真正支持结论。

对于复杂 Agent，这种组合通常比单独使用某一种方式更实用。

8.3 文章生成了哪些测试？#

文章将主要问题转化为五个 Eval：

1. Runway / Burn Risk： 正确分析现金消耗和资金跑道。
2. ARR Source of Truth： 正确区分不同来源的 ARR。
3. Parent-account Rollup： 正确合并母公司层级客户并计算集中度。
4. SOC 2 Type I / Type II： 正确区分两种合规状态。
5. Unsupported Metrics Refusal： 对缺乏证据的指标拒绝编造结论。

这些测试覆盖了数据口径、计算、业务实体合并、状态判断和证据不足等不同类型的问题。

8.4 自动生成的 Eval 不能不经检查就直接使用#

模型可以根据失败案例生成测试，但它可能：

• 错误理解原始问题。
• 把偶然出现的行为当成普遍规则。
• 生成不合理的预期结果。
• 把错误的判断标准固化进测试集。

如果测试本身有问题，系统可能会要求 Agent 学会满足错误标准。

因此，合理的流程是：

1. 从 Trace 和反馈中生成 Eval。
2. 人工检查预期行为和评分标准。
3. 修正测试用例。
4. 将确认过的 Eval 保存到持久化测试集。
5. 后续每次改动都重复执行这些测试。

Agent 的失败提供测试素材，但测试的正确性仍然需要得到保证。

Eval Gate 的意义#

Eval Gate 是一个质量门禁。

在 Agent 的 Prompt、工具逻辑或代码发生修改之后，先运行测试，再决定是否允许进入下一阶段。

例如：

1
修改代码
2
   |
3
   v
4
运行 Eval Suite
5
   |
6
   +---- 测试失败 ----> 阻止发布，分析问题
7
   |
8
   +---- 测试通过 ----> 进入人工审核或后续发布流程

这样，测试结果就成为工程流程的一部分，而不是开发者偶尔执行的检查。

10.1 为什么不能只看 Eval 结果？#

因为 Eval 主要告诉我们：某个测试通过了还是失败了。

但它不一定能解释整个系统还存在哪些结构性问题。

例如：

• 为什么某些错误总是重复出现？
• 为什么一个验证器通过了，实际输出却仍然存在错误？
• 是 Prompt 不够明确，还是验证逻辑本身不完整？
• 哪项改进最有可能提升整体可靠性？

HALO 的价值在于把多个来源的信息放在一起分析，而不是孤立地看单个失败结果。

10.2 输出结构化的改进报告#

文章中的 HALO 会生成 codex_handoff.md，用于向后续编码环节传递建议。

报告包含：

• 执行结果的摘要。
• 优先级最高的改进事项。
• 排序后的建议表。
• 支持建议的执行证据。
• 详细的改进说明。
• 来自不同反馈来源的洞察。
• 机器可读的摘要信息。

这份文件相当于一份有证据支撑的工程任务说明。

它不只是告诉开发者“这里可能有问题”，还要解释问题的证据、优先级和建议的修改方向。

11.1 建立确定性的业务事实台账和领域检查清单#

第一项建议是增加 Deterministic Diligence Fact Ledger，并将领域检查清单显式纳入系统。

核心目标是：不要把所有业务约束都寄托在模型是否记得 Prompt。

例如，尽职调查任务需要明确检查：

• ARR 使用哪个数据来源。
• 现金消耗和资金跑道是否正确。
• 客户集中度是否按照母公司口径计算。
• 未经证实的指标是否被标记。
• SOC 2 的状态是否准确。
• 缺失指标是否被明确指出。

这些业务不变量可以通过结构化事实台账、领域规则和代码验证器实现。

这样，Agent 在生成最终报告时，不必完全依靠模型临场回忆所有约束。

11.2 让验证器直接审计真实输出#

第二项建议是加强验证器。

不能只检查 Agent 是否声称自己完成了检查，也不能只检查引用路径是否存在。

验证器应该直接读取实际生成的 Markdown、JSON 和 CSV 文件，识别重要结论，并检查这些结论是否得到证据支持。

例如：

1
Agent 输出：
2
SOC 2 Type II 已完成。
3

4
引用文件：
5
soc2_status.md
6

7
文件实际内容：
8
Type I 已完成，Type II 正在进行中。
9

10
验证结果：
11
失败，输出结论与证据不一致。

这个例子体现了一个重要原则：

验证器必须检查实际交付物，而不是只相信 Agent 对自身行为的描述。

这也能发现一种常见问题：Agent 在验证器通过之后仍然产生不正确的结论，说明当前验证器的检查范围可能不够完整。

11.3 将 Eval 持久化为回归测试集#

第三项建议是将生成并经过确认的五个 Eval 保存到代码仓库中，形成长期维护的 Regression Suite。

这意味着：

• 测试不再只是某次实验的临时产物。
• 每次修改 Harness，都可以重复运行同一套测试。
• 新增失败案例时，可以继续扩充测试集。
• 代码修改可以通过测试结果判断是否改善了系统。
• 已经修复的问题可以被持续监控，防止再次出现。

这一点尤其重要。

如果每次发现错误都只改代码、不保留测试，那么相同的问题很可能在下一次改动中再次出现。

11.4 为什么 5/5 通过仍然需要改进？#

文章的示例中，虽然五个 Eval 全部通过，HALO 仍然提出增强验证器和持久化测试集的建议。

原因是：当前测试通过，只能说明已知的测试条件得到满足，不代表系统已经充分覆盖所有重要风险。

工程改进不应该只看测试是否通过，还要看：

• 测试集是否覆盖了关键失败模式。
• 验证器能否发现真实输出中的错误。
• 新的失败能否进入回归测试集。
• 后续修改是否有可靠的质量门禁。

12.1 人工审核驱动#

在关键节点设置人工检查：

• Trace Review：检查真实执行记录。
• Eval Refinement：审查自动生成的测试。
• PR Approval：审核代码修改。
• Merge：决定是否合并代码。
• Deploy：决定是否部署到生产环境。

这种模式更适合刚开始建设 Agent 改进系统的团队。

它保留了自动化带来的效率，同时让人工把关业务判断和高风险操作。

12.2 更高程度的自动化#

在自动化程度更高的工作流中，可以将 HALO 生成的改进任务放入共享存储，由 Codex 等编码 Agent 自动读取并执行。

完整流程可以是：

1
真实 Agent 运行
2
      |
3
      v
4
收集 Trace 和反馈
5
      |
6
      v
7
生成 Eval 并执行
8
      |
9
      v
10
分析改进建议
11
      |
12
      v
13
生成代码修改任务
14
      |
15
      v
16
Codex 修改代码
17
      |
18
      v
19
运行回归测试
20
      |
21
      v
22
创建 PR / 人工审核
23
      |
24
      v
25
合并与部署

但自动化并不意味着取消控制。

随着 Agent 获得更大的代码修改和部署权限，系统还需要考虑：

• 权限隔离。
• 测试失败时的阻断。
• 人工审批。
• 变更记录。
• 失败回滚。
• 防止自动修复反复循环。
• 避免错误评测标准导致错误修改。

更合理的方向不是让系统无条件地自动修改和发布，而是让它在明确的权限和质量门禁内持续迭代。

原则一：以真实执行证据为基础#

不能只依靠最终回答分析问题。

需要保留实际的模型调用、工具调用、工具结果和执行状态，才能判断错误究竟发生在哪一层。

原则二：将问题转化为可重复验证的标准#

反馈如果不能转化为测试，就很容易随着时间被遗忘。

每次出现重要失败，都应该思考：

能不能用一条测试，把这个问题永久记录下来？

原则三：每次修改都需要重新验证#

修改代码并不意味着问题一定解决。

只有通过测试验证，才能说明这次改动满足了既定标准；如果测试覆盖不足，还需要继续补充测试。

第一阶段：Trace 采集#

先让系统能够回答：

• Agent 收到了什么输入？
• 模型实际输出了什么？
• 它请求调用了哪个工具？
• 工具是否真的执行？
• 工具返回了什么？
• 每一步花了多长时间？
• 哪一步发生了异常？
• Agent 是否重试，重试了几次？

尤其要区分模型生成的 Tool Call 意图与工具执行器真正执行的结果。

例如：

1
模型请求调用工具
2
        |
3
        v
4
执行器是否接收到请求？
5
        |
6
        v
7
工具是否真正执行？
8
        |
9
        v
10
执行是否成功？
11
        |
12
        v
13
Agent 是否正确处理返回结果？

这几个阶段不能简单合并为一个“工具调用成功”状态。

第二阶段：失败标注#

为每条 Trace 增加人工标注能力，例如：

1
failure_type:
2
  - wrong_tool
3
  - tool_not_executed
4
  - tool_execution_failed
5
  - hallucinated_success
6
  - unsupported_claim
7
  - wrong_final_answer
8
  - retry_loop
9
  - handoff_error

这些类别只是可以采用的设计示例，并非文章规定的固定字段。

每条失败记录还应该包含：

• 对应的 Trace ID。
• 失败发生在哪个 Span。
• 错误描述。
• 预期行为。
• 修复建议。
• 严重程度。

第三阶段：建立 Eval 数据集#

将确认过的失败记录转换为可重复执行的测试。

例如：

1
测试名称：
2
工具没有执行成功时，Agent 不得报告成功。
3

4
输入：
5
用户要求创建飞书任务。
6

7
模拟工具结果：
8
API 返回权限错误。
9

10
预期行为：
11
Agent 明确告知任务创建失败。
12

13
禁止行为：
14
Agent 声称任务已经创建成功。

对于能够明确判断的情况，优先使用确定性断言；对于语义复杂的情况，再使用 LLM Judge。

第四阶段：回归测试#

每次修改 Prompt、工具代码或执行器逻辑后，重新运行历史测试。

测试结果可以包括：

• 通过率。
• 新增失败数量。
• 旧问题是否复现。
• 不同失败类型的变化。
• 每个测试的执行耗时和成本。

第五阶段：再引入自动化改进#

前四个阶段稳定之后，再让模型自动归纳问题、提出改进方案，甚至辅助修改代码。

在此之前，不必急着构建能够自行修改和发布代码的全自动 Agent。

最小闭环先解决“看得见问题、记得住问题、验证得了修复”，再考虑“自动分析问题、自动修改代码”。

1. Trace：知道 Agent 实际做了什么#

Trace 负责记录真实执行过程，包括模型调用、工具调用、工具结果、耗时和异常。

它解决的是可观测性问题：当 Agent 出错时，开发者可以定位问题发生在哪个环节，而不是只根据最终回答猜测原因。

2. Feedback：判断 Agent 为什么做得不好#

Trace 记录事实，Feedback 对行为进行评价。

人工反馈负责提供业务判断和正确行为标准，LLM Feedback 则帮助从多条执行记录中归纳重复出现的问题。

它解决的是问题识别问题：不仅要发现失败，还要知道什么行为是错误的、为什么错误。

3. Eval：把失败变成可重复执行的测试#

Eval 将一次性的失败转化为明确的测试场景、预期行为和通过标准。

它解决的是问题固化问题：把经验保存下来，不再依赖开发者的记忆。

4. Eval Gate：验证修改是否真的有效#

每次修改 Prompt、工具或代码后，都重新执行测试集。

它解决的是质量保障问题：防止修复旧问题时引入新问题，也避免开发者凭感觉判断改动是否有效。

5. HALO + Codex：分析问题并辅助实施改进#

HALO 汇总 Trace、反馈和测试结果，分析值得优先处理的问题；Codex 根据改进建议辅助修改代码。

它们解决的是改进效率问题：减少人工分析和实施修改的成本。

这五个环节串起来，就是：

记录事实 → 判断问题 → 固化标准 → 验证修复 → 持续改进。