接触 Agent 开发有段时间后我最大的体感是Agent 项目从“Demo 能跑”到“真正能上线运营”中间隔着的往往不是模型能力而是一堆看不见的工程债。最近我陆续接触了一些做 Agent 交付和外包维护的团队大家聊得最多的话题之一就是怎么帮客户清理那些已经跑不动的 Agent 代码。有人称之为“给 Agent 清理屎山”并且这已经慢慢成了一门独立的生意。这个现象并不奇怪。Agent 项目的迭代速度远超传统后端项目需求方经常上午改 Prompt、下午加工具、晚上换模型开发节奏快工程治理自然就跟不上。于是项目越跑越乱越乱越不敢改最后进入“新需求接不进来旧功能一改就挂”的循环。本文就围绕“Agent 屎山”这个主题先讲清楚它是怎么形成的再给出一套可落地的重构思路和完整代码示例最后聊聊这背后的工程化机会。1. 为什么 Agent 项目特别容易长“屎山”1.1 Agent 项目与传统后端的本质差异要理解 Agent 项目为什么更容易堆出问题先要明白它和普通后端项目的区别。传统后端面向的是相对稳定的业务规则SQL 查询、接口调用、缓存逻辑输入输出基本可控。Agent 项目则不一样它由大模型驱动输入是自然语言输出可能是一个文本回答也可能是一串工具调用指令。这里有一个关键概念Agent Loop智能体循环。简单说Agent 拿到用户问题后会把问题交给大模型模型判断自己是直接回答还是需要调用某个工具如果需要调用工具模型会返回工具名和参数程序执行工具后再把结果交回模型模型继续推理直到得出最终答案。这个过程非常灵活但副作用是每一次循环的输入输出都由模型决定代码很难像传统接口那样做严格的参数校验和状态约束。正因为这种“不可完全确定”的运行方式Agent 项目的工程治理比普通项目更难。我们很难用一套固定的状态机描述 Agent 的全部行为也很难保证模型每一次都按预期调用工具。于是代码里就会出现大量兜底逻辑、异常补丁、临时开关时间一长就是名副其实的屎山。1.2 屎山的三个主要来源结合我观察到的实际项目Agent 项目里的屎山通常有三个来源。首先是需求快速迭代。业务方在使用 Agent 时会不断发现“这个场景模型处理得不好”然后要求调整 Prompt、增加工具、修改系统提示词。这些需求来得很频繁开发人员往往没有时间做完整回归测试只能小步快跑地打补丁。其次是工具数量膨胀。Agent 项目接入真实业务后工具函数会越来越多。今天加一个查订单明天加一个退款后天加一个查询物流如果从一开始就没有统一的工具协议最终就会演变成一个大函数里堆满 if-else 分支或者一个目录下散落着几十个风格迥异的工具文件。最后是模型和框架版本波动。大模型版本更新很快同一个 Prompt 在旧模型上效果好换了新模型可能效果直线下降Agent 开发框架也在快速演进一会儿要求按这种方式注册工具一会儿新增了某种上下文协议。每次升级都可能引发连锁修改代码腐化速度远快于传统项目。2. 一段典型的 Agent“屎山”代码2.1 场景设定为了把问题讲清楚我先设定一个非常典型的业务场景一个客服 Agent。用户会问订单状态、申请退款、查询商品信息等。下面这段代码是典型的“能跑就行”版本很多项目从 Demo 阶段进入真实业务后代码很容易长成这个样子。2.2 典型“能跑就行”的代码长什么样# 文件路径agent_v1.py # 这是很多 Agent 项目早期的真实缩影代码能跑但基本没有工程结构。 import json from openai import OpenAI client OpenAI() # 问题