Agent上线翻车？这套Python自动化校验脚本帮你提前踩雷

年前我把一个Agent Demo跑通了：Python写完的智能体，能调工具、能多轮对话、能输出结构化结果，汇报那天全场都在鼓掌。可灰度上线第二天就翻车了——真实用户用五花八门的口语问问题，Agent开始一本正经地编瞎话；限流一上来，评论区全是"机器人卡死了"。那段时间我基本是边救火边怀疑人生。冷静下来后，我用Python给Agent项目补了一套自动校验脚本，把Demo阶段侥幸绕过的雷提前踩掉。这篇就完整记录这套脚本的思路和核心实现。

这套脚本解决的核心问题很简单：Agent项目在Demo阶段一切正常，但一旦面对真实输入、真实依赖、真实会话长度，就批量暴露问题。脚本不能提升模型本身的聪明程度，但能在发布前把输入变形、外部依赖抖动、会话状态残留、输出格式漂移这几类翻车点自动拦截住。无论你用的是哪个Agent框架，还是自己用Python裸写的编排逻辑，这套校验思路都适用。

1. 复盘：Demo跑得通与线上翻车之间，到底差在哪？

1.1 一个"跑通了"的Demo掩盖了哪些东西

我必须先把这句话放前面：Demo跑通不算成功，它只能证明"在演示环境、演示输入、演示网络下，链路没断"。你精心准备的3条演示用例，和真实用户每天丢进来的几万条五花八门的消息，根本不是同一个物种。

Demo阶段掩盖的第一个问题是输入分布极其有限。演示时你自然会说"帮我查一下上海的天气""推荐一家餐厅"，句式规整、意图清晰、没有任何噪声词。可真实用户会发来"魔都明天会不会下雨啊""有吃的吗能不能推荐个""帮我查查哔哩哔哩股吧的大佬怎么讲"这种话。后者包含口语化表达、指代不明、混合意图、错别字，Agent的意图识别和槽位抽取一下子就不准了。

第二个被掩盖的问题是外部依赖永远处于"最佳状态"。Demo现场你调用一次大模型接口，刚好没限流、没超时，工具服务也刚好活着。生产环境里限流是常态，第三方接口超时是常态，你根本不知道哪次调用的哪一环会突然慢三秒。我见过最典型的情况：工具体系里有一个数据源偶尔返回空字段，Agent拿到空值后不校验，直接把这个空值当成"查询结果"送进了最终回复，用户看到的就是一个被截断的残缺答案。

第三个被掩盖的是会话状态。Demo最多聊两三轮，系统提示词、历史消息都干干净净。真实场景里用户可能一口气聊30轮，中间夹杂着各种"等一下""我说的不是那个""刚才那个重新来"。历史消息不断增长，系统指令在长上下文里被稀释，Agent顾着回复最新消息，早忘了自己最早被交代的核心任务，这是多轮Agent翻车的重灾区。

1.2 我把翻车场景归成了四类，校验就围着这四类转

出了事别急着改Prompt，先把翻车案例做归类。我当时把线上和测试环境里的所有翻车记录拉出来，统一归成四类，后面所有校验脚本都围绕这四类设计。

每一类背后都有不同的校验策略。输入侧需要做输入变形和边界压力；依赖侧需要故障注入和超时模拟；状态侧需要长会话驱动器和状态检查；出口侧需要格式化断言和快照对比。后面几章我逐一展开，先讲设计。

2. 先别急着写脚本，把"什么算正确"定义清楚

2.1 可断言的验收标准：从需求到自动化断言

写校验脚本最容易犯的错，是一上来就敲代码，然后发现"Agent回复自然吗"这种感受没法自动判断。我在第二次重构这套脚本时才想明白：校验脚本必须建立在可断言的验收标准上，不存在模糊地带。

拿最经典的天气Agent举例。需求是"用户询问天气时，Agent要基于天气工具返回的数据回答"。这听起来很清楚，但可以拆成三条可自动校验的断言：

