构建 AI Agent 的过程充满了意外。以下是 21 个最痛苦的教训，每条都是实战踩坑后的反思。
#架构与设计
1. 过度工程是头号杀手
第一个 Agent 项目总想做得「正确」：选最酷的框架、设计最通用的抽象、考虑所有边缘情况。结果三个月过去，还没上线。Agent 应该快速验证，快速迭代。
2. Agent 不是产品，是基础设施
太多团队把 Agent 当成 feature 做——「我们在 App 里加个 AI 助手」。但 Agent 的维护成本、监控需求、失败模式都和传统 feature 完全不同。它更像数据库或消息队列，是底层基础设施。
3. 多 Agent 系统的协调比想象中难 100 倍
一个 Agent 做一件事很简单。五个 Agent 协作时，状态同步、错误传播、任务分配、死锁检测——每个都是深水区。不要低估多 Agent 系统的复杂度。
#提示词与模型
4. 提示词是代码，不是配置
提示词需要版本控制、代码审查、A/B 测试、回滚策略。把它当成配置文件随手改，迟早会在生产环境踩雷。
5. 模型选择不是越大越好
GPT-4 不是万能解药。很多任务用更小的模型更快更便宜，效果差距不大。关键是任务匹配，不是模型参数。
6. 上下文窗口是稀缺资源
不要浪费 token 在无关信息上。Agent 的上下文管理策略（压缩、摘要、选择性加载）直接影响成本和性能。
#工具与集成
7. 工具调用失败是常态，不是异常
外部 API 会超时、会限流、会返回垃圾数据。Agent 需要优雅降级策略，不能把工具调用失败当成 edge case 处理。
8. 不要给 Agent 太多工具
工具越多，选择越困难，出错概率越高。给 Agent 它真正需要的工具，而不是所有可用的工具。
9. 工具描述的质量决定调用准确率
模糊的工具描述导致错误的工具选择。花时间在工具描述的精确性上，回报巨大。
#监控与调试
10. 监控 Agent 比监控传统服务难 10 倍
传统服务的失败模式是确定性的：HTTP 500、超时、内存溢出。Agent 的失败模式是非确定性的：「模型产生了幻觉」「工具选择错误」「推理链断裂」。需要全新的监控思维。
11. 日志不是可选的，是生存的
Agent 的每一步决策、每次工具调用、每个中间状态都需要记录。没有日志，生产环境出问题等于盲人摸象。
12. 成本失控是沉默的杀手
Agent 的 token 消耗可以指数级增长。没有预算控制和告警，月底账单会让你惊醒。
#用户体验
13. 用户不知道 Agent 在做什么
黑箱 Agent 让用户焦虑。展示思考过程、当前步骤、预计时间——透明度建立信任。
14. 允许用户介入和覆盖
Agent 不是全知全能的。给用户随时介入、纠正、覆盖的能力。Human-in-the-loop 不是弱点，是设计特性。
15. 失败时要优雅
Agent 卡住时，不要让它无限循环或返回垃圾。设计好的失败路径：回退到人类、提供部分结果、或者清晰说明为什么无法完成。
#团队与流程
16. AI 工程师和传统工程师的协作是挑战
两个群体的工作方式、思维模式、成功标准都不同。不主动管理这种差异，团队会分裂。
17. 评估（Eval）是基础设施，不是一次性工作
没有持续评估，Agent 的质量会随时间漂移。每次模型更新、提示词改动、工具变更都需要回归测试。
18. 不要外包核心 Agent 能力
用第三方 Agent 平台快速启动可以，但核心能力（推理、规划、记忆）应该内建。外部依赖的变更会打乱你的产品节奏。
#长期维护
19. Agent 的债务累积速度惊人
提示词债务、工具债务、上下文债务——Agent 系统的技术债务比传统系统累积更快，因为组件之间的耦合更松散、更动态。
20. 文档化 Agent 的行为几乎不可能
传统系统的行为可以通过代码和配置文档化。Agent 的行为是 emergent 的，取决于模型、提示词、工具、上下文的复杂交互。接受这种不确定性，设计相应的运营策略。
21. 准备好重写
第一个 Agent 架构大概率不是最终架构。Agent 技术演进太快，今天的最佳实践明天可能过时。保持架构的模块化和可替换性，比追求一次性完美更重要。
#结论
构建 AI Agent 是一场马拉松，不是短跑。这些教训的核心主题：Agent 系统的不确定性、 emergent 行为、和快速演进的生态，要求我们用不同于传统软件工程的方式来思考和构建。接受这种不同，是成功的第一步。