从0到1搭建可落地的AI Agent与工作流(15):第15期|Agent上线后疯狂出bug?这套n8n调试工作流,20分钟定位

从0到1搭建可落地的AI Agent与工作流｜第14期

你的Agent明明通过所有评测，上线第三天却开始胡言乱语——RAG引用的居然是一年前的旧文档，工具调用凭空少了一个必填参数。你打开n8n执行历史，三万行日志里token和状态来回跳，根本看不出哪里先出的错。问题不在Agent有多复杂，而在你没有给调试留抓手。这一期我们直接在你的工作流外面套一个“调试包装器”，把毒苹果的果核精准剜出来。

本期你将完成

🗺 BUILD MAP · 本期构建路径

真实生产环境里，Agent在用户一个平平无奇的提问下崩溃，通常不是因为它突然变笨了，而是调用链里某个环节悄悄发生了变化。可能是RAG索引更新后检索排序变了，可能是供应商API返回了一个之前没见过的字段格式，也可能是上游状态机在并发的边界下跳错了步骤。这种多因子故障，靠肉眼翻日志基本是撞大运。

更棘手的是，Agent的每一步都是概率性的。你重跑同一个输入，它很可能又好了——这就是典型的“非确定性臭虫”。要让它现原形，必须先消除一切随机变量：温度、模型版本、检索召回顺序、外部时间戳。我们把这一步叫“锁模”，是调试Agent独有的前置条件。

我们在Agent工作流外面包一层n8n子工作流，它像安检传送带一样记录所有进出货。具体做法：在“执行Agent”节点的前后各插入一个“存储快照”节点，用`$execution.resumeUrl`作为唯一运行ID，把输入prompt、输出内容、工具调用列表、模型名称、Token用量、整体耗时打包成一个JSON Object，写入调试专用的数据集（可以用n8n内置数据库或外部云存储）。

这个包装器还有一个好处：即使Agent中途超时或抛出异常，我们也能抓到崩溃前的最后一张快照，不至于像抓一把沙子一样看着日志溜走。调试时，你只需要根据运行ID拉取快照，对比正常轨迹和故障轨迹的差异，马上就能发现是工具返回的数据结构变了，还是模型生成的thought过长触发了截断。

你可能会问：每步都存，存储成本扛得住吗？我们存的是元数据，每条快照不超过2KB，10万次执行才200MB，远比一个模型调用省。而且可以设定期限自动清理，只保留最近7天的调试快照。

有了快照，还得有“诱饵”。你必须为Agent准备一套标准化输入样本，每个样本都要标注期望的完成路径和不允许出现的行为。比如我们上一期接好的RAG客服Agent，正常输入是“最近公司招聘政策有变化吗？”，期望输出应引用最新的HR公告，并明确标出来源发布日期；边界输入是“新政策怎么规定的？”，但不带任何上下文，此时Agent应该询问澄清而不是凭空编造。

这些样本要极其简单——正常用例甚至可以只包含一个词。目的是用最小的干扰因素激活目标模块。如果连最小输入都无法稳定通过，那复杂对话就更没戏了。把这些样本存成n8n的静态数据集，调试时用循环节点逐个投喂Agent，记录每次是否命中期望。这一步的验收指标很硬：正常用例通过率100%，边界用例拒绝（或触发澄清）率100%，恶意注入类输入必须触发安全阻断而非执行工具。

现在你可以开始手术刀式排查了。假设故障现象是Agent回复“根据2024年政策…”但2024年的文档早该被淘汰。第一步，切断RAG检索，直接给模型喂明确答案，看它还会不会乱说——如果不再错，问题在检索环节；如果继续错，则是模型本身对“最近”这个词的理解偏差，你需要改写prompt或添加时间窗口约束。

第二步，如果可疑点在工具调用，创建一个Mock工具，返回你手工构造的固定数据。比如模拟一个“查询账户余额”的工具，错误现象是Agent在余额不足时不调用转账而是继续推销。替换成Mock工具后，如果Agent行为符合预期，那说明原工具的返回格式或触发条件需要调整。相反，如果Mock下依然错，就是Agent的推理逻辑有问题，也许需要加一个“余额不足则终止”的硬护栏。

第三步，故意注入非法状态让Agent接续执行。比如把上一步的审批状态篡改成“已批准”，看Agent是否会跳过安全校验。这种“状态投毒”测试可以提前发现状态转移图里的漏洞——在第7期的人机审批工作流里很常见。真实生产案例里，一个未被检测的状态位翻转曾让某个物流Agent连续放行了三个超标包裹。

调试的终点不是修好一个bug，而是把这次诊断过程固化为自动化测试，防止同一个坑踩两次。把我们准备的10个正常用例、5个边界用例和3个故障注入用例集成为一套n8n测试阵列，每次对Agent或其依赖的API做任何修改后，跑一遍全部用例，输出一份通过率报告。这其实就是第11期生产部署中的health check的延伸，但粒度更细，能直接告诉你“上次能让Agent查询个人信息的工具，这次返回缺少了‘住址’字段”。

你还可以利用n8n的定时触发，每天凌晨用这些用例冲一下Agent，跑不过就自动发邮件。而且调试包装器的快照功能让你可以追溯一个月内的任何一次执行，真正实现“问题不过夜”。

这套方法的价值在我接触的早期项目中反复被验证：一个在企业内部处理合同审批的Agent，上线首周因OCR模型升级导致提取字段错乱，团队用最小输入+Mock工具法在30分钟内锁定新模型输出格式变化，当天就修复了。如果没有调试夹具，他们可能要在几千份合同的日志里翻三天。

调试过程本身也会花钱。用大模型重放错误样本是烧钱黑洞，建议在调试包装器里加一个模型选择开关：正常回归用Claude Haiku或GPT-3.5 Turbo，只在需要精确对齐智能时切到主力模型。另外，快照数据集一定不能存明文密钥，n8n凭据要严格隔离，调试节点的执行权限也应独立授权，避免开发阶段的临时Mock工具不小心被发布到生产环境。

调试时还有一点容易被忽略：侵入性。你往Agent肚子里塞快照节点，会轻微增加延迟（每次多15-40ms），所以这套包装器最好做成“按需激活”——在n8n工作流里用一个布尔变量控制，出问题时一键打开，平时的正常请求干净执行。