AI Agent 项目复盘：半年内踩过的架构坑和修复方案

一、花 3 个月搭了一套 Agent 框架，上线第三天开始改架构

Agent 项目启动时信心满满。参考了 LangChain、AutoGPT 等知名框架，自己封装了一套"万能 Agent 底座"。支持自定义 Tool、记忆管理、多轮对话、流式输出。Demo 跑得飞起，老板看了直说好。上线第三天，第一个问题来了：客服场景需要 5 秒内响应，但 Agent 的 Chain 执行经常超过 15 秒——因为在每个步骤都调一次 LLM，串行执行 4-5 个 Tool，每个 Tool 等待 LLM 输出 2 秒，加上网络延迟和 Tool 本身执行时间，用户等得关了页面。

这个教训的核心：Agent 架构不能追求"通用性"，而应根据"响应时间"SLA 反推设计。客服场景的 SLA 是 5 秒内首次响应，这意味着 Agent 的决策链路不能超过 3 次 LLM 调用。

二、Agent 架构演进历程

下面是架构的 3 个主要迭代阶段：

V1 的核心问题是"LLM 调用次数不可控"。每次 Tool 执行完都问 LLM"够了没"，有时循环 6-7 次才停。V2 改为"意图分流"——客服 FAQ 直接走规则引擎（不需要 LLM），复杂问题才调用 LLM。V3 进一步分级，用"三级路由"保证大部分查询在 500ms 内完成。

三、核心踩坑记录与修复

坑一：ToolSchema 的不稳定性：给 LLM 定义了 15 个 Tool，但 LLM 经常选错——应该查订单数据，它调了知识库搜索。根因是 Tool description 写得不够精确。修复：每个 Tool 的 description 加上"使用场景"和"不适用场景"，并引入 Tool 选择校验（规则检查 Tool 选择是否合理）。

坑二：上下文窗口的"记忆污染"：Agent 的多轮对话历史越来越长，第 10 轮时 LLM 开始"忘记"之前的重要信息（如用户最初的问题）。修复：引入"对话摘要"机制——每 5 轮自动触发一次摘要生成，将历史对话压缩为 300 字的摘要，替代原始对话历史。

坑三：Tool 执行失败后的错误传播：如果 Agent 调了 3 个 Tool，第 1 个成功、第 2 个超时、第 3 个就没执行——整个链失败。但用户的问题是"帮我查订单并推荐类似商品"——订单查到了，只是推荐失败。修复：Tool 的依赖关系从串行改为声明式 DAG（有向无环图），不相互依赖的 Tool 并行执行，单个 Tool 失败不影响其他。

坑四：Token 成本失控：V1 阶段每次对话平均消费 4000 Token（系统提示 1500 + 对话历史 2000 + 输出 500）。每日 5000 次对话，一个月 API 费用超 2 万元。修复：系统提示词从 1500 压缩到 500 Token（去掉废话如"你是一个有用的助手"），对话历史只保留最近 3 轮 + 摘要。

四、从踩坑中提炼的设计原则

原则一：可解释性优先于智能性。Agent 的每一步决策都要留下日志——为什么选了这个 Tool、为什么输出这个答案。没有日志的 Agent 是个黑盒，出了问题只能靠猜。我们给每个 Tool 调用加了一条审计事件，包含：用户提问摘要、选择的 Tool 名称、LLM 给出的选择理由、Tool 的输入参数、Tool 的执行时间和结果、以及最终的置信度评分。这套日志在排查"为什么 Agent 答错了"时，比任何监控面板都有用。有一次用户投诉"Agent 把 VIP 客户当成了普通用户"，我们从日志里追溯发现，是客户查询 Tool 返回了用户等级字段为空，LLM 在没有用户等级信息的情况下默认按普通用户处理。如果不是这条日志，我们会花大量时间排查 Prompt 和模型问题，而实际问题只是一个数据库字段的空值处理。

原则二：显式优于隐式。不要让 LLM"自己决定"要不要终止，而是在系统层面设定最大迭代次数（如最多调用 3 个 Tool）。LLM 的自主决策是个概率事件，工程需要确定性约束。我们在 V2 架构里增加了一个"硬刹车"机制：如果 Agent 在同一轮会话中调用了超过 5 次 LLM，系统强制返回"处理超时，已升级为人工处理"。用户看到这个提示虽然不够智能，但比无限等待然后超时好一万倍。确定性兜底是概率系统的最后一道防线。

原则三：静态路径优于动态推理。对于高频场景（占比 60% 以上），用预定义的决策树代替 LLM 推理。例如"退款"场景的流程固定（查询订单 → 检查状态 → 发起退款 → 发送确认），不需要 LLM 每次"思考"下一步做什么。我们把高频场景的流程固化成了 YAML 配置文件，新增一个场景不需要改代码，只需要加一段 YAML 描述决策树。这其实是在 Agent 系统内部做了一个小的规则引擎——用确定性的方式来管理概率性的能力边界。

五、总结

半年 Agent 项目的核心教训：LLM 的每一次调用都应该被视为"昂贵的资源"，而不是"免费的智慧"。架构设计的目标是减少 LLM 调用次数（从 V1 的 5-7 次降到 V3 的 0-1 次），方法是用规则引擎/小模型/缓存做分流。三个最关键的架构决策：意图分流（高频走规则、低频走 LLM）、Tool 并行执行（DAG 声明式依赖）、以及上下文管理（摘要替代全量历史）。如果你也在做 Agent，建议从 V2 架构开始，跳过 V1 的"万能框架"阶段——那些坑已经被踩过了。