Python Agent 上线避坑：自动校验脚本与异常捕获实战

1. 从 Demo 到上线，Agent 项目最容易翻车的三个环节

做过 Agent 项目的人大概都有过这种体验：本地跑 Demo 的时候一切丝滑，工具调用、多轮对话、记忆读写全都正常，日志干干净净。结果一部署到测试环境或者交给同事试用，各种稀奇古怪的问题就冒出来了——工具参数传错、模型返回格式漂移、上下文超长被截断、某个环节静默失败但整个链路还在往下跑。最要命的是，这些问题往往不是每次都复现，而是偶发性的，你盯着日志看半天也找不到规律。

我自己在做一个基于 Python 的 Agent 编排项目时就踩过这个坑。Demo 阶段用的是固定的测试用例，输入输出都在预期范围内，跑一百遍都没问题。上线之后面对真实用户的多样化输入，问题集中爆发：有的请求触发了工具调用但参数缺失，有的模型返回了非 JSON 格式导致解析失败，还有的因为上下文累积过长触发了截断逻辑，但截断之后的状态没有正确回滚。这些问题如果靠人工一条条排查，效率极低，而且很容易漏掉边界情况。

所以我决定用 Python 写一套自动校验脚本，核心目标不是替代单元测试，而是在 Agent 执行链路的每个关键节点做实时校验和异常捕获，把问题在发生的瞬间就记录下来，并且给出可复现的最小用例。这套脚本后来帮我节省了大量排查时间，也让我对 Agent 项目的质量保障有了更系统的认识。这篇文章就把这套方案的完整思路、实现细节和踩坑经验分享出来，适合正在做 Agent 开发、准备上线或者已经被线上问题折磨过的朋友参考。

2. 自动校验脚本的整体设计思路

2.1 为什么选择在链路中埋点而不是只做端到端测试

很多人做 Agent 测试的第一反应是写端到端用例：给定输入，断言最终输出。这种方式在 Demo 阶段够用，但上线后的问题往往出在中间环节。比如工具调用的参数格式错了，但模型恰好用某种方式绕过去了，最终输出看起来正常，实际上链路里已经埋了雷。等到某个特定输入触发时，整个流程就崩了。

我的思路是在 Agent 执行链路的每个关键节点埋校验点，包括输入解析、意图识别、工具选择、参数生成、工具执行、结果解析、记忆读写、上下文管理等环节。每个校验点做两件事：一是检查当前节点的输出是否符合预期格式和约束，二是记录完整的上下文快照，方便出问题时回溯。

这样做的好处是，问题发生时你能立刻知道是哪个环节出的错，而不是面对一个最终输出发呆。而且因为每个节点都有快照，复现问题变得非常容易——直接把快照喂给对应的节点就能重现。

2.2 校验脚本的模块划分与职责边界

整套脚本我分成了四个核心模块，每个模块职责清晰，方便单独调试和替换。

第一个是校验规则引擎，负责定义和执行各种校验规则。规则可以是格式校验、范围校验、枚举校验、正则匹配等，支持组合和优先级。第二个是快照记录器，在每个校验点自动保存输入输出、时间戳、节点名称、执行耗时等信息，序列化后存到本地文件或内存队列。第三个是异常分类器，对捕获到的异常进行归类，区分是模型输出问题、工具执行问题、还是编排逻辑问题，方便后续统计和告警。第四个是最小用例生成器，当检测到异常时，自动从快照中提取关键信息，生成一个可独立运行的最小复现用例。

这四个模块之间通过一个轻量级的事件总线通信，避免耦合过重。实际用下来，这种划分方式让后续扩展变得很容易，比如后来我想加一个性能监控模块，只需要订阅事件总线上的耗时事件就行，不用改动原有代码。

2.3 与现有测试框架的配合方式

这套校验脚本不是要替代 pytest 或者 unittest，而是作为补充。单元测试负责验证单个函数的逻辑正确性，集成测试负责验证模块间的协作，而校验脚本负责在真实运行环境中做实时监控和异常捕获。三者配合使用，覆盖了从开发到上线的完整周期。

具体来说，我会在 pytest 的 fixture 里初始化校验脚本，让每个测试用例执行时自动开启校验。这样单元测试不仅能验证功能，还能顺便检查链路中的格式和约束。上线之后，校验脚本以守护模式运行，持续监控 Agent 的执行状态，异常时触发告警并保存现场。

3. 核心校验点的实现细节与代码拆解

3.1 输入解析阶段的格式校验与清洗

Agent 的输入来源很多样，可能是用户直接输入的自然语言，也可能是上游系统传来的结构化数据。这个阶段最常见的问题是格式不符合预期，比如期望 JSON 但收到了纯文本，或者字段缺失、类型错误。

