Session 24: testing — how to test an agent system

传统后端系统的测试相对容易理解:给定输入,检查输出是否符合预期。Agent 系统多了一层不确定性,LLM 的输出不固定,工具调用可能变化,执行路径也可能受到模型决策影响。

Originally in ChineseThis article was written in Chinese. The body below is the Chinese original; the English translation is not available yet.

测试 Agent 时,我更倾向于先区分是否使用 Mock LLM。Mock 的部分主要验证程序逻辑和执行流程;使用真实 LLM 的部分主要检查模型行为与最终结果是否符合要求。再通过端到端测试,把这些检查放到完整任务中验证。

一、Mock LLM:测试程序逻辑和执行流程

Mock LLM 的主要价值是让模型输出可控。测试时不必每次调用真实模型,可以预先定义不同场景下的模型响应,然后检查 Agent 是否按照预期执行。

以 Research Agent 为例,假设它需要获取研究主题、搜索资料、判断证据是否充分,最后生成研究报告。

正常流程可以预先安排好模型的响应:

text
第 1 次 LLM 调用:
返回搜索关键词

第 2 次 LLM 调用:
请求调用 search_tool

第 3 次 LLM 调用:
判断当前证据不足,要求补充搜索

第 4 次 LLM 调用:
根据补充材料生成报告

测试中可以使用预先准备好的响应,检查程序是否正确处理每一步。

测试对象 主要检查内容
整体流程 节点是否按预期执行,任务是否正常结束
Tool 调用 是否调用正确的工具,参数是否符合预期
分支判断 不同的模型响应是否进入正确的分支
State 更新 搜索结果、任务状态、重试次数是否正确更新
错误处理 超时、异常响应、工具失败后是否采取正确措施
故障恢复 Checkpoint 恢复后是否继续正确的执行流程
循环控制 达到最大搜索次数或重试次数后是否正常终止

例如,可以模拟搜索工具返回空结果,检查 Agent 是否进入补充搜索分支;模拟工具连续失败,检查程序是否在达到重试上限后终止或切换到预设的降级方案。

这些场景往往比单纯测试正常流程更有价值。生产环境中,很多问题发生在异常分支、状态更新和恢复逻辑上,而这些恰好可以通过 Mock 稳定复现。

1.1 一个简单的 Mock 示例

下面用一个简化的 Python 示例说明如何测试工具调用决策。实际项目可以使用 unittest.mock、pytest 或测试框架提供的模型替身。