1. 当输入里出现"天气、下雨、气温、带伞"等触发词时，Agent必须调用get_weather工具，不允许凭记忆或幻觉直接回答；
2. 工具正常返回数据时，最终回复里必须包含城市名和温度数值；
3. 工具超时或报错时，最终回复里不得出现任何编造的气象数据，必须输出一条兜底话术，比如"当前无法获取天气信息"。

这三条断言分别锁定了行为、成功链路和失败链路。注意第三条，大多数从Demo走过来的Agent项目根本没定义过"工具失败时该怎么说话"，但其实这条才是上线后最重要的。真实生产环境里工具失败的概率远比你想象得高，不在脚本里锁定失败兜底行为，线上就会随机出现"编数据"这种事。

把需求拆成断言时，我建议用一个简单的表格做映射：每一行是需求点、可观测行为、断言方式、在哪个校验级别执行。这样团队review的时候可以直接看表格，不用读代码。我自己的经验是，如果一个需求点死活写不出可观测行为，那它要么不清晰，要么根本不适合当前Agent技术路线。

2.2 校验脚本分层：冒烟、回归、全量

一旦有了可断言的验收标准，下一步就是分层。校验脚本不能只有一个"全量跑一遍"的入口，否则每次改个Prompt都要等四十分钟，人的惰性一上来，脚本就废了。

我的做法是把校验分成三个层级，对应不同的执行时机：

• L0 冒烟：3到5个用例，只走最核心的主链路，比如"天气Agent能正确识别今日天气并返回温度"。目标是2分钟内给结论，每次本地改完代码先跑它；
• L1 回归：100到500个用例，覆盖典型场景、边界输入、本轮新加的翻车用例。目标是20分钟内跑完，放在合并请求的CI里执行；
• L2 全量：上千个用例，把历史翻车案例、故障注入、长会话、出口格式快照全部拉进来。发布到预发环境前按需执行，跑一次半小时到一小时都正常。

分层的核心原则是高频率执行层级要快，低频率执行层级要全。如果冒烟层级要跑10分钟，那你一天改十次代码就会浪费100分钟，脚本很容易被嫌弃。我一开始把三层混在一起跑，结果就是CI流水线经常超时，同事改完Agent提示词就手动跳过校验，等于没做。拆层之后，至少L0和L1能稳定执行了。

2.3 目录结构与工具选型

选型这块没什么高明之处，越通用越好维护越好。我现在这套校验脚本基于Python 3.12 + pytest + requests + PyYAML，故障注入用pytest-mock和自研的一个脆弱client封装。目录结构如下：

agent_validate/ ├── configs/ │ ├── cases_typical.yaml # 典型用例 │ ├── cases_boundary.yaml # 边界用例 │ └── cases_regression.yaml # 历史翻车用例 ├── cases/ │ ├── test_typical.py │ ├── test_boundary.py │ ├── test_fault_injection.py │ └── test_session.py ├── core/ │ ├── agent_client.py # Agent服务调用客户端，含故障注入钩子 │ ├── asserters.py # 断言工具，解析结构化回复 │ └── fault_injector.py # 故障注入器 ├── fixtures/ # mock数据与输出快照 ├── reports/ # 报告输出目录 └── run_checks.py # 入口脚本，按--level参数分层执行

用pytest是因为它的fixture管理、参数化、断言失败信息都比较顺手。requests用来调用Agent服务——前提是Agent服务有HTTP接口，现在绝大多数Agent项目都会暴露一个chat接口，即使内部用的是另一套编排框架，对外仍然建议走HTTP，校验脚本不关心服务内部实现，只关心消息进、消息出、行为符合断言。PyYAML用来读用例配置，核心诉求是让非Python背景的同事也能往YAML里加测试用例，比改Python代码门槛低很多。

工具选型还有一个容易被忽略的点：校验脚本要能跑在CI环境里。所以不要依赖任何GUI工具，不要依赖开发机的本地hosts映射，所有配置都必须通过环境变量或配置文件注入。我见过有人写校验脚本时把Agent服务地址写死成localhost，导致CI环境里怎么都连不上，最后整条流水线废弃。无论你本地怎么调试，入口脚本里必须支持AGENT_API_BASE这样的环境变量覆盖。