我的做法是定义一个输入契约，明确每个字段的类型、是否必填、取值范围。然后用一个校验函数在解析前做检查，不符合契约的输入直接拦截并记录，避免脏数据流入后续环节。

from typing import Any, Dict, List import json class InputValidator: def __init__(self, schema: Dict[str, Any]): self.schema = schema def validate(self, raw_input: Any) -> tuple[bool, str, Any]: if isinstance(raw_input, str): try: data = json.loads(raw_input) except json.JSONDecodeError as e: return False, f"JSON解析失败: {e}", None else: data = raw_input for field, rules in self.schema.items(): if rules.get("required") and field not in data: return False, f"缺少必填字段: {field}", None if field in data: expected_type = rules.get("type") if expected_type and not isinstance(data[field], expected_type): return False, f"字段 {field} 类型错误", None if "enum" in rules and data[field] not in rules["enum"]: return False, f"字段 {field} 取值不在允许范围", None return True, "校验通过", data

这段代码看起来简单，但实际用的时候有几个细节要注意。第一，JSON 解析失败是很常见的情况，尤其是上游系统拼接字符串的时候容易出问题，所以要把解析和校验分开，方便定位。第二，类型校验要小心 Python 的 bool 是 int 的子类这个坑，如果字段期望 int 但传了 True，isinstance 会返回 True，需要额外判断。第三，枚举校验的取值列表最好从配置文件读取，方便后续调整而不用改代码。

注意：输入校验不要做得太严格，否则会拦截掉一些虽然格式不规范但语义正确的输入。我的经验是必填字段和类型必须严格，取值范围可以宽松一些，把边界情况记录下来后续分析。

3.2 工具调用参数的完整性检查

工具调用是 Agent 最容易出问题的环节。模型生成的参数可能缺字段、类型不对、或者值超出了工具能处理的范围。如果不在调用前检查，工具执行时就会抛异常，而异常信息往往不够清晰，排查起来很费劲。

我的方案是在工具注册时定义一个参数契约，包括每个参数的类型、是否必填、默认值、取值范围。调用前用契约做校验，不通过就拦截，并把模型的原始输出和校验失败原因一起记录下来。

class ToolParamChecker: def __init__(self, tool_registry: Dict[str, Dict]): self.registry = tool_registry def check(self, tool_name: str, params: Dict) -> tuple[bool, List[str]]: errors = [] if tool_name not in self.registry: return False, [f"未注册的工具: {tool_name}"] contract = self.registry[tool_name]["params"] for name, rules in contract.items(): if rules.get("required") and name not in params: errors.append(f"缺少必填参数: {name}") continue if name in params: value = params[name] if "type" in rules and not isinstance(value, rules["type"]): errors.append(f"参数 {name} 类型错误") if "range" in rules: low, high = rules["range"] if not (low <= value <= high): errors.append(f"参数 {name} 超出范围") return len(errors) == 0, errors

这里有个实际经验：模型生成的参数经常是字符串形式的数字，比如 "5" 而不是 5。如果契约里写的是 int，校验就会失败。我的处理方式是在校验前先做一次类型转换尝试，能转就转，转不了再报错。这样既保证了后续工具执行的类型正确，又不会因为格式问题误杀。

另外，工具的参数契约最好和工具的实际实现放在一起维护，避免两边不一致。我见过有的项目契约写在一个地方，工具实现在另一个地方，改了一边忘了另一边，结果校验通过了但工具执行还是报错。

3.3 模型输出格式的容错解析

Agent 依赖模型输出结构化数据来驱动后续流程，但模型输出格式漂移是家常便饭。有时候多了一层 markdown 代码块标记，有时候 JSON 里多了注释，有时候干脆返回了一段自然语言解释。如果解析逻辑不够健壮，整个链路就会断在这里。

我的做法是写一个多级容错解析器，按优先级依次尝试不同的解析策略。第一级直接 json.loads，第二级去掉 markdown 标记后再解析，第三级用正则提取 JSON 片段，第四级尝试用 ast.literal_eval 解析 Python 字典格式。每一级失败都记录原因，全部失败则抛出带完整原始输出的异常。

import re import ast class RobustParser: def parse(self, text: str) -> tuple[bool, Any, str]: strategies = [ ("direct", lambda t: json.loads(t)), ("strip_markdown", lambda t: json.loads(re.sub(r"```(?:json)?|```", "", t).strip())), ("regex_extract", lambda t: json.loads(re.search(r"\{.*\}", t, re.DOTALL).group())), ("literal_eval", lambda t: ast.literal_eval(t)), ] for name, func in strategies: try: return True, func(text), name except Exception: continue return False, None, "all_failed"

