1. 项目概述为生产级LLM Agent构建确定性测试框架最近在折腾一个生产环境里的LLM Agent项目踩了不少坑。最头疼的问题莫过于每次更新Agent的提示词、逻辑流甚至只是换个底层大模型心里都没底。线上服务会不会崩回答质量会不会断崖式下跌传统的端到端测试要么成本太高每次都要调用昂贵的LLM API要么太“黑盒”出了问题根本不知道是哪个环节的锅。这让我开始思考能不能像测试传统软件一样给LLM Agent也搞一套稳定、高效、低成本的自动化测试方案于是就有了“Layer-Isolated Evaluation”层间隔离评估这个想法。简单来说这个项目的核心目标就是为复杂的生产级LLM Agent系统搭建一个“不用LLM”的、回归锁定的测试工具链。它不是一个简单的问答对匹配器而是一个工程框架旨在将Agent内部那些本应确定性的逻辑比如流程控制、工具调用、数据解析与不确定的LLM生成过程剥离开单独进行严格的、可重复的测试。这样一来我们就能在持续集成CI流水线里快速、廉价地验证Agent“骨架”的健壮性确保核心逻辑的每一次变更都是安全的把不确定性和成本留给真正需要LLM创造力的环节去处理。这适合谁呢如果你正在开发或维护一个涉及多步骤推理、工具调用、复杂流程的LLM Agent比如客服机器人、数据分析助手、自动化工作流引擎并且受困于测试的不可靠和高成本那么这个思路会给你带来直接的工程价值。它尤其适合那些已经将Agent投入生产需要进行频繁迭代和持续交付的团队。2. 核心设计思路隔离、锁定与确定性验证2.1 为什么需要“层间隔离”一个典型的LLM Agent架构可以粗略分为几个层次应用/流程层定义任务目标、拆解步骤、协调工具调用。这部分通常是基于代码或配置的确定性逻辑。编排/决策层根据当前状态和上下文决定下一步是调用工具还是请求LLM。这部分逻辑也应该是相对确定的。LLM交互层向大模型发送精心构造的提示词Prompt并解析其返回的非结构化文本。这是不确定性的主要来源。工具执行层执行具体的API调用、数据库查询、代码运行等。这部分的外部依赖可能引入不确定性。传统的端到端测试把所有这些层“一锅炖”用最终输出LLM生成的自然语言来评判整个系统。这带来了几个致命问题成本高昂每次测试都要调用LLM API无论是金钱还是时间成本都难以承受高频的CI/CD。结果不稳定LLM的输出具有随机性即使温度设为0不同版本模型也可能给出不同回答导致测试用例时而过时而过不了毫无可靠性可言。问题定位困难测试失败时你无法快速判断是提示词没写好、流程逻辑有bug还是工具API挂了。“层间隔离”的思路就是将第1、2层确定性骨架与第3层非确定性LLM进行解耦。我们为Agent的骨架搭建一个模拟环境在这个环境里LLM的响应被一个Mock服务所替代。这个Mock服务不调用真实LLM而是根据预先定义好的规则返回固定的、结构化的数据。这样我们就可以用极低的成本成千上万次地运行测试专门验证骨架逻辑的正确性。2.2 “回归锁定”测试工具链的精髓“Regression-Locked Test Harness”是这个框架的另一个核心。它不仅仅是做功能测试更是做回归测试并且是“锁定”的。回归测试确保新的代码变更不会破坏已有的、正常的功能。对于Agent来说就是确保对提示词、流程逻辑的修改不会导致之前能正确处理的任务现在出问题。“锁定”这里的“锁定”有两层含义。锁定LLM的输出通过Mock将LLM的不确定性输出“锁定”为确定性的测试数据。这些测试数据即Mock的响应本身需要被版本化管理作为测试基准。锁定核心行为测试用例所验证的不是LLM说了什么漂亮话而是Agent在接收到特定模拟的LLM响应后是否做出了正确的行为。例如是否调用了正确的工具调用时的参数是否正确流程状态是否按预期转换这个测试工具链会集成到你的CI/CD流程中。每次代码提交或合并请求都会自动触发这套测试。如果骨架逻辑的变更导致了与“锁定”的预期行为不符测试就会失败阻止有问题的代码进入生产环境。2.3 与非隔离测试的对比为了更直观地理解我们可以看一个对比表格测试类型测试对象LLM调用成本稳定性定位问题主要用途端到端测试整个Agent系统真实LLM API极高低受模型波动影响困难需层层排查验收测试、关键场景冒烟测试层间隔离测试Agent的确定性骨架流程、工具调用逻辑Mock服务无LLM极低高完全可控容易直接定位到逻辑层回归测试、CI/CD、快速迭代实操心得不要指望用层间隔离测试完全替代端到端测试。它俩是互补关系。隔离测试用于保障“骨架”的健壮性支持高频迭代而端到端测试则用于在发布前对集成后的完整系统进行最终验证尤其是检验LLM在真实提示词下的创造力是否符合预期。前者求“稳”后者求“全”。3. 构建No-LLM测试工具链的实操要点3.1 工具链的核心组件构建这样一个测试工具链你需要以下几个核心组件测试运行器可以是pytest,JUnit, 或任何你熟悉的测试框架。它负责组织、运行测试用例并报告结果。Agent骨架的测试接口你需要为你Agent的核心逻辑即剥离了真实LLM调用的部分暴露出一个可测试的接口。这通常是一个函数或类方法它接收“用户输入”和“模拟的LLM历史/响应”然后执行内部逻辑最终返回“下一步动作”如调用某个工具或“最终输出”。LLM Mock服务这是关键。你需要一个服务它能拦截Agent试图调用LLM API的请求并根据请求中的提示词Prompt或其他标识返回预先准备好的响应。这个Mock可以很简单比如一个内存中的字典映射{prompt_signature: mock_response}也可以很复杂支持基于正则表达式匹配或请求内容的部分匹配。测试数据管理用于存储和管理那些“锁定”的Mock响应和预期的Agent行为。这些数据应该被当作代码一样进行版本控制例如存放在tests/fixtures/目录下。断言库用于验证Agent的实际行为是否符合预期。不仅仅是比较字符串更要能断言“是否调用了工具A”、“调用工具B时的参数是否包含某个值”、“状态机是否从S1转移到了S2”。3.2 实施步骤详解假设我们有一个简单的“天气查询Agent”它的逻辑是1) 让LLM从用户输入中提取城市名2) 调用天气查询工具3) 让LLM格式化结果并回复。步骤一重构Agent代码使其可测试首先要将LLM调用部分抽象出来使其易于被Mock替换。# 原始不可测试的代码片段混合在一起 class WeatherAgent: def __init__(self, llm_client, weather_tool): self.llm llm_client self.tool weather_tool def run(self, user_input: str) - str: # 步骤1: 调用LLM提取城市 extraction_prompt f从以下用户输入中提取城市名{user_input} city self.llm.call(extraction_prompt) # 直接调用难以Mock # 步骤2: 调用工具 weather_data self.tool.query(city) # 步骤3: 调用LLM格式化 format_prompt f将天气数据{weather_data}组织成友好的回复。 final_response self.llm.call(format_prompt) return final_response # 重构后可测试的代码 class TestableWeatherAgent: def __init__(self, llm_provider, weather_tool): # llm_provider 是一个抽象接口 self.llm llm_provider self.tool weather_tool def process_step(self, step_input: dict) - dict: 核心的、确定性的处理逻辑。 step_input: 包含当前状态、用户输入、上一步的LLM响应等。 返回: 一个动作字典如 {action: call_llm, prompt: ...} 或 {action: call_tool, tool_name: weather, params: {...}} if step_input[step] extract_city: # 决定要调用LLM来提取城市 return { action: call_llm, prompt: f从以下用户输入中提取城市名{step_input[user_input]}, next_step: query_weather # 指定LLM响应后的下一步 } elif step_input[step] query_weather and step_input.get(llm_response): # 上一步LLM返回了城市名现在调用工具 city step_input[llm_response] return { action: call_tool, tool_name: weather, params: {city: city}, next_step: format_response } elif step_input[step] format_response and step_input.get(tool_result): # 工具返回了天气数据现在调用LLM格式化 weather_data step_input[tool_result] return { action: call_llm, prompt: f将天气数据{weather_data}组织成友好的回复。, next_step: final } elif step_input[step] final and step_input.get(llm_response): # 得到最终LLM回复流程结束 return {action: finish, response: step_input[llm_response]} else: return {action: error, reason: Invalid state} # 一个外部的“驱动器”来协调这个Agent def run_agent_driver(agent, user_input, mock_llm_responses): state {step: extract_city, user_input: user_input} llm_response_index 0 while True: action agent.process_step(state) if action[action] call_llm: # 在这里我们使用Mock响应而不是真实LLM mock_response mock_llm_responses[llm_response_index] llm_response_index 1 state[llm_response] mock_response state[step] action[next_step] elif action[action] call_tool: # 这里也可以Mock工具调用或者使用一个轻量级的测试工具 tool_result agent.tool.query(**action[params]) state[tool_result] tool_result state[step] action[next_step] elif action[action] finish: return action[response] elif action[action] error: raise Exception(fAgent error: {action[reason]})通过这样的重构process_step方法包含了所有决定“下一步做什么”的确定性逻辑。LLM调用被抽象成一个外部依赖llm_provider在测试中我们可以轻易地注入一个Mock实现。步骤二创建LLM Mock服务创建一个简单的Mock类它根据某种规则返回预定义的响应。class DeterministicLLMMock: def __init__(self, response_map): response_map: dict, 键可以是prompt的哈希或者包含prompt和step的元组。 self.response_map response_map self.call_history [] # 记录调用历史用于断言 def call(self, prompt: str, step_contextNone) - str: self.call_history.append({prompt: prompt, context: step_context}) # 生成一个简单的键实际项目中可能需要更复杂的匹配逻辑 key hash(prompt[:100]) # 示例取prompt前100字符的哈希 if key in self.response_map: return self.response_map[key] else: # 如果未找到匹配可以返回一个默认错误这有助于发现未覆盖的测试场景 raise ValueError(fNo mock response defined for prompt: {prompt[:50]}...) # 准备测试数据 mock_responses { hash(从以下用户输入中提取城市名北京天气怎么样): 北京, hash(将天气数据{temp: 22, condition: 晴}组织成友好的回复。): 北京今天天气晴朗气温22摄氏度非常舒适。 }步骤三编写层间隔离测试用例使用pytest编写测试验证骨架逻辑。import pytest def test_weather_agent_happy_path(): # 1. 准备Mock数据 mock_llm DeterministicLLMMock(mock_responses) # 使用一个简单的、可预测的天气工具Mock mock_tool MockWeatherTool(return_value{temp: 22, condition: 晴}) # 2. 实例化被测试的Agent骨架 agent TestableWeatherAgent(llm_providermock_llm, weather_toolmock_tool) # 3. 运行驱动器 final_response run_agent_driver( agent, user_input北京天气怎么样, mock_llm_responses[北京, 北京今天天气晴朗气温22摄氏度非常舒适。] # 驱动器直接使用这个列表 ) # 4. 断言最终结果 assert 北京 in final_response assert 22 in final_response assert 晴朗 in final_response # 5. 更重要的断言行为过程 # 检查LLM Mock被调用了两次且第二次调用的prompt包含天气数据 assert len(mock_llm.call_history) 2 assert 天气数据 in mock_llm.call_history[1][prompt] # 检查工具被调用了一次且参数正确 assert mock_tool.call_count 1 assert mock_tool.last_called_with {city: 北京}这个测试用例完全不依赖真实LLM运行速度极快且结果100%可重复。它锁定了Agent在接收到“北京”和特定格式化指令后应该调用天气查询工具并最终生成包含特定关键词的回复这一系列行为。注意事项Mock响应的设计是关键。它们应该模拟LLM在理想情况下“正确”的响应但也要考虑一些边界情况比如LLM提取城市失败返回空或无法识别、返回了非预期格式等。这些“负面”测试用例对于验证Agent的鲁棒性同样重要。4. 集成到CI/CD流水线4.1 在GitLab CI中的配置示例将这套测试集成到CI中能确保每次合并请求Merge Request都不会引入回归错误。以下是一个简化的.gitlab-ci.yml配置示例stages: - test layer-isolated-test: stage: test image: python:3.11-slim # 使用包含测试环境的镜像 before_script: - pip install -r requirements.txt -r requirements-test.txt # 安装项目依赖和测试依赖 script: - pytest tests/layer_isolated/ -v --tbshort # 专门运行层间隔离测试 rules: - if: $CI_PIPELINE_SOURCE merge_request_event # 在MR时触发 - if: $CI_COMMIT_BRANCH main # 在推送到主分支时也触发4.2 测试数据的管理与版本控制“回归锁定”要求测试数据Mock响应本身是稳定的。这些数据文件应该被纳入版本控制。your_agent_project/ ├── src/ │ └── agent.py ├── tests/ │ ├── layer_isolated/ │ │ ├── conftest.py # 公共测试配置和fixture │ │ ├── test_weather_agent.py │ │ └── fixtures/ # 存放测试数据 │ │ ├── weather_agent/ │ │ │ ├── happy_path_responses.json │ │ │ ├── edge_case_no_city.json │ │ │ └── ... │ ├── e2e/ # 端到端测试另作他用 │ └── ... ├── .gitlab-ci.yml └── ...当Agent的提示词或逻辑发生变更导致原有的Mock响应不再匹配时测试会失败。这时你需要有意识地去更新测试数据。这个过程应该是手动的、经过评审的而不是自动更新。因为这迫使开发者思考这次变更是否合理新的预期行为是什么这本身就是一次对变更影响的小范围评审。5. 常见问题与排查技巧实录在实际搭建和运行这套框架时你肯定会遇到一些典型问题。下面是我踩过的一些坑和解决办法。5.1 Mock响应匹配失败问题测试运行时提示ValueError: No mock response defined for prompt: ...。排查检查Prompt是否发生变更这是最常见的原因。你是否修改了Agent中构造提示词的代码即使是微小的改动比如增加了一个换行符也会导致哈希值或字符串匹配失败。检查Mock匹配逻辑你的Mock服务是精确匹配整个prompt字符串还是匹配部分如果是精确匹配prompt中的变量部分如用户输入会导致每次测试的prompt都不同。解决方案是使用更灵活的匹配方式例如提取关键部分只匹配prompt中固定不变的指令部分。使用正则表达式if re.search(r从以下用户输入中提取城市名.*, prompt):。基于步骤上下文匹配在Mock的call方法中除了prompt也传入当前的step信息用(step, prompt_template)作为键。检查测试数据是否被正确加载确保测试数据文件的路径正确并且在测试设置如pytest的fixture中被正确读取并传递给Mock。实操心得不要追求对LLM Prompt的100%精确Mock。我们的目标是测试骨架逻辑而不是Prompt本身。因此Mock匹配可以“宽松”一些只要它能正确识别出Agent在当前步骤“意图做什么”即可。例如对于提取城市的Prompt只要Mock能识别出这是“提取城市”的意图并返回一个预设的城市名就行无需关心Prompt的具体措辞。5.2 测试变得脆弱Flaky Tests问题即使使用了Mock测试有时过有时不过。排查检查工具Mock的副作用如果你的工具Mock比如模拟数据库查询返回了非确定性的数据例如包含当前时间戳就会导致测试不稳定。确保所有Mock返回的数据都是完全确定的。检查Agent的状态残留确保每个测试用例都是独立的。在setup或teardown阶段重置Agent的所有内部状态。避免测试用例间的状态污染。检查并发问题如果你的测试框架或Agent本身涉及异步或多线程在测试环境中需要格外小心。尽量在隔离测试中避免并发或者使用确定性的并发原语进行Mock。5.3 测试覆盖度不足问题层间隔离测试都通过了但端到端测试还是失败了。排查审查Mock数据的完备性你的Mock数据是否只覆盖了“阳光大道”happy path是否考虑了LLM返回格式错误、返回无关信息、拒绝回答等边缘情况补充这些负面测试用例。检查被隔离的“层”是否完整你是否把所有应该确定性的逻辑都剥离到了可测试的骨架中有些逻辑可能无意中依赖了LLM输出的微妙格式。确保骨架的逻辑判断是基于清晰、结构化的数据比如JSON而不是基于对自然语言的字符串解析。验证集成点层间隔离测试不覆盖Agent与真实LLM、真实工具的集成。你需要有另外的集成测试来验证你构造的Prompt是否能被真实LLM正确理解你解析LLM响应的代码是否能处理真实模型输出的各种变体这些测试不需要在CI中高频运行但必须在发布前执行。5.4 测试维护成本上升问题随着Agent功能越来越复杂测试用例和Mock数据越来越多维护起来很麻烦。排查与优化建立测试数据生成器不要手动编写大量的JSON Mock文件。可以编写一些辅助函数根据测试场景如“成功查询天气”、“城市提取失败”动态生成标准的Mock响应。使用契约测试Contract Test思想为你的Agent骨架与LLM Mock之间定义一个“契约”。这个契约规定了对于给定的输入状态步骤、上下文骨架会请求一个什么样“意图”的LLM调用例如“意图提取城市”而Mock则承诺对于某个“意图”它会返回何种格式的数据。这样测试用例可以基于“意图”来编写而不是基于具体的Prompt字符串降低了与Prompt具体文本的耦合度。分层组织测试用例按功能模块组织测试目录。对于复杂的多轮对话Agent可以按对话场景或用户目标来组织测试套件。6. 进阶扩展测试工具链的能力基础框架搭建好后可以考虑以下扩展以提升测试的效能和洞察力。6.1 自动化生成“黄金标准”测试数据一开始的Mock响应数据可能需要手动创建。但你可以利用历史线上日志或成功的端到端测试记录来半自动地生成这些数据。从日志中提取一次成功的用户会话。提取其中Agent对LLM的真实请求和LLM的真实响应。经过人工审核后将这些(request, response)对转化为测试用的Mock数据。 这样就能快速积累覆盖真实场景的测试用例。6.2 性能与压力测试既然测试成本极低你就可以轻松地对Agent的骨架逻辑进行性能测试。例如模拟高并发下的请求检查是否有状态竞争、内存泄漏或逻辑错误。虽然不涉及真实LLM但可以暴露出流程引擎本身的性能瓶颈。6.3 可视化测试报告与差异对比在CI流水线中当测试失败时除了输出日志还可以生成更友好的报告。例如对比“期望的Agent行为”和“实际的Agent行为”用高亮显示差异所在是调用的工具不对还是参数值错了。这能极大提升排查效率。实施“Layer-Isolated Evaluation”这套方法最直接的体会是心理负担小了很多。以前改几行提示词都要提心吊胆现在只要隔离测试套件全绿我就有九成把握这次变更不会搞垮核心流程。它把LLM Agent开发中“确定”与“不确定”的部分划清了界限让工程师能在一个稳固的基础上去放心地探索和优化那些真正需要创造力和不确定性的部分。这套模式本质上是一种关注点分离它让Agent的测试变得像测试一个普通的、有状态的业务服务一样清晰和可控。 构建LLM Agent确定性测试框架：层间隔离与回归锁定实践
1. 项目概述为生产级LLM Agent构建确定性测试框架最近在折腾一个生产环境里的LLM Agent项目踩了不少坑。最头疼的问题莫过于每次更新Agent的提示词、逻辑流甚至只是换个底层大模型心里都没底。线上服务会不会崩回答质量会不会断崖式下跌传统的端到端测试要么成本太高每次都要调用昂贵的LLM API要么太“黑盒”出了问题根本不知道是哪个环节的锅。这让我开始思考能不能像测试传统软件一样给LLM Agent也搞一套稳定、高效、低成本的自动化测试方案于是就有了“Layer-Isolated Evaluation”层间隔离评估这个想法。简单来说这个项目的核心目标就是为复杂的生产级LLM Agent系统搭建一个“不用LLM”的、回归锁定的测试工具链。它不是一个简单的问答对匹配器而是一个工程框架旨在将Agent内部那些本应确定性的逻辑比如流程控制、工具调用、数据解析与不确定的LLM生成过程剥离开单独进行严格的、可重复的测试。这样一来我们就能在持续集成CI流水线里快速、廉价地验证Agent“骨架”的健壮性确保核心逻辑的每一次变更都是安全的把不确定性和成本留给真正需要LLM创造力的环节去处理。这适合谁呢如果你正在开发或维护一个涉及多步骤推理、工具调用、复杂流程的LLM Agent比如客服机器人、数据分析助手、自动化工作流引擎并且受困于测试的不可靠和高成本那么这个思路会给你带来直接的工程价值。它尤其适合那些已经将Agent投入生产需要进行频繁迭代和持续交付的团队。2. 核心设计思路隔离、锁定与确定性验证2.1 为什么需要“层间隔离”一个典型的LLM Agent架构可以粗略分为几个层次应用/流程层定义任务目标、拆解步骤、协调工具调用。这部分通常是基于代码或配置的确定性逻辑。编排/决策层根据当前状态和上下文决定下一步是调用工具还是请求LLM。这部分逻辑也应该是相对确定的。LLM交互层向大模型发送精心构造的提示词Prompt并解析其返回的非结构化文本。这是不确定性的主要来源。工具执行层执行具体的API调用、数据库查询、代码运行等。这部分的外部依赖可能引入不确定性。传统的端到端测试把所有这些层“一锅炖”用最终输出LLM生成的自然语言来评判整个系统。这带来了几个致命问题成本高昂每次测试都要调用LLM API无论是金钱还是时间成本都难以承受高频的CI/CD。结果不稳定LLM的输出具有随机性即使温度设为0不同版本模型也可能给出不同回答导致测试用例时而过时而过不了毫无可靠性可言。问题定位困难测试失败时你无法快速判断是提示词没写好、流程逻辑有bug还是工具API挂了。“层间隔离”的思路就是将第1、2层确定性骨架与第3层非确定性LLM进行解耦。我们为Agent的骨架搭建一个模拟环境在这个环境里LLM的响应被一个Mock服务所替代。这个Mock服务不调用真实LLM而是根据预先定义好的规则返回固定的、结构化的数据。这样我们就可以用极低的成本成千上万次地运行测试专门验证骨架逻辑的正确性。2.2 “回归锁定”测试工具链的精髓“Regression-Locked Test Harness”是这个框架的另一个核心。它不仅仅是做功能测试更是做回归测试并且是“锁定”的。回归测试确保新的代码变更不会破坏已有的、正常的功能。对于Agent来说就是确保对提示词、流程逻辑的修改不会导致之前能正确处理的任务现在出问题。“锁定”这里的“锁定”有两层含义。锁定LLM的输出通过Mock将LLM的不确定性输出“锁定”为确定性的测试数据。这些测试数据即Mock的响应本身需要被版本化管理作为测试基准。锁定核心行为测试用例所验证的不是LLM说了什么漂亮话而是Agent在接收到特定模拟的LLM响应后是否做出了正确的行为。例如是否调用了正确的工具调用时的参数是否正确流程状态是否按预期转换这个测试工具链会集成到你的CI/CD流程中。每次代码提交或合并请求都会自动触发这套测试。如果骨架逻辑的变更导致了与“锁定”的预期行为不符测试就会失败阻止有问题的代码进入生产环境。2.3 与非隔离测试的对比为了更直观地理解我们可以看一个对比表格测试类型测试对象LLM调用成本稳定性定位问题主要用途端到端测试整个Agent系统真实LLM API极高低受模型波动影响困难需层层排查验收测试、关键场景冒烟测试层间隔离测试Agent的确定性骨架流程、工具调用逻辑Mock服务无LLM极低高完全可控容易直接定位到逻辑层回归测试、CI/CD、快速迭代实操心得不要指望用层间隔离测试完全替代端到端测试。它俩是互补关系。隔离测试用于保障“骨架”的健壮性支持高频迭代而端到端测试则用于在发布前对集成后的完整系统进行最终验证尤其是检验LLM在真实提示词下的创造力是否符合预期。前者求“稳”后者求“全”。3. 构建No-LLM测试工具链的实操要点3.1 工具链的核心组件构建这样一个测试工具链你需要以下几个核心组件测试运行器可以是pytest,JUnit, 或任何你熟悉的测试框架。它负责组织、运行测试用例并报告结果。Agent骨架的测试接口你需要为你Agent的核心逻辑即剥离了真实LLM调用的部分暴露出一个可测试的接口。这通常是一个函数或类方法它接收“用户输入”和“模拟的LLM历史/响应”然后执行内部逻辑最终返回“下一步动作”如调用某个工具或“最终输出”。LLM Mock服务这是关键。你需要一个服务它能拦截Agent试图调用LLM API的请求并根据请求中的提示词Prompt或其他标识返回预先准备好的响应。这个Mock可以很简单比如一个内存中的字典映射{prompt_signature: mock_response}也可以很复杂支持基于正则表达式匹配或请求内容的部分匹配。测试数据管理用于存储和管理那些“锁定”的Mock响应和预期的Agent行为。这些数据应该被当作代码一样进行版本控制例如存放在tests/fixtures/目录下。断言库用于验证Agent的实际行为是否符合预期。不仅仅是比较字符串更要能断言“是否调用了工具A”、“调用工具B时的参数是否包含某个值”、“状态机是否从S1转移到了S2”。3.2 实施步骤详解假设我们有一个简单的“天气查询Agent”它的逻辑是1) 让LLM从用户输入中提取城市名2) 调用天气查询工具3) 让LLM格式化结果并回复。步骤一重构Agent代码使其可测试首先要将LLM调用部分抽象出来使其易于被Mock替换。# 原始不可测试的代码片段混合在一起 class WeatherAgent: def __init__(self, llm_client, weather_tool): self.llm llm_client self.tool weather_tool def run(self, user_input: str) - str: # 步骤1: 调用LLM提取城市 extraction_prompt f从以下用户输入中提取城市名{user_input} city self.llm.call(extraction_prompt) # 直接调用难以Mock # 步骤2: 调用工具 weather_data self.tool.query(city) # 步骤3: 调用LLM格式化 format_prompt f将天气数据{weather_data}组织成友好的回复。 final_response self.llm.call(format_prompt) return final_response # 重构后可测试的代码 class TestableWeatherAgent: def __init__(self, llm_provider, weather_tool): # llm_provider 是一个抽象接口 self.llm llm_provider self.tool weather_tool def process_step(self, step_input: dict) - dict: 核心的、确定性的处理逻辑。 step_input: 包含当前状态、用户输入、上一步的LLM响应等。 返回: 一个动作字典如 {action: call_llm, prompt: ...} 或 {action: call_tool, tool_name: weather, params: {...}} if step_input[step] extract_city: # 决定要调用LLM来提取城市 return { action: call_llm, prompt: f从以下用户输入中提取城市名{step_input[user_input]}, next_step: query_weather # 指定LLM响应后的下一步 } elif step_input[step] query_weather and step_input.get(llm_response): # 上一步LLM返回了城市名现在调用工具 city step_input[llm_response] return { action: call_tool, tool_name: weather, params: {city: city}, next_step: format_response } elif step_input[step] format_response and step_input.get(tool_result): # 工具返回了天气数据现在调用LLM格式化 weather_data step_input[tool_result] return { action: call_llm, prompt: f将天气数据{weather_data}组织成友好的回复。, next_step: final } elif step_input[step] final and step_input.get(llm_response): # 得到最终LLM回复流程结束 return {action: finish, response: step_input[llm_response]} else: return {action: error, reason: Invalid state} # 一个外部的“驱动器”来协调这个Agent def run_agent_driver(agent, user_input, mock_llm_responses): state {step: extract_city, user_input: user_input} llm_response_index 0 while True: action agent.process_step(state) if action[action] call_llm: # 在这里我们使用Mock响应而不是真实LLM mock_response mock_llm_responses[llm_response_index] llm_response_index 1 state[llm_response] mock_response state[step] action[next_step] elif action[action] call_tool: # 这里也可以Mock工具调用或者使用一个轻量级的测试工具 tool_result agent.tool.query(**action[params]) state[tool_result] tool_result state[step] action[next_step] elif action[action] finish: return action[response] elif action[action] error: raise Exception(fAgent error: {action[reason]})通过这样的重构process_step方法包含了所有决定“下一步做什么”的确定性逻辑。LLM调用被抽象成一个外部依赖llm_provider在测试中我们可以轻易地注入一个Mock实现。步骤二创建LLM Mock服务创建一个简单的Mock类它根据某种规则返回预定义的响应。class DeterministicLLMMock: def __init__(self, response_map): response_map: dict, 键可以是prompt的哈希或者包含prompt和step的元组。 self.response_map response_map self.call_history [] # 记录调用历史用于断言 def call(self, prompt: str, step_contextNone) - str: self.call_history.append({prompt: prompt, context: step_context}) # 生成一个简单的键实际项目中可能需要更复杂的匹配逻辑 key hash(prompt[:100]) # 示例取prompt前100字符的哈希 if key in self.response_map: return self.response_map[key] else: # 如果未找到匹配可以返回一个默认错误这有助于发现未覆盖的测试场景 raise ValueError(fNo mock response defined for prompt: {prompt[:50]}...) # 准备测试数据 mock_responses { hash(从以下用户输入中提取城市名北京天气怎么样): 北京, hash(将天气数据{temp: 22, condition: 晴}组织成友好的回复。): 北京今天天气晴朗气温22摄氏度非常舒适。 }步骤三编写层间隔离测试用例使用pytest编写测试验证骨架逻辑。import pytest def test_weather_agent_happy_path(): # 1. 准备Mock数据 mock_llm DeterministicLLMMock(mock_responses) # 使用一个简单的、可预测的天气工具Mock mock_tool MockWeatherTool(return_value{temp: 22, condition: 晴}) # 2. 实例化被测试的Agent骨架 agent TestableWeatherAgent(llm_providermock_llm, weather_toolmock_tool) # 3. 运行驱动器 final_response run_agent_driver( agent, user_input北京天气怎么样, mock_llm_responses[北京, 北京今天天气晴朗气温22摄氏度非常舒适。] # 驱动器直接使用这个列表 ) # 4. 断言最终结果 assert 北京 in final_response assert 22 in final_response assert 晴朗 in final_response # 5. 更重要的断言行为过程 # 检查LLM Mock被调用了两次且第二次调用的prompt包含天气数据 assert len(mock_llm.call_history) 2 assert 天气数据 in mock_llm.call_history[1][prompt] # 检查工具被调用了一次且参数正确 assert mock_tool.call_count 1 assert mock_tool.last_called_with {city: 北京}这个测试用例完全不依赖真实LLM运行速度极快且结果100%可重复。它锁定了Agent在接收到“北京”和特定格式化指令后应该调用天气查询工具并最终生成包含特定关键词的回复这一系列行为。注意事项Mock响应的设计是关键。它们应该模拟LLM在理想情况下“正确”的响应但也要考虑一些边界情况比如LLM提取城市失败返回空或无法识别、返回了非预期格式等。这些“负面”测试用例对于验证Agent的鲁棒性同样重要。4. 集成到CI/CD流水线4.1 在GitLab CI中的配置示例将这套测试集成到CI中能确保每次合并请求Merge Request都不会引入回归错误。以下是一个简化的.gitlab-ci.yml配置示例stages: - test layer-isolated-test: stage: test image: python:3.11-slim # 使用包含测试环境的镜像 before_script: - pip install -r requirements.txt -r requirements-test.txt # 安装项目依赖和测试依赖 script: - pytest tests/layer_isolated/ -v --tbshort # 专门运行层间隔离测试 rules: - if: $CI_PIPELINE_SOURCE merge_request_event # 在MR时触发 - if: $CI_COMMIT_BRANCH main # 在推送到主分支时也触发4.2 测试数据的管理与版本控制“回归锁定”要求测试数据Mock响应本身是稳定的。这些数据文件应该被纳入版本控制。your_agent_project/ ├── src/ │ └── agent.py ├── tests/ │ ├── layer_isolated/ │ │ ├── conftest.py # 公共测试配置和fixture │ │ ├── test_weather_agent.py │ │ └── fixtures/ # 存放测试数据 │ │ ├── weather_agent/ │ │ │ ├── happy_path_responses.json │ │ │ ├── edge_case_no_city.json │ │ │ └── ... │ ├── e2e/ # 端到端测试另作他用 │ └── ... ├── .gitlab-ci.yml └── ...当Agent的提示词或逻辑发生变更导致原有的Mock响应不再匹配时测试会失败。这时你需要有意识地去更新测试数据。这个过程应该是手动的、经过评审的而不是自动更新。因为这迫使开发者思考这次变更是否合理新的预期行为是什么这本身就是一次对变更影响的小范围评审。5. 常见问题与排查技巧实录在实际搭建和运行这套框架时你肯定会遇到一些典型问题。下面是我踩过的一些坑和解决办法。5.1 Mock响应匹配失败问题测试运行时提示ValueError: No mock response defined for prompt: ...。排查检查Prompt是否发生变更这是最常见的原因。你是否修改了Agent中构造提示词的代码即使是微小的改动比如增加了一个换行符也会导致哈希值或字符串匹配失败。检查Mock匹配逻辑你的Mock服务是精确匹配整个prompt字符串还是匹配部分如果是精确匹配prompt中的变量部分如用户输入会导致每次测试的prompt都不同。解决方案是使用更灵活的匹配方式例如提取关键部分只匹配prompt中固定不变的指令部分。使用正则表达式if re.search(r从以下用户输入中提取城市名.*, prompt):。基于步骤上下文匹配在Mock的call方法中除了prompt也传入当前的step信息用(step, prompt_template)作为键。检查测试数据是否被正确加载确保测试数据文件的路径正确并且在测试设置如pytest的fixture中被正确读取并传递给Mock。实操心得不要追求对LLM Prompt的100%精确Mock。我们的目标是测试骨架逻辑而不是Prompt本身。因此Mock匹配可以“宽松”一些只要它能正确识别出Agent在当前步骤“意图做什么”即可。例如对于提取城市的Prompt只要Mock能识别出这是“提取城市”的意图并返回一个预设的城市名就行无需关心Prompt的具体措辞。5.2 测试变得脆弱Flaky Tests问题即使使用了Mock测试有时过有时不过。排查检查工具Mock的副作用如果你的工具Mock比如模拟数据库查询返回了非确定性的数据例如包含当前时间戳就会导致测试不稳定。确保所有Mock返回的数据都是完全确定的。检查Agent的状态残留确保每个测试用例都是独立的。在setup或teardown阶段重置Agent的所有内部状态。避免测试用例间的状态污染。检查并发问题如果你的测试框架或Agent本身涉及异步或多线程在测试环境中需要格外小心。尽量在隔离测试中避免并发或者使用确定性的并发原语进行Mock。5.3 测试覆盖度不足问题层间隔离测试都通过了但端到端测试还是失败了。排查审查Mock数据的完备性你的Mock数据是否只覆盖了“阳光大道”happy path是否考虑了LLM返回格式错误、返回无关信息、拒绝回答等边缘情况补充这些负面测试用例。检查被隔离的“层”是否完整你是否把所有应该确定性的逻辑都剥离到了可测试的骨架中有些逻辑可能无意中依赖了LLM输出的微妙格式。确保骨架的逻辑判断是基于清晰、结构化的数据比如JSON而不是基于对自然语言的字符串解析。验证集成点层间隔离测试不覆盖Agent与真实LLM、真实工具的集成。你需要有另外的集成测试来验证你构造的Prompt是否能被真实LLM正确理解你解析LLM响应的代码是否能处理真实模型输出的各种变体这些测试不需要在CI中高频运行但必须在发布前执行。5.4 测试维护成本上升问题随着Agent功能越来越复杂测试用例和Mock数据越来越多维护起来很麻烦。排查与优化建立测试数据生成器不要手动编写大量的JSON Mock文件。可以编写一些辅助函数根据测试场景如“成功查询天气”、“城市提取失败”动态生成标准的Mock响应。使用契约测试Contract Test思想为你的Agent骨架与LLM Mock之间定义一个“契约”。这个契约规定了对于给定的输入状态步骤、上下文骨架会请求一个什么样“意图”的LLM调用例如“意图提取城市”而Mock则承诺对于某个“意图”它会返回何种格式的数据。这样测试用例可以基于“意图”来编写而不是基于具体的Prompt字符串降低了与Prompt具体文本的耦合度。分层组织测试用例按功能模块组织测试目录。对于复杂的多轮对话Agent可以按对话场景或用户目标来组织测试套件。6. 进阶扩展测试工具链的能力基础框架搭建好后可以考虑以下扩展以提升测试的效能和洞察力。6.1 自动化生成“黄金标准”测试数据一开始的Mock响应数据可能需要手动创建。但你可以利用历史线上日志或成功的端到端测试记录来半自动地生成这些数据。从日志中提取一次成功的用户会话。提取其中Agent对LLM的真实请求和LLM的真实响应。经过人工审核后将这些(request, response)对转化为测试用的Mock数据。 这样就能快速积累覆盖真实场景的测试用例。6.2 性能与压力测试既然测试成本极低你就可以轻松地对Agent的骨架逻辑进行性能测试。例如模拟高并发下的请求检查是否有状态竞争、内存泄漏或逻辑错误。虽然不涉及真实LLM但可以暴露出流程引擎本身的性能瓶颈。6.3 可视化测试报告与差异对比在CI流水线中当测试失败时除了输出日志还可以生成更友好的报告。例如对比“期望的Agent行为”和“实际的Agent行为”用高亮显示差异所在是调用的工具不对还是参数值错了。这能极大提升排查效率。实施“Layer-Isolated Evaluation”这套方法最直接的体会是心理负担小了很多。以前改几行提示词都要提心吊胆现在只要隔离测试套件全绿我就有九成把握这次变更不会搞垮核心流程。它把LLM Agent开发中“确定”与“不确定”的部分划清了界限让工程师能在一个稳固的基础上去放心地探索和优化那些真正需要创造力和不确定性的部分。这套模式本质上是一种关注点分离它让Agent的测试变得像测试一个普通的、有状态的业务服务一样清晰和可控。