text
from unittest.mock import Mockdef run_research_step(llm, tools, state):    response = llm.invoke(state["messages"])    if response["type"] == "tool_call":        tool_name = response["tool"]        tool_args = response["args"]        result = tools[tool_name](**tool_args)        return {            "tool_result": result,            "next_step": "analyze",        }    return {        "report": response["content"],        "next_step": "finish",    }def test_search_tool_call():    llm = Mock()    llm.invoke.return_value = {        "type": "tool_call",        "tool": "search",        "args": {"query": "Agent 工程化"},    }    search = Mock(return_value=["资料 A", "资料 B"])    result = run_research_step(        llm,        {"search": search},

这个测试不关心真实模型会不会提出这些搜索关键词。它只验证:当模型返回指定的工具调用请求时,程序能否正确执行工具并更新流程状态。

真实的 LangGraph 项目中,可以采用相同思路测试节点、条件边和工具执行逻辑。对于需要测试的模型响应,可以用固定的模型客户端替代真实模型;对于工具,也可以用 Mock 返回预设结果。

需要注意,Mock 测试只能证明程序在这些预设输入下表现正确,无法证明真实模型一定会产生这些输入。因此,它不能替代真实模型测试。

1.2 Mock Tool 与真实 Tool 也需要区分

即使 LLM 使用 Mock,工具层也不一定全部使用 Mock。

例如,测试 Agent 能否正确处理搜索工具返回的空结果,可以 Mock 搜索工具;测试搜索 API 的认证、参数格式、超时和真实返回结构,则需要单独的工具集成测试。

同样,测试数据库操作时,可以使用测试数据库验证实际 SQL、事务和约束,而不是只检查 Mock 对象有没有被调用。

通常可以把测试拆成两部分:一部分验证 Agent 如何使用工具,另一部分验证工具自身是否可靠。这样出现问题时,更容易判断故障发生在哪一层。

二、真实 LLM:测试结果是否符合要求

当测试使用真实 LLM 时,输出可能存在变化。同一个 Prompt,模型可能使用不同的措辞、组织不同的段落,甚至选择不同的搜索关键词。

因此,测试不能过度依赖完整文本的精确匹配。

例如:

text
assert result == "这是一份完整的研究报告"

这种断言只适用于输出必须完全固定的场景。对于开放式的研究报告生成,它很容易因为措辞变化而失败,也无法有效判断报告质量。

更合理的方式是先定义任务的验收条件,再根据不同条件选择适当的检查方法。

2.1 能够用程序检查的结果,尽量用程序检查

Research Agent 的输出可以分成几个层次。

检查维度 检查示例 检查方式
任务完成情况 是否进入完成状态 程序断言
输出结构 是否包含标题、结论、证据等章节 结构校验
数据完整性 是否包含必要字段 Schema 校验
来源有效性 引用的来源 ID 是否真实存在 程序校验
执行限制 搜索次数、重试次数是否超限 计数与边界检查
内容质量 结论是否有证据支持 规则、模型评估或人工审核

例如,报告中引用的来源必须来自实际检索结果,就可以写成确定性的检查:

text
def validate_citations(report, retrieved_sources):    source_ids = {        source["id"]        for source in retrieved_sources    }    cited_ids = set(report["citation_ids"])    invalid_ids = cited_ids - source_ids    if invalid_ids:        raise ValueError(            f"引用了不存在的来源:{invalid_ids}"        )

这里能够保证引用 ID 存在于检索结果中,但还不能证明引用内容真正支持对应结论。来源真实性、引用对应关系和论证充分性是不同的检查维度,不能用一个简单的断言全部覆盖。

2.2 内容质量需要专门的评估方法

对于研究报告,常见的质量问题包括:

  • 报告是否回答了原始研究问题。
  • 核心结论是否有足够证据支持。
  • 是否遗漏了重要的相反证据。
  • 是否存在事实错误或无依据的推断。
  • 是否正确表达了证据不足的部分。

有些问题可以使用规则或结构化检查,有些需要结合 LLM 评估,也可能需要人工审核。

例如,可以让评估模型根据明确的标准判断报告是否覆盖研究问题、引用是否与结论相关。但评估模型本身也会犯错,因此不能简单地把另一个 LLM 的判断当成绝对正确的结果。

对于高风险或高价值的任务,可以把程序校验、独立评估模型和人工抽查结合起来。评估结果最好保留具体的失败原因,而不只是输出一个笼统的分数。

2.3 为测试准备固定的验收标准

真实 LLM 的输出可以变化,但验收条件应尽可能明确。

例如,某个 Research Agent 的测试要求如下:

text
def test_research_report(result, retrieved_sources):    assert result["status"] == "completed"    report = result["report"]    assert report["title"]    assert report["conclusion"]    assert len(report["evidence"]) >= 3    validate_citations(        report,        retrieved_sources,    )    assert result["tool_call_count"] <= 10

这段代码展示的是测试思路,实际项目需要根据自己的 State 和报告数据结构调整。

这里的重点是:不要求模型每次写出相同的句子,但要求它满足明确的任务约束。对于证据数量、引用有效性、状态完成情况和工具调用上限等条件,尽量采用确定性的验证。

三、端到端测试:验证完整任务是否真正完成

单元测试和图流程测试能够覆盖局部逻辑,但 Agent 的问题也可能出现在多个组件之间的配合上。

例如,工具调用本身没有问题,报告生成节点也能正常运行,但前一个节点输出的数据结构与后一个节点预期不一致,最终仍然可能导致任务失败。

端到端测试需要从真实任务输入开始,经过必要的模型调用、工具调用和状态流转,最后检查完整任务是否符合要求。

以 Research Agent 为例,可以准备一组固定的研究任务,并为每个任务定义明确的验收标准。

检查项 验收条件
任务状态 最终状态为 completed
工具调用 实际执行过必要的搜索工具
来源数量 至少获得规定数量的有效来源
引用校验 所有引用 ID 都存在于实际检索结果中
报告结构 包含要求的章节和字段
执行边界 工具调用次数、循环次数不超过上限
异常处理 模拟工具失败后,按规则重试、降级或终止

端到端测试不一定要让所有外部依赖都保持真实。比如,可以使用真实 LLM,但固定搜索工具返回的数据,以便减少搜索结果变化带来的干扰。

这种方式可以验证真实模型的决策与生成行为,同时让部分测试条件保持可控。对于需要检查真实搜索接口、模型服务或数据库兼容性的场景,再单独安排集成测试。

还需要注意,任务成功结束不等于任务质量合格。Agent 可能完成了所有工具调用,却生成了一份结论错误的报告。因此,端到端测试既要检查执行过程,也要检查最终产物。

四、LangGraph 中如何组织测试?

LangGraph 将 Agent 的执行组织成节点、边和共享 State,因此可以围绕这些组件设计测试。

4.1 节点测试

节点测试主要验证输入 State 在经过节点处理后,是否产生了预期的状态更新。

例如,分析节点收到一组搜索结果后,应当输出分析结果和证据充分性判断。可以直接调用节点函数,或者为节点依赖的模型客户端和工具提供 Mock。

这类测试适合覆盖状态字段、异常输入、输出格式和业务规则,不需要每次都启动整张图。

4.2 图流程测试

图流程测试关注节点之间的协作。

例如,Research Agent 判断证据不足后,应该返回搜索节点继续补充资料;达到最大搜索次数后,应该进入报告生成或证据不足的结束分支,而不是无限循环。

这类测试可以通过 Mock LLM 返回不同的结构化结果,验证条件边是否进入正确的节点。

测试时还应覆盖异常路径,例如工具失败、模型返回格式错误、没有检索到结果,以及达到重试上限等场景。

4.3 Checkpoint 与恢复测试

持久化测试需要验证:任务暂停或进程中断后,是否能够利用保存的状态恢复执行。

例如,可以让 Agent 在搜索和分析完成后暂停,确认 checkpoint 中保存了必要的状态,再通过相同的 thread_id 恢复执行,检查后续流程是否正常完成。

如果使用 interrupt 实现 Human-in-the-Loop,还应验证:

  • 暂停时是否保存了恢复所需的状态。
  • 使用正确的 thread_id 和恢复输入后,是否继续执行。
  • 审批拒绝时是否进入拒绝分支。
  • 重复提交审批请求时,业务层是否正确处理。
  • 恢复执行时,是否意外重复执行外部副作用。

这类测试尤其要区分图状态恢复与外部业务操作的一致性。即使 checkpoint 恢复正确,也需要另外验证外部接口的幂等和去重逻辑。

五、回归测试:修改之后,原来的能力还在吗?

Agent 项目会不断修改 Prompt、模型、工具描述、State 结构和工作流程。一次改动可能解决了当前问题,却让之前正常的任务发生退化。

例如,修改 Research Agent 的 Prompt 后,报告结构变得更好,但模型开始过度搜索;切换模型后,成本降低了,却经常遗漏重要来源。

如果没有回归测试,就只能依赖人工试用发现问题,难以判断修改到底改善了什么,又损害了什么。

比较实用的做法是维护一组有代表性的任务样本:

测试样本 主要验证内容
正常研究任务 能否完成搜索、分析和报告生成
无有效搜索结果 是否正确处理证据不足
工具连续失败 重试和降级是否符合预期
相互矛盾的来源 是否识别冲突并谨慎处理
复杂研究主题 是否满足任务要求,执行是否超限
人工审批任务 是否能暂停、恢复并正确处理审批结果

每次修改 Prompt、模型或流程后,重新运行这些样本,并比较关键指标,例如任务完成率、引用有效率、工具调用次数、成本、延迟和质量评估结果。

回归测试可以分为两部分:一部分使用 Mock,快速检查程序行为是否发生意外变化;另一部分使用真实模型,检查实际任务质量是否出现退化。

真实模型测试的结果可能波动,因此最好在相同的测试数据和尽可能一致的运行条件下比较。如果任务重要、波动较大,可以多次运行,观察整体趋势,而不是只根据单次结果作出结论。

六、如何控制测试成本?

Agent 测试可能涉及多轮 LLM 调用、搜索 API、数据库操作和其他外部服务。如果所有测试都调用真实模型,不仅成本较高,执行速度也会变慢。

可以按测试目的选择执行方式:

测试类型 推荐方式 原因
高频单元测试 不调用真实 LLM,或使用 Mock 快速、稳定
图流程测试 Mock LLM 和部分 Tool 覆盖大量分支与异常路径
工具集成测试 真实工具或测试环境 验证接口与数据格式
端到端测试 真实 LLM,固定部分依赖 验证完整任务行为
回归测试 Mock 与真实模型结合 兼顾程序稳定性和任务质量

对于真实模型测试,还可以控制测试集规模、使用固定的测试输入、限制最大工具调用次数,并记录每次运行的 Token 消耗和执行时间。

不必每次修改一个普通的状态处理函数,就重新执行所有昂贵的端到端任务。可以先运行快速的单元测试和图流程测试,再根据变更范围决定是否运行完整的真实模型回归测试。

七、测试结果需要可追踪

Agent 测试失败时,只有一句 AssertionError 往往不够。还需要知道模型收到了什么消息、返回了什么内容、调用了哪个工具、State 如何变化,以及最终在哪一步失败。

因此,测试结果最好能够关联到一次完整的执行记录,包括:

  • 测试用例 ID、输入数据和验收标准。
  • 模型名称、Prompt 版本及关键参数。
  • LLM 请求与响应。
  • Tool 调用参数、返回结果和异常。
  • 节点执行路径、状态变化与重试记录。
  • 最终结果、失败原因、Token 消耗和延迟。

涉及敏感数据时,需要对日志进行脱敏,并限制访问权限。尤其是研究任务可能包含用户输入、内部资料和外部检索内容,不能为了调试方便就把所有原始数据无限期保留。

有了这些记录,测试失败才更容易定位到具体问题:是模型没有按照要求调用工具,是程序分支判断错误,还是工具返回数据异常,或者是状态恢复逻辑出现了问题。

八、总结

Agent Testing 可以围绕三条主线组织。

第一,Mock LLM,重点验证程序逻辑,包括工具调用、分支判断、状态更新、异常处理、故障恢复和循环控制。第二,使用真实 LLM,检查模型的实际行为与最终结果是否满足任务要求。第三,通过端到端测试验证完整任务,并使用硬性验收条件检查任务状态、工具执行、数据完整性和执行边界。

对于开放式的模型输出,不应过度依赖固定文本比较。能够用程序明确判断的条件,应尽量使用确定性断言;涉及内容质量的部分,则需要规则、专门的评估方法或人工审核。

最后,回归测试需要贯穿整个开发过程。Prompt、模型、工具和工作流程发生变化后,都可能影响原有能力。只有将固定测试样本、确定性检查和真实模型评估结合起来,才能更有把握地判断 Agent 的修改是否真的有效。

On this page