实测下来，这四级策略能覆盖绝大多数情况。direct 和 strip_markdown 处理正常输出，regex_extract 处理模型在 JSON 前后加了说明文字的情况，literal_eval 处理模型用了单引号或者 Python 风格字典的情况。如果四级都失败，那基本可以确定是模型输出严重偏离，需要人工介入。

提示：每一级解析成功后，把使用的策略名称记录下来。如果发现某个策略的使用频率突然升高，说明模型输出风格在变化，可能需要调整提示词或者更新解析逻辑。

3.4 上下文长度与记忆状态的边界检测

Agent 的上下文会随着对话轮次增加而不断累积，最终可能超出模型的上下文窗口。如果不做检测，要么请求被拒绝，要么模型自动截断导致信息丢失。更隐蔽的问题是，截断之后记忆状态和实际上下文不一致，后续轮次基于错误的记忆做决策。

我的方案是在每轮对话开始前计算当前上下文的 token 数，接近阈值时触发压缩或摘要逻辑。同时维护一个记忆状态快照，记录哪些信息已经被压缩、哪些还在原始上下文中。压缩后校验记忆状态和上下文的一致性，不一致就回滚并记录。

class ContextGuard: def __init__(self, max_tokens: int, threshold: float = 0.85): self.max_tokens = max_tokens self.threshold = threshold def check(self, context: List[Dict], memory: Dict) -> tuple[bool, str]: current_tokens = self._count_tokens(context) if current_tokens > self.max_tokens: return False, f"上下文超限: {current_tokens}/{self.max_tokens}" if current_tokens > self.max_tokens * self.threshold: return True, "接近阈值，建议压缩" if not self._memory_consistent(context, memory): return False, "记忆状态与上下文不一致" return True, "正常"

token 计数这里有个坑，不同模型的 tokenizer 不一样，精确计数需要调用对应的 tokenizer。如果不想引入额外依赖，可以用字符数除以一个经验系数做估算，比如英文约 4 字符一个 token，中文约 1.5 字符一个 token。估算虽然不精确，但配合 0.85 的阈值留出余量，实际用下来够用。

记忆一致性检查的逻辑是：遍历记忆中的每条记录，确认它引用的上下文片段确实存在且未被修改。如果记忆引用了已经被压缩掉的内容，就说明状态不一致，需要回滚到压缩前的快照。

4. 异常捕获、分类与最小用例生成

4.1 异常分类体系的设计

异常捕获不难，难的是分类。如果所有异常都混在一起，排查时还是得一条条看。我设计了一个三层分类体系：第一层按发生环节分，包括输入、意图、工具选择、参数生成、工具执行、结果解析、记忆、上下文；第二层按异常性质分，包括格式错误、类型错误、范围错误、超时、空值、逻辑冲突；第三层按严重程度分，包括致命、警告、提示。

分类的依据来自校验点的上下文。比如工具执行环节抛出的异常，如果错误信息里包含 timeout，就归为超时；如果包含 KeyError，就归为格式错误。分类结果会写入异常记录，方便后续统计和告警。

这张表是我根据实际项目中的异常分布总结的，不同项目的分布可能不一样，但分类思路是通用的。关键是要让每个异常都能被归到某个明确的类别里，避免出现"其他"这种模糊分类。

4.2 最小复现用例的自动生成逻辑

异常发生时，最有价值的信息是一个能独立复现问题的最小用例。我的生成逻辑是从快照中提取异常发生节点的输入、当时的上下文状态、以及相关的配置参数，组装成一个可以直接运行的脚本。

class MinimalCaseGenerator: def generate(self, snapshot: Dict) -> str: node = snapshot["node"] input_data = snapshot["input"] context = snapshot.get("context", {}) config = snapshot.get("config", {}) case = f''' # 自动生成的最小复现用例 # 异常节点: {node} # 异常时间: {snapshot["timestamp"]} from agent.core import {node} input_data = {repr(input_data)} context = {repr(context)} config = {repr(config)} result = {node}(input_data, context, config) print(result) ''' return case

生成的用例会保存到本地文件，文件名包含时间戳和异常分类，方便后续查找。实测下来，这个功能帮我节省了大量手动构造复现条件的时间，尤其是那些依赖特定上下文状态的偶发问题。

注意：生成用例时要注意脱敏，如果输入数据包含用户隐私信息，需要先做替换再写入文件。我一般会把敏感字段替换成占位符，并在文件头注明原始数据的哈希值，方便对照。

4.3 告警触发与日志落盘策略

校验脚本捕获到异常后，需要决定是立即告警还是先记录。我的策略是按严重程度分级：致命异常立即告警，同时落盘完整快照；警告异常只落盘，累积到一定数量后汇总告警；提示异常只记录计数，定期统计。

