构建 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 行为、和快速演进的生态，要求我们用不同于传统软件工程的方式来思考和构建。接受这种不同，是成功的第一步。