过去一年，我参与过一个 Agent 项目，最终效果不理想。不是模型不行，不是数据不够，而是架构设计从一开始就埋下了问题。
这篇文章不讲具体产品，只复盘这个项目里最致命的几个架构错误。如果你正在做 Agent 项目，这些教训可能帮你少走一些弯路。
读完你会得到三样东西：
- 理解”过度抽象”在 Agent 项目里具体长什么样
- 知道多工具调用为什么容易变成系统的最大隐患
- 一套在早期就能识别架构风险的检查方法
一、先说结论：这个项目失败在”想做的事太多”
这个项目的原始目标很清晰：做一个能帮助企业用户自动化处理日常事务的 Agent。
但到项目后期，这个 Agent 变成了：
- 能接 20 多个工具
- 能处理多种任务类型
- 能在不同场景下切换不同模式
- 支持多种输出格式
- 内置多轮对话记忆
- 还要兼顾权限控制和审计日志
听起来很完整，但实际运行时，用户最常用的功能只有两三个。而这两三个功能，被其他”完整能力”拖得越来越难用。
问题不是”功能做多了”，而是架构过度服务于”可能的扩展”，而不是”当前的价值”。
二、第一个教训：过早的抽象层
项目早期，团队做了一个决定：为了未来能支持多种模型、多种工具、多种场景，先搭一套”通用 Agent 框架”。
这个框架包括：
- 统一的工具注册接口
- 统一的任务调度层
- 统一的上下文管理器
- 统一的输出格式转换器
- 统一的权限校验钩子
每一层都设计得很”通用”，但每一层都缺乏真实场景打磨。
三个月后，我们发现：
- 工具注册接口改了四次，每次都是因为新工具接入时发现”通用接口不够通用”
- 任务调度层在单任务场景下几乎没用，只是为了”未来多任务”存在
- 上下文管理器处理不了长对话，最后又加了一层补充逻辑
- 输出格式转换器在一种格式稳定前，就试图支持三种格式
抽象层的问题不是”没有价值”，而是”价值还没验证就先做了完整实现”。
正确的做法应该是：
先让一个模型、一个工具、一个场景跑通，再基于真实痛点逐步抽象。
而不是先猜想”未来可能需要”，把架构搭得很大再往下填内容。
三、第二个教训：工具数量不是能力，是复杂度
这个项目最开始的工具只有三个：日程查询、邮件发送、文档检索。
用了两个月后，团队开始加工具：
- 又接了数据库查询
- 又接了浏览器自动化
- 又接了代码执行
- 又接了外部 API 调用
- 还有一个”万能工具”可以执行任意命令
最后工具数量超过 20 个。
问题是：
工具越多，Agent 越难选对工具。
用户问一个简单问题，Agent 可能在多个相似工具之间反复试探，甚至选错工具后进入错误路径。
更严重的是：
- 工具之间的依赖关系没人管
- 工具描述重叠，模型难以区分
- 有的工具功能相似，但参数结构不同
- 工具失败后的 fallback 逻辑不统一
最后的结果是：用户最常见的请求，反而因为工具太多而被”淹没”在选项里。
工具数量增加带来的不是能力提升，而是决策难度提升和稳定性下降。
正确的做法应该是：
只保留高频、稳定、差异化的工具，其他能力通过组合或外部系统解决。
不是所有能力都必须塞进 Agent 的工具列表里。
四、第三个教训：没有清晰的”完成条件”定义
这个项目还有一个问题：几乎每个任务都没有清晰的”完成条件”。
比如用户说”帮我整理一下这周的会议纪要”，Agent 会：
- 先检索会议记录
- 再尝试从邮件里补充信息
- 再去日历里确认时间
- 还可能从文档库里找相关资料
每一步都可能触发新的子任务，每个子任务又可能调用新的工具。
结果就是：
- 用户等很久
- Agent 做了很多事，但不确定什么时候该停
- 最后输出很冗长，但核心信息被淹没
没有清晰的”完成条件”，意味着没有边界。
正确的做法应该是：
在任务开始前就明确：这次调用要做到什么程度就算完成。
可以通过：
- 明确输出格式
- 明确信息范围
- 明确步骤上限
- 明确时间限制
让 Agent 知道什么时候该收敛，而不是无限展开。
五、第四个教训：错误处理链条太长
系统有这么多层，每一层都可能出错。但我们早期的错误处理非常简陋。
典型情况：
- 工具调用失败 → 重试 → 再失败 → 再重试 → 超时
- 子任务失败 → 返回空 → 上层以为成功 → 最终输出不完整
- 外部服务异常 → 异常被吞掉 → 用户只看到”处理失败”
后来我们花了大量时间补日志、补状态追踪、补错误分类。
但这恰恰说明：架构越复杂，错误处理成本越高。
如果一开始就控制复杂度，错误处理链条不会这么长。
六、第五个教训：把”可扩展”当成了”必须实现”
项目中途，团队经常说：”这个可能以后会用到，先把接口留出来。”
比如：
- 留多语言接口，但其实只用中文
- 留多租户接口，但其实只有一个客户
- 留分布式调度接口，但其实只跑单实例
这些”预留”带来的问题是：
- 代码里到处是占位逻辑
- 测试要覆盖很多不存在的场景
- 每次重构都要考虑”会不会影响未来扩展”
“可扩展”不是”现在就实现所有扩展点”。
正确的做法应该是：
先让当前价值跑通，等真实需求出现再扩展。
扩展性是结果，不是预设。
七、这些教训背后有一个共同问题
回顾这五个教训，背后其实有一个共同的根因：
架构服务于”想象中的未来”，而不是”真实的当前价值”。
团队在设计时，想的是：
- 万一以后要支持多模型怎么办
- 万一工具越来越多怎么办
- 万一场景越来越复杂怎么办
但实际的约束条件是：
- 用户只关心两三个核心功能
- 每个功能的调用路径很简单
- 系统稳定性远比功能数量重要
架构的目标不是”看起来完整”，而是”稳定交付当前价值”。
八、如果重来一遍，我会怎么做
如果现在重新做这个项目，我会按这个顺序来：
第一步：只选一个核心场景
不要追求”通用 Agent”，先做一个”能解决某一件具体事的 Agent”。
比如：
- 只做会议纪要整理
- 只做日报生成
- 只做文档问答
第二步：只接两三个工具
足够覆盖当前场景就好，不要提前接”可能有用”的工具。
第三步：先定义完成条件
在写代码之前，先定义清楚：
- 输入是什么
- 输出是什么
- 什么情况算完成
- 什么情况算失败
- 失败后怎么处理
第四步：等真实痛点出现再抽象
不要提前搭框架，先让系统跑起来。
等发现真正的重复逻辑、真正的扩展需求时，再做抽象。
第五步：每加一层都问三个问题
每次要引入新层时，问：
- 这一层解决什么具体问题？
- 这个问题现在真的存在吗？
- 有没有更简单的方式解决？
如果答案不够清晰，就不要加这一层。
九、一个判断架构是否过度复杂的方法
如果你在做一个 Agent 项目，可以用下面这些问题自查：
- 你的 Agent 有几个核心使用场景？用户最常来做什么？
- 你的工具列表里，有多少工具是真正被高频调用的？
- 你的架构里有多少层是”为未来预留”的？
- 用户一个请求，平均要经过多少步才能得到结果？
- 系统里有多少代码是处理”理论上可能发生”的情况？
如果这些问题的答案让你觉得”好像确实有点多了”，那大概率就是过度了。
十、结语：让架构服务于价值，而不是可能性
这个项目最核心的教训，其实就一句话：
架构设计的目标，是让当前价值交付更稳定、更简单，而不是让系统看起来更完整、更通用。
过度抽象和多工具调用，本质上是把”可能性”放到了”价值”前面。
但现实中，系统能稳定解决一个具体问题，比”理论上能解决很多问题”重要得多。
下次你在做架构决策时，可以问自己一个问题：
这一层/这个工具/这个抽象，是为了解决真实痛点，还是为了满足想象中的完整性？
把这句话压缩成一行：
架构越简单，价值越容易兑现；复杂度要等到真正的痛点来敲门时再加。
摘要建议
这篇文章复盘了一个失败 Agent 项目的架构教训，重点列举了五大问题：过早抽象、工具数量失控、缺乏完成条件定义、错误处理链条过长、把”可扩展”当成”必须实现”。文章指出这些问题的共同根因是架构服务于”想象中的未来”而非”真实的当前价值”，并给出了更健康的设计顺序和自查方法。
关键词建议
- Agent 架构
- 过度抽象
- 工具调用设计
- AI 项目架构
- Agent 项目复盘