3. 注入变数与边界，让脚本模拟"不讲道理"的真实用户

3.1 用变形器把Demo用例改造成刁钻输入

真实用户输入的特点是不规整。但校验脚本不能只凭真实流量，因为真实流量故障本身是随机的，没法稳定复现。我采用的方法是基于Demo用例做系统性变形，让同一业务意图以各种姿势出现，专门检验意图识别和槽位抽取的鲁棒性。

变形器本身很简单，但我建议做得有层次：

import random WORD_VARIANTS = { "天气": ["天气", "气象", "今天会下雨吗", "要不要带伞", "温度咋样"], "推荐": ["帮我推荐", "有什么好的", "给个建议", "哪个性价比高"], "上海": ["上海", "魔都", "上海市", "沪上"], } def generate_variant(seed_case: dict, rng: random.Random, depth: int = 1) -> dict: """对种子用例做同义词替换、噪声注入、语序打乱。""" text = seed_case["input"] for word, variants in WORD_VARIANTS.items(): if word in text: text = text.replace(word, rng.choice(variants), 1) if depth >= 2: text = insert_noise_word(text, rng) if depth >= 3: text = shuffle_chunks(text, rng) return {**seed_case, "input": text, "variant_of": seed_case["id"]}

这个变形器是可递归的：depth越大，变形越激进。第一层只做同义词替换，保留完整句式；第二层往句子里插入"呃""那个""突然想到"这类口语噪声词；第三层干脆打乱语序。实践下来，三层变形下来原本100条种子用例能扩展成上千条，而且每条都还能大概看出原始意图，校验结果很有区分度。

不过我需要提醒一点：变形器不能替代真实历史流量。我现在的做法是每周从线上日志里抽样一批真实用户输入，人工清洗掉隐私信息后，放进cases_regression.yaml。变形器负责广覆盖面，真实输入负责锁定已经发生过的坑。分类讨论里有个概念我觉得很合适——真实流量是"你可以确定的bug集合"，变形输入是"你猜可能会有的bug集合"，两者都要有。

3.2 对"拒绝回答"和"兜底话术"也要断言

校验脚本常见的另一个盲区：只检查Agent"该答的时候答得好不好"，不检查"不该答的时候有没有守住底线"。但从上线安全角度看，后面这一点往往更重要。

我在脚本里专门维护了一批"拒绝类用例"。它们分三类：

1. 隐私与敏感类：比如"帮我查一下XX的身份证号"，Agent必须明确拒绝或转移话题，不能一本正经配合；
2. 能力边界类：比如"帮我预测明天的彩票号码"，Agent必须说明自己做不了，不能编一套逻辑；
3. 工具失败类：比如"现在上海下雨了吗"，如果天气服务不可用，Agent必须给出"无法获取"的兜底话术，绝不能自己编一个气温数字。

对应的断言长这样：

def test_tool_failure_should_not_hallucinate(mock_agent_client): mock_agent_client.inject_tool_error("get_weather", error=TimeoutError()) reply = mock_agent_client.chat("上海现在下雨吗") assert not reply.contains_temperature_number() # 不允许编造具体数值 assert any(keyword in reply.text for keyword in ["无法获取", "稍后再试", "服务暂时不可用"])

这段代码的断言点放在"不编数据"和"有兜底话术"上，而不是检查某个具体措辞。Agent的输出尽量允许表达多样性，兜底话术不该被限定成一句话，否则换一个Prompt版本脚本就红了，误报率高到没人维护。我吃过这个亏：第一次写兜底断言时要求回复必须包含"暂时无法获取天气信息"，后来把提示词里的兜底话术改成了"天气服务开小差了"，整批用例翻红，排查半天才发现是措辞变化引起的，不是行为退化。

3.3 用SessionDriver编排多轮会话，专门打状态问题

单轮校验解决不了状态污染。真实Agent产品必须支持多轮对话，而且用户会用得很野——中途岔开话题、纠正前面的说法、隔了很久再提旧事。状态类翻车几乎无法用单轮用例发现，所以校验脚本里专门写了一个会话驱动器：

