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 的万能框架阶段——那些坑已经被踩过了。
AI Agent 项目复盘：半年内踩过的架构坑和修复方案
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 的万能框架阶段——那些坑已经被踩过了。
