Agent Demo 跑通了上线却翻车我用 Python 做了一套自动校验脚本说实话搞 Agent 开发的人大部分都经历过这么一遭Demo 演示的时候Agent 表现神勇工具调用行云流水答案回答得又准又全客户当场点头。结果一上生产同样的活儿它在真实数据面前直接原地宕机要么答非所问要么工具参数格式错到离谱要么一个简单 query 愣是能绕出七八轮死循环。我之前也栽过。后来想明白了Demo 能跑通只能证明你有一个能工作的原型证明不了你的 Agent 在复杂、多样、不可控的真实输入下仍然稳定。真正的问题在于大部分Agent项目缺了一层“专门为 LLM 交互设计”的自动化校验层。传统的单元测试覆盖不了 prompt 的行为变化端到端测试又太重太慢等发现问题的时候生产事故已经发生了。所以我自己用 Python 写了一套轻量级的自动校验脚本专门用在 Agent 上线前后的回归验证上。它不是端到端测试的替代品也不是单元测试的变体它是介于两者之间的一个“契约冒烟层”把 Agent 的输入、工具调用序列、最终输出质量全部用自动化的方式钉死。这篇文章把整套方案的思路、代码结构、踩过的坑都拆开讲清楚。1. Demo 能跑上线为什么翻车问题不在模型在校验1.1 三个最典型的上线翻车场景先说几个我实际遇到的翻车场景。第一个是输入漂移。Demo 阶段你拿给 Agent 测的 query 往往是规范、完整、意图明确的比如“帮我查一下华东区上个月的销售额”。但生产环境的真实用户输入是什么是“那个上个月华东卖得咋样”是“查一下就那个区域对销售”甚至可能是带错别字、中英混杂、还夹着口语化表达的句子。Prompt 模板是为理想输入设计的一旦真实输入偏离了预期分布Agent 的意图识别、参数抽取、工具路由就全乱了。第二个场景是工具调用参数格式问题。Demo 里你测的是 happy path模型调用工具时参数规规矩矩。生产环境里模型可能会把日期格式传成“2024/8/1”而不是约定的“2024-08-01”会把数字金额带上“元”“块”这样的单位甚至会在 JSON 里多一个逗号或少一个引号直接导致下游工具解析失败。这类问题单测很难覆盖因为工具函数的单元测试用的是合法参数而 Agent 的“非法参数”恰恰是模型动态生成的你根本无法预先把所有脏数据写进函数测试里。第三个场景是链路状态的污染和多轮上下文错乱。比如 Agent 支持先查天气再推荐穿搭Demo 时上下文干净Agent 按顺序调用工具没问题。生产里用户可能已经在会话里聊了十来轮上下文里包含无关闲聊、历史工具返回的旧数据、甚至上一次调用失败的报错信息。模型被这些噪音干扰后可能跳过必要的工具调用直接凭历史记忆生成答案或者突然调用一个不该调的工具。这类问题单纯靠观察一两个 Demo 用例根本暴露不出来。1.2 传统测试手段为什么不管用我和很多团队聊过这个问题发现大家不是不想测而是手里没有合适的工具。单元测试只能测独立的函数Agent 的行为是被 Prompt 和模型权重共同决定的你没法对一段 Prompt 写 assert端到端测试倒是能覆盖完整链路但每次跑都依赖外部服务慢不说还极其不稳定动不动就超时CI 里红一片根本没法作为日常回归手段。更关键的是Agent 的输出天然带有非确定性。同一个问题同一个模型温度调成 0两次输出的措辞也可能不完全一样。你没法用“字符串精确相等”去断言 Agent 的回答。这就逼着我们必须设计一套新的校验框架——不是去断言“模型输出了什么”而是去断言“模型是否遵守了我们约定的行为契约”比如是否调用了预期的工具、调用顺序是否正确、给工具传的参数是否符合 schema、最终答案是否覆盖了用户问题的核心信息点。这正是我这套 Python 脚本的核心设计逻辑。1.3 自动校验脚本到底在解决什么问题这套脚本解决的不是“模型回答得好不好”这种主观质量问题而是“Agent 行为是否符合与系统交互的契约”这种客观一致性问题。它把 Agent 对外表现的三个层面——意图理解层、工具调用层、答案生成层——全部转成可断言的检查点。只要 Agent 的行为在契约范围内哪怕措辞稍有不同也算通过一旦跳出契约立即报错定位。这样我们就能在每次代码改动后快速跑一遍知道这次改动是让 Agent 变得更守规矩还是破坏了什么。用一句话概括这套脚本就是给 Agent 装了一个“行为合规检测仪”让那些原本要等到上线被用户骂了才能发现的问题提前在测试环境里暴露出来。2. Python 技术选型和整体校验架构设计2.1 为什么用 Python 而不是其他语言选 Python 做这套脚本不是因为它比 Java 或 Go 更高级纯粹是因为在 Agent 开发这个语境下Python 的生态和协作效率是最优解。你开发 Agent 大概率本身就用 Python那校验脚本和业务代码用同一种语言意味着可以直接复用内部的工具函数、Pydantic 模型、配置加载逻辑不需要搞跨语言桥接。另外一个很实际的原因是 pytest 生态。做 Agent 校验需要大量的前后置逻辑、依赖注入、fixture 管理、参数化用例pytest 这套东西几乎是现成的。fixture 里可以初始化 Agent 实例、加载测试配置、准备 mock 服务用例里只要写断言逻辑。而且 pytest 的参数化能力特别适合批量跑“同结构、不同输入”的校验用例写一条用例模板喂几十组输入自动生成几十个测试用例出问题后能精确定位是哪一组输入触发的。还有一点Python 有非常成熟的请求 mock 库比如 respx、responses。Agent 在生产环境要调一堆外部 API测试环境不可能真调用 mock 库拦截 HTTP 请求把预置的响应返回给 Agent既能控制 Agent 的行为路径又能避免测试期间产生真实的外部调用费用和网络延迟。2.2 校验脚本的整体架构分层这套脚本的架构我按功能拆成了五层。配置层负责读取 YAML 格式的校验用例用例里定义输入 query、期望调用的工具序列、工具参数的检查规则、输出答案的关键信息点。场景层负责构造测试环境包括加载 Agent 实例、注册 mock 响应、准备临时知识库或数据库数据。执行层负责发起对话请求、驱动 Agent 运行、记录完整的内部调用轨迹。断言层负责把执行结果和配置规则做比对给出通过或失败的判定。报告层负责汇总执行情况输出 JSON 格式的测试报告方便 CI 系统解析展示。选 YAML 而不是 JSON 做用例格式主要原因是可读性和注释能力。校验用例是写给人看的PM 和算法工程师也要参与 reviewYAML 天然的缩进结构和注释支持让他们不用看代码就能理解一条用例覆盖了什么场景。JSON 写复杂嵌套时满屏括号根本没法人工 review。整个执行流程是这样的pytest 启动后fixture 创建临时配置目录加载所有 YAML 用例每个用例被参数化成一条测试项执行时先向 Agent 发起对话请求在请求发出之前mock 层已经注册好预期返回Agent 内部如果发送 HTTP 请求会被 respx 拦截并返回预设数据Agent 跑完后从运行上下文中抽取调用轨迹和用例里的期望序列做对比。这里有个关键点Agent 框架本身要能暴露自己的调用记录如果用的是 LangChain 或自研框架一定要在 Agent 的基类里挂一个 callback 钩子把每一步 tool_call 的请求参数和响应摘要记录下来。没有这一步后面的断言逻辑根本无从下手。2.3 目录结构和核心模块的设计思路我建议把脚本按功能模块划分而不是按测试类型划分。核心目录大概是这样的config 目录放全局配置和所有校验用例core 目录放 Agent 实例的加载工厂和环境上下文cases 目录放 pytest 的用例入口utils 目录放 mock 工厂和报告生成器reports 目录放每次运行的输出。这样划分的目的是为了让“加一条新用例”变成一个纯粹的配置操作而不用动代码。为了说明具体结构我给一个简化的目录示例agent_verifier/ ├── config/ │ ├── global.yaml │ └── cases/ │ ├── weather_rec_flow.yaml │ └── sales_query_flow.yaml ├── core/ │ ├── agent_loader.py │ ├── context.py │ └── trace_recorder.py ├── cases/ │ └── test_agent_flows.py ├── utils/ │ ├── mock_factory.py │ ├── assertors.py │ └── report.py └── conftest.pycore/trace_recorder.py 是这套方案里最容易忽略却又最关键的模块。很多 Agent 项目没有记录中间轨迹的习惯导致 Agent 执行完只看到一坨最终回答中间调了什么工具、传了什么参数全部无从追溯。我封装了一个 Recorder在 Agent 的每一步执行后记录事件类型、工具名、输入参数、返回摘要、耗时。有了这个 Recorder断言逻辑就不需要去解析 Agent 最终输出的文本而是直接检查结构化日志这样判断既准确又高效。3. 核心校验细节实现从用例设计到断言策略3.1 校验用例的 YAML 设计规范写校验用例是这套方案的重心用例质量直接决定校验的可靠性。我设计用例字段时遵循的原则是用例必须能精确表达“Agent 应遵守的行为契约”。一条完整的用例至少要包含 id、desc、input、expect 四个部分。id 用来唯一标识desc 是给人类看的场景描述input 里除了 query 还可以带 mock 数据和会话历史expect 里就是我们要断言的内容。expect 部分我拆成了四个子结构。expect_call_sequence 用来声明期望的工具调用链比如先调用“查天气”工具再调用“查穿搭”工具expect_tool_args 是对工具参数的约束比如查天气工具必须传符合 date 格式和 city 取值的参数expect_answer_contains 是期望最终答案里包含的关键信息短语expect_no_tool_called 用来声明这个场景下严禁调用的工具这个字段非常有用能有效防止 Agent 答非所问时乱调工具兜底。下面是一个真实用例的 YAML 示例- id: weather_query_informal desc: 用户使用口语化表达询问天气并期望得到穿搭推荐 input: query: 明天北京那边冷吗穿啥合适 history: [] expect: call_sequence: - get_weather - get_outfit_advice tool_args: get_weather: city: 北京 date: 2024-11-10 answer_contains: - 天气 - 气温 no_tool_called: - search_news这个用例设计的一个核心思路是校验的不是答案“完美不完美”而是答案“有没有守住边界”。只要 Agent 调用了正确的工具、传了合规的参数、回答了关键信息点、且没有乱调其他工具就算通过。答案措辞漂移是无所谓的。这样一来非确定性问题就被绕过去了。3.2 工具调用序列和参数的断言实现实现调用序列断言时我遇到一个实际问题Agent 框架返回的轨迹里工具调用可能是嵌套的也可能有重试逻辑直接把调用列表拉平逐项比较很容易误判。我最后是基于事件序列做的断言把 Agent 从开始到结束产生的所有事件按顺序编号只取 tool_call 类事件组成调用序列再和期望序列比对。比对时支持前缀匹配和完整匹配两种模式。前缀匹配用于处理“Agent 先调了工具 A然后自由发挥”的松校验场景完整匹配用于严格规定全流程的场景。参数断言则用 JSON Schema 做约束。每个工具在定义时本来就有一个函数签名我们把它转成 JSON Schema然后对 Agent 实际传进来的参数做校验。这里有个特别多坑的地方模型经常把参数值类型搞混。比如日期字段模型可能传一个“2024年11月10日”这种带中文的字符串数字字段可能传带逗号的千分位字符串。直接用 schema 校验大概率失败但这是不是 Agent 的错呢看场景如果下游函数已经做好了解析那这不算错如果下游函数接收原始参数那就是错。所以我在 assertor 里做了一层“宽松解析”逻辑先尝试用 schema 严格校验失败后做一次标准化解析再判断解析后的值是否满足要求。这样既保留了对格式问题的敏感度又避免因为无关紧要的变体导致测试不稳定。3.3 答案内容与非确定性输出的断言策略答案质量的断言我摒弃了任何“字符串完全相等”的思路基本只做三层校验。第一层是关键词命中抽取用户问题里的核心实体和动作词确认答案里出现了对应匹配第二层是语义相似度用 embedding 模型把用户问题和 Agent 答案映射到向量空间计算相似度分数低于某个阈值就判失败这个方法对“答非所问”非常敏感第三层是分类器判定对特别重要的场景我会单独训一个简单的二分类器判断答案内容是否真正回应了用户指令。三层校验各有侧重关键词命中保证实体覆盖语义相似度保证相关性分类器保证意图符合度。需要特别说明的是语义相似度阈值的确定。我一开始把阈值设成 0.8结果一大堆“模型回答得完全没问题但表达风格不同”的用例被判失败。后来我把阈值下调到了 0.68并且引入了一个回归基线集每次调整阈值时先在基线集上跑一遍确保不会因为阈值调整导致以前通过的用例失败。踩过这个坑之后我对所有“主观类断言”都坚持用回归基线集来校准参数而不是拍脑袋定数字。3.4 Mock 外部依赖的关键处理方式Agent 的完整链路几乎必然依赖外部 API测试环境里不能真调。我用 respx 做 HTTP 层的 mock拦截特定 host 和 path 的请求返回预置 JSON 响应。设计 mock 时要注意两点一是 mock 的粒度按场景划分而不是按接口划分二是 mock 返回的数据要和用例输入保持一致。比如用户问“北京天气”mock 的天气接口返回的数据里城市必须对应北京否则 Agent 会从返回数据里提取城市信息数据不一致会诱导 Agent 返回错误答案。另一个关键点是 mock 请求匹配规则不能写死后端完整 URL。Agent 服务在测试环境部署时域名可能是 localhost:8000也可能是 staging.example.com如果请求匹配规则里硬编码域名换环境就跑不起来了。我的方案是配置一个 base_url 变量所有 mock 规则的请求匹配都基于相对路径运行时用 base_url 拼接出完整匹配 URL这样同一份校验用例能够同时跑在本地开发环境和 CI 环境里。4. 接入 CI 之后的日常回归和排障技巧4.1 把校验脚本集成到 CI 流程里写好了校验脚本如果没有日常跑价值就很有限。我的做法是把它做成 CI 流程里必过的检查门禁。每次 PR 涉及 Agent prompt、工具定义、Agent 编排逻辑、工具返回结构这些关键文件时自动触发校验任务跑完整用例集跑完产出 JSON 报告报告里附上每个用例的通过失败情况、失败原因、触发输入的追踪 ID。任何一条用例挂了PR 不能合入。这里有个工程细节如果用例集比较大全量跑可能要花几分钟这会让开发者体验变差。我给用例打了标签分级smoke 级是每次 PR 必跑的覆盖核心流程full 级是合入主干前跑一次覆盖全场景nightly 级则跑那些耗时重但对稳定性要求极高的长链路场景。分级之后开发迭代期的反馈速度能保持在秒级到分钟级CI 总时长也不会失控。4.2 高频问题测试不稳定、偶发失败和误报做自动校验脚本最痛苦的问题是测试本身的偶发性失败。模型在不同时间给出的回答有随机性同一个用例可能上一次过、这一次挂这种“flaky test”是校验脚本最大的敌人。我处理这类问题的思路是分层排查先看失败发生的位置如果是在答案语义断言阶段大概率是阈值边缘案例需要微调阈值或补充更多相似度样本如果是在工具调用序列阶段大概率是模型在复杂输入下发生了链路分叉需要补充 prompt 示例或调整示例选择策略。另外一个常见问题是 mock 数据和真实数据结构不一致导致 Agent 在本该成功的场景里表现异常。比如真实 API 返回的数据里多了一个嵌套字段而 mock 返回的没有Agent 抽取信息失败最终输出不完整。这类问题排查起来特别隐蔽因为失败发生在 Agent 内部外层只看到答案不满足断言。后来我在 Recorder 里增加了对每一步工具返回数据的指纹记录出了问题可以直接对比 mock 数据和真实数据结构五分钟就能定位是不是 mock 数据陈旧。4.3 一些可以让这套脚本更好用的执行细节运营一段时间后我总结出几个能显著提升效率的经验。用例的输入数据不要太单一不要总是用规范化的 query特意往里面加口语化表达、长尾问题、带噪音的输入这些才是生产环境的常态。给每条用例附带一个“预期用时”字段如果实际执行超过了预期用时会自动标黄提醒因为 Agent 反应变慢往往是模型上下文被撑爆的前兆。报告输出一定要包含 Agent 的关键 trace 片段而不只是“通过/失败”状态否则排障时要重新跑一遍才能拿到上下文浪费时间。我还做了一个特殊标记机制给 API 调用接了一个“对比通道”。在校验场景里如果 Agent 第一次调用某个工具失败了会自动触发一次“带明确重试指令”的重新调用同时记录前后差异。这个机制模拟了生产环境里我们可能会做的轻量自愈也暴露了很多潜在问题因为很多 Agent 框架默认没有重试机制一次失败就中断整个任务。5. 脚本落地后给项目带来的实际改变5.1 从“演示型 Agent”变成“可靠型 Agent”引入这套校验脚本之后我最大的感受是Agent 从“演示型”向“可靠型”迈出了实质的一步。以前提升 Agent 稳定性靠的是人工反复试各种问题试到累了就以为没问题了实际上覆盖的输入空间极其有限。现在每一次改动 Prompt、调整工具描述、升级模型版本都会自动过一遍几十条精心设计的校验用例任何行为回退都能在半小时内被发现而不是等到用户反馈。印象最深的是有一次我把某个工具的描述改得更详细了结果跑校验时发现“查询天气后推荐穿搭”这条链路断了。排查后才知道改描述时不小心改变了工具的参数格式说明模型开始在新格式和旧格式之间摇摆抽取出带单位的时间字段下游解析失败。如果没有校验脚本这个问题要等到把改动合入主干、部署到生产、被真实用户触发之后才会暴露可能又是一次线上事故。5.2 校验用例本身就是团队的“行为需求文档”另外一个意外收获是校验用例集慢慢变成了团队的“行为需求文档”。新同学来了与其翻烂 PPT 学习 Agent 应该做什么不该做什么不如把校验用例读一遍每条用例就是一条行为契约。产品经理评审新需求时也会翻看现有用例确认新改动会不会破坏已有行为。校验用例不是项目的负担而是团队沟通的桥梁。而且这份“文档”是活的。每发生一次线上问题我都会把故障场景沉淀成一条新的校验用例确保同样的问题永远不会再次通过测试。这种“事故驱动开发”的模式让校验用例集越来越接近生产环境的真实输入分布Agent 的稳定性也随之越来越扎实。5.3 快速上手的建议和注意避开的坑如果想把这套方案引入自己的项目我的建议是不要一上来就追求大而全。先把最常见的三类场景写成用例核心 happy path、典型的口语化输入、容易误判的边界输入。能用十条例覆盖就先十条先把校验链路打通后续再逐步扩充。强行一开始就搞几百条用例很可能因为用例设计质量参差、阈值没调优导致大量误报团队很快就会放弃这个工具。还有几个坑可以提前避掉。不要用真实 API 去跑校验用例成本高、不稳定、还可能引发数据安全问题全部用 mock个别关键链路做“mock 与真实对比测试”即可。断言逻辑不要散落在用例代码里统一封装成断言工具函数这样调整断言策略时不用改几十个文件。文档里记录的阈值、相似度基线、模型版本必须在 CI 里通过测试来维护任何人为调参都应该有回归基线集做支撑否则就是靠感觉控制质量。最后说一个我自己特别深的体会Agent 跟传统程序本质上的区别在于它的行为是概率事件校验脚本的目标不是消灭概率而是把概率风险控制在可接受的范围并且在概率风险变成真实事故之前及时发现。把校验脚本当作 Agent 的“安全带”而不是“自动驾驶”摆正心态这个事情就能真正发挥价值。