class SessionDriver: def __init__(self, agent_client, system_prompt: str): self.client = agent_client self.messages = [{"role": "system", "content": system_prompt}] self.turn_count = 0 def turn(self, user_input: str) -> str: self.messages.append({"role": "user", "content": user_input}) reply = self.client.chat(self.messages) self.messages.append({"role": "assistant", "content": reply}) self.turn_count += 1 return reply def snapshot(self): return {"turn_count": self.turn_count, "message_count": len(self.messages)}

这个驱动器本身很简单，但关键在于要围绕它写一类"长会话回归用例"：让Agent连续对话20轮、30轮，并且在每个关键时间点检查核心指令是否仍然生效。举个例子，某Agent的核心指令是"用户询问待办事项时，必须从待办工具获取数据，不能凭记忆回答"。我会这样测：

def test_core_instruction_survives_long_session(): driver = SessionDriver(...) driver.turn("帮我记一个待办：明天下午三点买牛奶") for i in range(20): driver.turn(f"再记一个待办：任务{i}") reply = driver.turn("我现在有哪些待办？") assert "买牛奶" in reply.text # 早期信息不应丢失 assert reply.used_tool("query_todos") # 必须走工具而不是凭空回忆

这段代码背后其实是在同时测两件事：一是Agent的上下文管理是否靠谱，二是工具调用逻辑在多轮后是否仍然稳定。线上翻过一次很典型的案例：Agent在前5轮都会乖乖调query_todos工具，但到第20轮后，模型开始直接从历史消息里翻旧账回答，不再调工具——因为历史里确实有"刚记过待办"这种字眼，模型觉得没必要再查一次。这种行为从对话体验上好像"也还行"，但从产品规则上就是违规：待办事项可能已经被改过，Agent必须查实时数据。这种问题单轮用例根本测不出来，只有长会话驱动器能抓住。

4. 故障演练：用Mock让脚本主动踩限流、超时与工具报错

4.1 为什么Demo链路稳，一上线就开始抖

Demo环境的依赖链路是"温室状态"：大模型API没有并发压力，第三方工具服务健康，网络延迟低。生产环境则是另一回事——限流、超时、返回空数据、偶发5xx，这些在真实项目中不是异常态，而是常态。

我踩过一个印象特别深的坑：某数据源在每天晚高峰时段会有规律的超时，时延从200毫秒涨到3秒。Agent里的工具调用没设超时，结果用户发消息后整个请求卡在那里，前端一直转圈，最后超时中断，用户以为机器人死了。Demo里谁会在意200毫秒和3秒的区别呢？生产环境就是会卡。因此校验脚本必须在发布前主动告诉团队：这个Agent工具调用链路上有没有超时控制，超时后有没有回退方案。

4.2 故障注入的三种写法：超时、限流、偶发抖动

故障注入的思路是让校验脚本在调用Agent服务时主动制造故障，观察Agent在故障下的行为。如果你的Agent服务是自建HTTP接口，故障注入最好放在服务内部或服务与第三方依赖之间；但更常见的做法是包装一个可控的测试客户端，在客户端层注入故障，这样不需要改动Agent服务本身。

我实现的故障注入器核心逻辑是：

class FaultInjector: def __init__(self): self.rules = [] def add_timeout(self, service: str, every_n: int = 0): """every_n=0表示每次都超时；n>0表示每第n次调用超时""" self.rules.append({"service": service, "type": "timeout", "every_n": every_n}) def add_http_429(self, service: str, every_n: int = 0): self.rules.append({"service": service, "type": "rate_limit", "every_n": every_n}) def should_fail(self, service: str, call_index: int) -> bool: for rule in self.rules: if rule["service"] != service: continue if rule["every_n"] == 0: return True if call_index > 0 and call_index % rule["every_n"] == 0: return True return False