告警渠道我用了最简单的方案：写入一个专门的告警日志文件，由外部的日志监控工具负责推送。这样校验脚本本身不依赖任何外部服务，部署简单，也不会因为告警服务不可用而影响主流程。

日志落盘要注意两点：一是文件大小控制，单个文件不要超过 100MB，超过就滚动；二是保留期限，我一般保留最近 7 天的详细日志，更早的只保留统计信息。这样既能满足排查需求，又不会把磁盘撑爆。

5. 实操中踩过的坑与排查技巧

5.1 校验规则误报的常见原因

校验规则太严格是误报的主要原因。我一开始把工具参数的范围卡得很死，结果模型生成的参数稍微偏一点就被拦截，导致大量正常请求被误判。后来调整了策略：必填和类型严格校验，范围只做警告不做拦截，把边界情况记录下来后续分析。

另一个误报来源是类型判断。Python 的 bool 是 int 的子类，如果参数期望 int 但传了 True，isinstance 会通过。我的处理是在类型校验前先排除 bool，除非契约明确要求 bool 类型。

还有一种是浮点数精度问题。模型生成的 0.1 + 0.2 可能不等于 0.3，如果范围校验用了精确比较就会误报。我的做法是范围校验用容差比较，比如 abs(value - expected) < 1e-6。

5.2 快照体积过大的优化方案

快照记录完整上下文会导致体积迅速膨胀，尤其是长对话场景。我一开始每个校验点都记录完整上下文，结果一天下来生成了好几个 GB 的日志。后来做了几个优化：第一，只记录与当前节点相关的上下文片段，而不是全部；第二，对重复出现的上下文做去重，用引用代替复制；第三，超过一定大小的快照做压缩存储。

优化之后，快照体积下降了大约 80%，排查时需要的上下文信息依然完整。关键是要想清楚每个校验点真正需要哪些信息，而不是无脑全量记录。

5.3 校验脚本本身性能开销的控制

校验脚本运行在 Agent 的主链路上，性能开销必须控制。我实测下来，如果每个校验点都做完整的序列化和落盘，单次请求的延迟会增加 50ms 以上，对于高并发场景是不可接受的。

优化方案是异步落盘：校验在主线程同步执行，但快照的序列化和写入放到后台线程池。这样主链路的开销只有校验本身，通常在 1ms 以内。另外，对于高频的提示级异常，只做内存计数，定期批量落盘，避免频繁 IO。

还有一个技巧是采样。对于非致命的校验点，可以按一定比例采样记录，比如 10% 的请求记录完整快照，其余只记录摘要。这样既能发现规律性问题，又不会产生过多日志。

5.4 常见问题速查表

这张表是我在实际项目中遇到过的典型问题，每个问题都对应了具体的排查方法和解决方案。建议根据自己的项目情况补充完善，形成自己的速查表。

6. 从校验脚本到质量保障体系的延伸

这套校验脚本最初只是为了解决上线后的排查效率问题，但用着用着发现它的价值不止于此。因为每个校验点都在记录数据，积累一段时间后就有了一个宝贵的异常数据集。我用这个数据集做了几件事：一是分析异常分布，找出最容易出问题的环节，针对性优化；二是把高频异常转化为单元测试用例，提前拦截；三是监控异常率的变化趋势，作为版本发布的质量指标。

具体来说，我会每周统计一次异常分类的分布，如果某个环节的异常率突然升高，就说明最近的改动可能引入了问题。另外，我会把校验脚本捕获的异常自动转化为 pytest 用例，加入到回归测试集中。这样每次发版前跑一遍回归，就能覆盖大部分已知问题。

还有一个延伸用法是把校验脚本的输出接入到 Agent 的可观测性面板上，实时展示各环节的健康状态。这样运维人员不用看日志就能知道 Agent 当前是否正常，异常时也能快速定位到具体环节。

这套方案不是一蹴而就的，我前后迭代了大概两个月，才把校验点覆盖到所有关键环节，把误报率降到可接受的范围。如果你刚开始做，建议先从工具调用和结果解析这两个最容易出问题的环节入手，跑通之后再逐步扩展到其他环节。校验规则也不要一次写太多，先覆盖必填和类型，范围校验后续再加。这样循序渐进，既能快速看到效果，又不会因为规则太复杂而难以维护。

最后分享一个小技巧：校验脚本的配置文件最好和 Agent 的代码放在同一个仓库里，用版本控制管理。这样每次改动都有记录，出问题时可以快速回滚到上一个正常版本。我见过有的项目把校验配置放在外部系统里，改了什么没人知道，排查时非常痛苦。