最近在帮团队搭建 Agent 测试体系的时候发现一个很典型的断档大家写 Skill 写得很起劲但问到你的 Skill 怎么验证基本只有两种回答——要么拿个例子跑一下看着差不多就行要么还没想好先上线再说。这个问题的严重性被严重低估了。Agent 应用和传统后端应用有一个本质区别输出具有不确定性。同一个 Skill今天跑能出结果明天换一种调用路径就可能崩。Skill 单测能过、一进 Agent 就废的情况几乎每个做 Agent 开发的团队都遇到过。这篇文章不讲什么是 Skill这种入门内容直接拆解三套可落地的测试方案方案一Pytest 单元测试把 Skill 从 Agent 中隔离出来Mock 掉外部依赖快速验证内部逻辑方案二Agent 运行时集成测试把 Skill 注册进真实 Agent 环境验证编排、意图识别、参数抽取和结果回传方案三LVM LLM 多模态联合测试针对需要视觉理解再加语言推理的 Skill做两阶段联合验证。文章里所有代码都是可以直接复制去改的不是伪代码。读完后你至少能搭出一套最小可用的 Skill 测试体系并且知道这三种方案各自该在什么阶段用、有什么坑。1. 为什么 Skill 测试突然成了硬需求先明确一个判断Skill 测试不是锦上添花而是 Agent 应用能不能稳定交付的分水岭。过去一年多Agent 开发框架经历了从能跑通对话到能执行复杂任务的转变。所谓 Skill就是在这个转变中诞生的能力封装机制。一个 Skill 通常包含触发条件、输入输出协议、执行步骤以及可能的外部依赖工具调用、提示词模板、上下文处理逻辑。听起来很清晰但实际开发中问题出现在三个地方。第一Skill 是独立写的却是在 Agent 里跑的。写 Skill 时你面对的是干净的函数签名和明确的输入输出跑起来之后它面对的是用户模糊的指令、Agent 规划出的子任务、多轮对话积累的上下文。这些环境差异单元测试不太容易覆盖到。第二LLM 的不可确定性让测试结果不可信。同一个请求温度参数稍微调一下输出的 JSON 结构就可能变化。如果测试断言写得过死每次跑都红如果断言写得过松又失去了测试意义。第三多模态场景把测试复杂度拉高了。当 Skill 需要先通过视觉大模型LVM理解图片再交给语言大模型LLM做判断时测试数据的构造、两阶段之间的接口约定、失败时的降级策略每一层都可能出问题。所以你会发现单一测试方案根本不够用。必须分层底层用 Pytest 把能确定的逻辑锁死中间层用 Agent 运行时验证编排最上层用 LVM LLM 联合测试覆盖多模态场景。这是本文的核心思路。2. 先把概念对齐Skill、Agent、LLM、LVM 到底指什么为了避免后面代码示例产生歧义先花两分钟把概念边界说清楚。2.1 SkillAgent 的能力模块Skill 是 Agent 框架里的一个能力封装单元。它不是一个函数那么简单而是触发条件 处理流程 输出协议的组合。一个 Skill 应该回答四个问题什么任务归我管我需要的输入是什么样我怎么做这件事我返回的结果是什么结构从测试角度看这意味着 Skill 必须具备清晰的接口边界。如果写 Skill 的时候连输入输出协议都没定义清楚那测试无从谈起。2.2 Agent调度编排层Agent 是接收任务、规划步骤、调度 Skill、汇总结果的执行主体。它不负责具体的业务能力负责的是怎么做决策。Agent 和 Skill 的关系可以类比为项目经理和工程师项目经理派活工程师干活。测试时Agent 层最需要关注的是派活派得对不对Skill 层最需要关注的是活干得好不好。2.3 LLM语言推理核心LLM大语言模型负责自然语言的理解、推理和生成。在 Skill 链路里LLM 通常承担意图识别、参数抽取、结果生成、决策判断等任务。2.4 LVM视觉理解模型这里要特别说明本文语境下的 LVM 是 Large Vision Model即视觉理解大模型不是 Linux 里的逻辑卷管理。很多文章把这两者混在一起搜资料时容易绕晕。LVM 负责处理图像、截图、表单、证件等视觉输入输出结构化描述或字段信息。在 Skill 链路里LVM 通常处于前置阶段先看懂图片再把结构化结果交给 LLM 做业务判断。2.5 四者关系速览概念职责测试关注点Skill封装某一类任务能力输入输出协议、内部逻辑、边界条件Agent理解任务、调度 Skill、汇总结果意图识别、Skill 选择、参数传递LLM语言推理与生成输出格式、稳定性、幻觉风险LVM视觉内容理解字段提取准确率、异常输入、超时降级3. 方案一Pytest 单元测试——把 Skill 隔离出来锁死内部逻辑3.1 为什么先选 PytestPytest 是 Python 生态最主流的测试框架对 Agent 类项目来说有三个不可替代的优势天然的 fixture 机制适合构造 Skill 测试所需的上下文环境支持 asyncioAgent 项目几乎全是异步代码配合 pytest-mock 可以非常方便地 Mock 掉 LLM、HTTP、数据库等外部依赖。单元测试的核心原则是把所有外部依赖全部 Mock 掉只测 Skill 自身的逻辑分支。这一步不是为了测 LLM 好不好用而是为了保证在外部依赖都正常的前提下我的 Skill 代码逻辑是正确的。3.2 环境准备pip install pytest pytest-asyncio pytest-mock如果项目使用 Poetry 或 uv把这三个包加到 dev 依赖组即可。版本以你项目实际情况为准本文重点演示思路。3.3 目录结构一个典型的项目结构长这样agent_project/ ├── agent/ │ ├── __init__.py │ └── core.py ├── skills/ │ ├── __init__.py │ └── order_skill.py └── tests/ ├── conftest.py └── test_order_skill.py3.4 被测 Skill 示例先写一个简单的订单查询 Skill方便测试演示# skills/order_skill.py from dataclasses import dataclass, field dataclass class OrderSkill: 订单查询 Skill从用户意图中抽取订单号然后查询订单状态。 llm_client: object order_api: object def parse_intent(self, user_input: str) - dict: 调用 LLM 抽取用户意图和订单号。 prompt f从以下用户输入中抽取意图和订单号返回 JSON{user_input} response self.llm_client.chat(prompt) # 假设响应是合法 JSON这里做简化处理 return response def execute(self, user_input: str) - dict: intent self.parse_intent(user_input) order_no intent.get(order_no) if not order_no: return {status: error, message: 未识别到订单号} order_info self.order_api.query(order_no) return {status: success, data: order_info}这个 Skill 的逻辑是先用 LLM 解析用户输入拿到订单号再调用订单 API 查询。它依赖两个外部对象llm_client 和 order_api。3.5 编写单元测试# tests/conftest.py import pytest from unittest.mock import Mock from skills.order_skill import OrderSkill pytest.fixture def mock_llm(): Mock LLM 客户端返回固定的意图解析结果。 llm Mock() def fake_chat(prompt): if 帮我查一下昨天下的订单 in prompt: return {intent: query_order, order_no: 2024001} if 取消订单 in prompt: return {intent: cancel_order, order_no: 2024002} return {intent: unknown, order_no: None} llm.chat.side_effect fake_chat return llm pytest.fixture def mock_order_api(): Mock 订单 API返回固定订单状态。 api Mock() api.query.return_value {order_no: 2024001, status: 已发货} return api pytest.fixture def order_skill(mock_llm, mock_order_api): return OrderSkill(llm_clientmock_llm, order_apimock_order_api)# tests/test_order_skill.py def test_parse_intent_success(order_skill): result order_skill.parse_intent(帮我查一下昨天下的订单) assert result[intent] query_order assert result[order_no] 2024001 def test_parse_intent_unknown(order_skill): result order_skill.parse_intent(今天天气怎么样) assert result[intent] unknown assert result[order_no] is None def test_execute_missing_order_no(order_skill, mock_llm): # 构造模拟LLM 返回没有订单号 mock_llm.chat.return_value {intent: query_order, order_no: None} result order_skill.execute(帮我查一下订单) assert result[status] error assert 未识别到订单号 in result[message] def test_execute_api_query_called(order_skill, mock_order_api): result order_skill.execute(帮我查一下昨天下的订单) mock_order_api.query.assert_called_once_with(2024001) assert result[status] success assert result[data][status] 已发货3.6 关键设计说明上面这段代码里最值得关注的是mock_llm的side_effect写法。它模拟了一个真实的 LLM 行为不同的输入返回不同的结果。这比简单的return_value更接近实际情况能覆盖更多分支。单元测试阶段要注意一个容易被忽视的问题Mock 的返回结果一定要遵循你和 LLM 约定的输出格式。很多项目在这里翻车——Mock 里返回的是完美 JSON真实 LLM 返回的是带前后缀文本的 JSON导致测试全绿、上线全红。后面第 7 节会专门讲这个问题。3.7 运行与验证cd agent_project pytest tests/test_order_skill.py -v预期输出中会出现四个测试通过的结果。如果失败先看是断言失败还是异常失败断言失败说明 Mock 输入和实际输出的预期不一致异常失败说明 Skill 代码本身有问题比如 key 不存在、类型不匹配。4. 方案二Agent 运行时集成测试——验证编排和参数传递单元测试能锁住 Skill 内部逻辑但它回答不了一个关键问题当用户指令到达 Agent 时Agent 能不能正确选中这个 Skill并把参数传对这就是集成测试的职责。4.1 一个最简单的 Agent 运行时为了演示这里用一个最小化的 Agent 运行时只保留核心的意图路由功能# agent/core.py class Agent: 最小 Agent 运行时负责意图识别与 Skill 调度。 def __init__(self, llm_client): self.llm_client llm_client self.skills {} def register_skill(self, skill_name: str, skill): self.skills[skill_name] skill def run(self, user_input: str) - dict: # 第一步识别意图决定调用哪个 Skill routing self.llm_client.route(user_input) skill_name routing.get(skill) params routing.get(params, {}) if skill_name not in self.skills: return {status: error, message: f未找到 Skill: {skill_name}} # 第二步调用 Skill skill self.skills[skill_name] return skill.execute(**params)这个运行时虽然简化了但它已经包含了两层最容易出错的地方路由层LLM 是否把用户意图正确映射到了 Skill 名称参数层LLM 抽取的 params 是否能被 Skill 的 execute 方法正确接收。4.2 集成测试代码# tests/test_agent_integration.py import pytest from unittest.mock import Mock from agent.core import Agent from skills.order_skill import OrderSkill pytest.fixture def agent(): agent Agent(llm_clientMock()) agent.register_skill(order_skill, Mock(wrapsOrderSkill( llm_clientMock(), order_apiMock() ))) return agent def test_route_to_correct_skill(agent): # Mock 路由结果命中 order_skill agent.llm_client.route.return_value { skill: order_skill, params: {user_input: 帮我查一下订单}, } result agent.run(帮我查一下订单) assert result[status] success def test_route_to_unknown_skill(agent): # Mock 路由结果命中不存在的 Skill agent.llm_client.route.return_value { skill: refund_skill, params: {user_input: 我要退款}, } result agent.run(我要退款) assert result[status] error assert 未找到 Skill in result[message] def test_route_params_passed_to_skill(agent): # 验证 Agent 是否把参数完整传递给了 Skill agent.llm_client.route.return_value { skill: order_skill, params: {user_input: 帮我查一下订单}, } agent.run(帮我查一下订单) skill agent.skills[order_skill] # 这里因为 Mock(wraps...) 会透传真实调用可以进一步断言内部依赖被正确调用 order_api skill.order_api order_api.query.assert_called()4.3 集成测试和单元测试的本质区别单元测试关注的是Skill 在给定输入下产出是否正确集成测试关注的是Agent 是否把用户的模糊指令变成了 Skill 的精确输入。一个典型的集成测试能发现的问题是这样的用户在界面上输入我的货到哪了Agent 的路由层把它映射成{skill: order_skill, params: {user_input: 我的货到哪了}}但 OrderSkill 的 execute 方法只接受user_input这个参数——这要没问题可如果路由层传的是{query: ...}Skill 端就会因为参数名不匹配直接抛TypeError。这类问题在单元测试里永远发现不了。4.4 用固定用例集做回归集成测试还有一个进阶用法建设固定用例集golden set。把线上真实用户的高频指令收集一批人工标注出期望路由结果和期望执行结果做成测试用例。每次修改 Agent 提示词或 Skill 逻辑后跑一遍这个集合看哪些用例产生了行为变化。变化不一定都是坏的但必须人工确认。这是目前 Agent 工程化里最实用也最容易被忽视的回归手段。注意这些用例集不要包含敏感信息涉及用户隐私的数据要做脱敏替换。5. 方案三LVM LLM 多模态联合测试——两阶段链路怎么验当 Skill 需要同时使用视觉理解和语言推理时测试复杂度会明显上升。先看一个典型的业务场景。5.1 场景发票信息核验 Skill用户上传一张发票图片Skill 需要用 LVM 从图片中提取发票号码、金额、日期等字段用 LLM 结合提取结果判断发票是否合规决定通过 / 拒绝 / 人工复核。这就是一个典型的 LVM LLM 两阶段链路。LVM 负责看懂LLM 负责判断。5.2 测试难点多模态测试和纯文本测试有三个明显差异测试数据不好构造图片样本的收集、脱敏、标注成本远高于文本LVM 输出本身不稳定同一张图模型可能在不同次运行中提取出略有差异的字段两阶段错误会叠加LVM 提取错了字段LLM 基于错误字段可能得出错误判断而且这个错误很隐蔽。5.3 推荐的分层测试策略对付上述难点推荐把多模态 Skill 拆成三层来测第一层LVM 识别层。使用固定图片资产测试 LVM 输出是否符合预期的字段结构。图片资产必须固定版本任何图片变更都要走 review。第二层LLM 决策层。不调用真实 LVM而是用预先构造好的LVM 输出桩直接喂给 LLM测试判断逻辑。第三层端到端联合层。用少量真实图片打通全链路做冒烟测试不需要覆盖全部分支目的是确认集成没问题。5.4 代码实现先看第二层的决策测试这是最稳定的测试层# tests/test_invoice_decision.py import pytest from unittest.mock import Mock from skills.invoice_skill import InvoiceSkill pytest.fixture def invoice_skill(): # 决策层测试不用真实 LVM直接用桩数据 lvm_client Mock() llm_client Mock() return InvoiceSkill(lvm_clientlvm_client, llm_clientllm_client) def test_approve_valid_invoice(invoice_skill): # 构造一份LVM 输出桩 extracted { invoice_no: INV2024001, amount: 100.00, date: 2024-06-01, } # Mock LLM 判断结果 invoice_skill.llm_client.decide.return_value ok decision invoice_skill.decide(extracted) assert decision ok def test_reject_suspicious_invoice(invoice_skill): extracted { invoice_no: INV2024002, amount: 999999.00, date: 2024-06-01, } invoice_skill.llm_client.decide.return_value reject decision invoice_skill.decide(extracted) assert decision reject def test_manual_review_for_low_confidence(invoice_skill): extracted { invoice_no: None, amount: 100.00, date: 2024-06-01, } invoice_skill.llm_client.decide.return_value manual_review decision invoice_skill.decide(extracted) assert decision manual_review这里的核心思路是决策层测试完全隔离 LVM输入是人工构造的字段字典输出是 LLM 的决策。这样在 LVM 模型升级或图片资产变动时决策层测试不会受到影响。再看 LVM 识别层的测试思路# tests/test_invoice_extract.py import pytest from skills.invoice_skill import InvoiceSkill pytest.fixture def skill_with_fake_lvm(): return InvoiceSkill( lvm_clientFakeLVMClient(), llm_clientNone, # 本层测试不涉及 LLM ) class FakeLVMClient: 在测试环境中替代真实 LVM 的桩实现。 def extract(self, image_path: str) - dict: return { invoice_no: INV2024001, amount: 100.00, date: 2024-06-01, } def test_extract_fields_from_static_image(skill_with_fake_lvm): # 用仓库内的固定图片资产 result skill_with_fake_lvm.extract(tests/assets/invoice_sample_001.jpg) assert result[invoice_no] assert result[amount] assert result[date]注意FakeLVMClient的应用它模拟的是LVM 正常工作时的行为用于验证 Skill 内部对 LVM 返回结果的消费逻辑。真实 LVM 的识别率验证属于模型评测范畴不应该放在 Skill 的单元测试里。5.5 端到端联合层怎么控制成本端到端联合层不建议跑全量用例原因就是成本调用真实 LVM 和真实 LLM 都有费用而且速度慢、不稳定。更推荐的做法是每轮发布前只跑 3 到 5 条代表性用例覆盖正常通过、明显拒绝、边界复核三种类型。目标是抓集成错误不是抓模型效果。如果是内部测试环境可以用开源的视觉模型或按需加载的测试模型降低调用成本。具体模型选型要看团队实际情况没有统一答案。6. 三种方案怎么选对比与搭配建议没有一种测试方案能覆盖所有层级。更合理的做法是三层组合使用。先看对比表对比维度Pytest 单元测试Agent 集成测试LVM LLM 联合测试测试层级Skill 内部逻辑Agent 编排与参数传递多模态两阶段协同运行速度快毫秒级中等秒级慢受模型调用影响稳定性高全 Mock中依赖路由 Mock低真实模型有不确定性成本低中高适合场景Skill 逻辑开发期提示词和 Skill 注册改动多模态能力上线前CI 适用性每次提交都跑每次提交都跑只在关键版本跑6.1 搭配建议实际项目里推荐这样组合提交代码时跑单元测试 集成测试要求全绿合并 MR 时跑集成测试 少量端到端冒烟用例发版前跑完整多模态联合测试 固定用例集回归。这样既保证了开发反馈速度又控制了测试成本。如果你只打算先落地一套方案先做 Pytest 单元测试它投入最小、收益最稳定。7. 常见问题与排查思路下面这些坑都是实际开发中高频出现的按问题现象、可能原因、排查方式和解决方案整理问题现象可能原因排查方式解决方案单元测试全绿Agent 里 Skill 直接报错Mock 返回格式和真实 LLM 差异过大对比 Mock 数据和线上实际 LLM 输出的结构把真实 LLM 输出录制为 fixture用真实响应跑测试测试偶尔失败重跑又通过LLM 输出不稳定检查是否依赖了模型输出的具体文本顺序断言改为结构校验而非文本相等固定 temperature 和 seedLLM 返回的是带解释的 JSON解析报错模型输出被包装在 Markdown 代码块或前后缀中打印完整响应检查是否有 包裹在解析层增加 JSON 提取方法容错处理Agent 路由经常选错 Skill提示词中 Skill 描述不清晰检查路由提示词里每个 Skill 的功能边界描述为每个 Skill 补充触发样例和负例说明多模态测试中图片读取超时图片资源过大检查测试图片文件大小和格式对测试图片压缩限制单张不超过 1MBLVM 提取字段和 LLM 判断不一致两阶段模型能力不匹配拆开分别跑定位是哪一层出错增加中间校验层对 LVM 输出做规则校验测试环境数据污染单元测试和集成测试共用了真实数据库查看测试是否依赖了外部服务所有外部依赖一律 Mock 或使用独立测试库CI 构建超时端到端用例过多看 CI 日志中哪类用例耗时最长把端到端用例从每次提交改为定时或发版触发8. 最佳实践与工程建议8.1 分层 Mock离真实模型越远越要 MockMock 的粒度是一个需要认真权衡的问题。单元测试里LLM、数据库、API 全部 Mock集成测试里路由层 LLM 可以 MockSkill 内部的 LLM 可以保留真实调用端到端测试里全部用真实服务。原则是离被测逻辑越远的依赖越应该 Mock离被测逻辑越近的依赖越应该保持真实。8.2 录制真实模型响应作为测试夹具针对第 7 节提到的Mock 和真实 LLM 输出不一致问题最好的解决办法是把真实 LLM 的典型响应录制下来保存为 JSON 文件作为测试 fixture。这样 Mock 数据不是凭空想的而是真实发生过的能显著降低测试环境通过、生产环境翻车的概率。具体做法是加一个调试开关把 LLM 的请求和响应记录到本地文件人工筛选出有代表性的样本入库。8.3 固定模型参数保证可重复性在测试环境中调用 LLM 时建议固定 temperature 参数通常设为 0 或接近 0并记录模型版本。模型版本一变测试结果可能跟着变。这不是 Bug但要能在排查时快速定位。如果框架支持 seed 参数也可以固定但不能完全依赖它保证确定性。8.4 日志和追踪是测试的一部分Agent 测试失败时最讨厌的是看不到中间过程。建议在 Agent 运行时中加上链路追踪记录每次路由决策、Skill 选择、参数内容、中间结果。排查问题时要能回答Agent 当时为什么选了某个 Skill。日志记录要注意数据安全用户的输入内容和图片涉及隐私的部分要做脱敏或直接不打印。8.5 敏感数据不能进测试集构造测试用例时不要使用真实用户数据、真实证件图片、真实发票。要么脱敏要么用模板生成。多模态测试的图片资产一定要有管理流程避免把含个人信息的图片提交到代码仓库。8.6 测试命名要能表达业务意图测试函数名应该是行为描述而不是过程描述。test_parse_intent_success比test_parse_intent好test_route_to_correct_skill比test_run好。这样测试失败时从名字就能知道哪个行为回归了。9. 总结与后续学习方向这篇文章真正想讲清楚的是一件事Skill 测试必须分层不能指望一套方案解决所有问题。Pytest 单元测试负责锁死 Skill 的内部逻辑Agent 集成测试负责验证编排和参数传递LVM LLM 联合测试负责覆盖多模态场景的真实链路。三者的速度、成本、稳定性各不相同组合起来才是一个完整的测试体系。如果你接下来要继续深入建议按这个路径走先把文中方案一的 Pytest 测试跑通替换成你自己的 Skill然后把方案二的集成测试接入 CI每次都跑最后在涉及多模态能力时再引入方案三的联合测试有条件的话研究一下录制回放和真实模型响应夹具这能解决测试稳定性的最后一公里问题。Skill 测试的难点不在于某个具体工具而在于你是否能清晰区分要测哪一层以及这一层该用什么策略。把这两点想清楚工具反而是次要的。