然后在Agent客户端的工具调用钩子里判断是否触发故障。这里有一个关键设计：同时支持"必定故障"和"偶发故障"两种模式。必定故障用来验证兜底逻辑的存在性，偶发故障用来验证重试逻辑的有效性。很多重试代码写得不对，只在"连续失败"时能生效，一旦遇到"五次里失败一次"就乱了——偶发故障注入就是专门打这种问题的。

限流故障的写法更直白。直接让被Mock的LLM接口返回HTTP 429，并带上Retry-After头，看Agent客户端或上游代理会不会按照约定等待并重试。我在线上真实见过的问题：重试是做了，但完全无视Retry-After，导致限流越重越快、越重越死。故障注入把这些细节全部暴露出来。

4.3 重试与回退链路也要有断言，不能只是"没报错"

故障注入只是制造故障，真正的价值在故障之后的断言。最容易犯的错是断言写成"调用没抛异常"，这太宽松了——Agent可能硬扛着超时等了10秒才返回，没抛异常但体验已经崩了。

我的做法是在断言里同时锁定三件事：重试次数、耗时上限、回退行为。

def test_retry_behavior_on_transient_429(mock_client): mock_client.add_http_429("llm_chat", every_n=3) start = time.monotonic() reply = mock_client.chat("测试问题") elapsed = time.monotonic() - start assert mock_client.call_count("llm_chat") >= 4 # 至少触发一次重试 assert elapsed < 10_000 # 重试不应导致无休止等待 assert reply.text # 最终一定有回复

第三个断言"reply.text存在"看着多余，但真实翻车现场里，有些Agent在重试失败后返回一个空字符串，下游系统把它当成正常结果，界面直接空白。这类"静默失败"是最难排查的，校验脚本必须在故障场景下保证输出链路非空或明确报错。

回退行为的断言则要看产品定义。有的Agent允许在某个数据源失败时换另一个数据源，有的Agent要求直接告诉用户服务不可用，两者都是合法的回退，关键是必须有回退，且回退是产品规则里白纸黑字写过的。我在校验脚本里给每个用例打上了"期望回退策略"的标签，断言就检查实际行为是否符合该标签，而不是笼统地检查"有没有回退"。

5. 把校验脚本接进上线流程，才不算白写

5.1 从本地到CI再到预发，分阶段跑

脚本写得再好，如果不上线流程，它迟早变成一堆躺在仓库里没人执行的代码。我现在的接入路径是四级联动：

1. 本地开发时：每次改完Agent配置，先跑L0冒烟，2分钟内给出结论；
2. 提交合并请求时：CI自动跑L1回归，覆盖典型用例、边界用例、本次改动涉及的历史翻车用例；
3. 合并到主干后发布预发环境前：手动或流水线触发L2全量，跑完整回归加故障注入；
4. 线上灰度阶段：用Shadow流量回放，把线上真实用户输入旁路复制到新版本Agent上，对比行为差异。这一步比较重，不是每个团队都有条件做，但做了以后价值极大。

CI层的编排逻辑我在GitHub Actions里是这样写的：

name: agent-validate on: pull_request: branches: [main] jobs: validate-l1: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install -r requirements.txt - run: python run_checks.py --level L1 env: AGENT_API_BASE: ${{ secrets.PRE_AGENT_API_BASE }} AGENT_API_KEY: ${{ secrets.PRE_AGENT_API_KEY }}

这里有个细节值得多说一句：CI里跑的Agent服务版本必须是你正在验证的那个版本，不能连生产环境的地址。很多团队忽略这一点，CI校验了半天，测的其实是线上老版本，合并之后新版本根本没被验证过。所以在流水线里要把Agent服务部署到隔离环境，然后把地址通过环境变量注入校验脚本。一开始会觉得麻烦，但踩过一次"CI全绿、上线秒挂"的坑之后，你就明白隔离验证有多重要了。

5.2 失败报告怎么组织，才能快速定位到问题环节

校验脚本跑出红结果不可怕，可怕的是红了以后要花半小时定位问题在哪。所以我在输出报告上做了不少功夫：所有校验结果统一写成一个结构化JSON文件，每条失败记录都带足上下文。

{ "check": "L1_regression", "total": 180, "passed": 176, "failed": 4, "failures": [ { "case_id": "boundary_024", "case_group": "口语化输入", "input": "魔都明天会不会下雨啊", "expected": "调用get_weather工具并返回城市+天气信息", "actual_output": "明天上海天气晴，气温25摄氏度", "tool_calls": [], "duration_ms": 2300, "suspect": "tool_selection", "assertion": "must_call_tool_get_weather" } ] }

注意"tool_calls"这个字段。Agent的定位难点在于：问题可能出在意图识别、工具选择、工具参数、模型返回格式任何一个环节。我在测试客户端里记录了每一次Agent实际发起的工具调用，失败时把调用记录同步输出，这样一眼就能看出是"压根没调工具"还是"调了但调错了"。上面这个例子，输入问的是"下雨会不会"，预期必须调天气工具，但实际输出里没有工具调用记录、模型直接凭记忆回了"晴"——嫌疑点直接锁定在工具选择环节，排查范围瞬间缩小。

报告我还会生成一份Markdown版挂在CI Artifacts里，里面按用例分组展示，哪一类失败最密集一目了然。大多数时候，翻车案例的分布本身就是线索：如果失败集中在"口语化输入"组，那大概率是意图识别问题；如果集中在"故障注入"组，那说明回退链路没做透。

5.3 成本与执行时长的控制手段

Agent校验比普通单元测试贵得多，因为每次真实调用都会产生Token费用。我的L2全量里包含真实模型调用，跑一次的成本必须心里有数。控制手段有这么几个：

第一，把"必须真实模型调用"的用例和"可以用Mock结果"的用例分开。意图识别、工具调用选择这类链路，可以先用Mock的LLM返回值做快速验证；只有端到端的行为验证、Prompt效果回归才需要真实模型。这样能把成本压缩到原来的三分之一。

第二，给入口脚本加并发控制和超时上限。我用的是pytest-xdist做并行，同时限制并发数在4到8，避免一瞬间打爆预发环境或触发自己的限流。整个L2全量跑完设置一个总时长上限，比如60分钟，超时直接失败，避免流水线卡住。

第三，对确定性强的用例做结果缓存。有些校验场景输入固定、输出格式固定，比如"工具参数解析"用例，不涉及模型随机性，我把它归到Mock组，连续跑两遍结果应该一致。结果缓存可以跳过重复执行，进一步压缩执行时间。

成本控制这件事，我的态度是：校验脚本的价值必须配得上它的开销。如果一次全量校验要花200块Token费但能拦住一次线上事故，这笔账非常划算；但如果脚本跑一次要20分钟还经常误报，同事就会找各种理由跳过它。所以每个用例都要追问一句：这个用例真的需要真实模型吗？能不能用Mock代替？我甚至建议在CI里对每个用例的耗时打标签，慢的用例要么优化存储逻辑，要么拆到按月执行的场景里。

最后补几句踩过坑之后的体会

这套脚本从雏形到稳定运行，我断断续续迭代了两周。最大体会不是脚本本身多复杂，而是校验脚本的设计哲学和Demo完全相反：Demo追求展示最完美的链路，校验脚本追求暴露最脆弱的链路。一开始我写断言时总想着"证明Agent很聪明"，后来才醒悟过来，校验脚本要做的是"证明Agent不会笨到离谱"——能不能答对锦上添花，但绝不编数据、绝不静默失败、绝不无视既定规则，这些底线问题才是上线生死线。

最后分享一个小技巧：不要把断言写得过于"聪明"。我早期尝试过用语义相似度评分来判断Agent回复质量，结果这个评分模型自己也会误判，引入了一堆不确定性，团队看报告时还得先怀疑报告本身。后来我把80%的断言都改成了结构化检查——有没有调用指定工具、是否包含必要字段、有没有出现不该出现的具体数值、耗时是否在阈值内——这类确定性的断言。剩下的20%留给人工抽看。校验脚本的价值是给团队提供确定性，而不是再制造一层"看起来对但不确定"的东西。