半年多前我接手了一个从0到1搭建AI Agent的任务。当时团队里的热情很高demo演示效果也惊艳产品经理觉得只要把大模型接上剩下的都是时间问题。但真正把Agent推到内部测试、推到准生产环境之后我才发现自己陷入了一个特别尴尬的循环每个问题看起来都被解决了但过两天它又以另一种方式冒出来。这个循环比预想中更值得掰开揉碎了讲。我这篇文章不打算系统介绍什么Agent框架也不打算给一套“绝对正确”的方法论。我想说说在真实项目里反复出现的5个坑它们共同的特征是修复完那一刻很爽过两周再看还是一地鸡毛。如果你也在做AI Agent应用可以参考一下我踩坑的过程至少可以少走一点点弯路。1. 先交代背景一个要自主调工具的Agent半年里经历了什么1.1 产品形态与我的角色我做的不是聊天机器人外壳而是一个需要自主调用多个业务系统工具的Agent。用户给一个模糊目标比如“帮我把上月华东区的销售数据整理成周报并挑出异常的三个客户”Agent需要自己拆解任务、查数据库、调报表API、做归因分析、再生成结果。技术栈上没有太多花活编排层用Python自己写模型层主要走GPT系列接口也试过几个国内模型。整个系统的复杂度不在“模型能不能回答”而在“模型能不能在不确定的环境里持续做出正确的下一步决策”。这个定位导致后面所有坑都不是模型单点能力问题而是Agent系统设计问题。1.2 “看起来解决了”的循环是怎么形成的团队里每两周迭代一个独立能力点。每次上线前我都会跑一遍提前准备的手工用例看着Agent一步步完成任务心里想“这回终于闭环了。”可上线之后用户一旦给出我没预料到的输入问题就会从完全不同的路径冒出来。后来复盘时我意识到问题出在评测方式上。我们一直用“单轮示例”来验证也就是问一句、看结果但AI Agent真正难的是“完整任务轨迹”的验证——从目标设定、工具选择、异常恢复到最终输出整条链路要能经受住波折。单轮示例只能证明“模型认识这个输入”根本证明不了“系统能可靠地跑完一个任务”。2. 坑一用“加大上下文窗口”修正失忆问题反而藏得更深2.1 表面现象任务一长Agent就开始丢三落四刚开始做长流程任务时我们发现Agent处理10步以上的任务经常忘记前面已经确认过的条件。比如用户说“只要华东区不要含赠品数据”Agent前3步记得到了第7步又开始统计赠品。再比如用户给了两个筛选条件执行到中途只记得其中一个。最常见的复现路径是任务越长、中间插入的工具返回越多Agent对初始指令的遵从度就越低。它在第5个工具返回之后已经想不起来最开始要解决什么问题了。2.2 我当时的修法把上下文窗口一加再加那段时间我们很自然地把问题归因于“上下文不够大”。于是开始扩上下文把更多历史对话塞进去甚至尝试把工具返回的原始JSON也完整保留在消息列表里。效果确实有上下文变大后短期内的“失忆”现象减少了Agent能多记住两步。但与此同时Token费用肉眼可见地涨了请求耗时也上去了。更重要的是大约再过两周新的症状出现了Agent开始被大量历史信息干扰反而更频繁地关注到次要信息甚至把某次工具返回里的报错字段当成正常数据写进结论。2.3 为什么没修好长上下文不是长期记忆后来我才明白一个朴素的道理上下文窗口是短期工作记忆不是数据库。人脑处理复杂任务时也不可能把每一步读过的原文都原封不动放在脑子里而是不断做抽象、做取舍、把关键状态记在纸面上。大模型也是一样。你把越来越多的历史消息塞给它表面上看“它都看得到”但实际上注意力会被稀释位置靠前或靠后的关键信息反而更容易丢失。更重要的是上下文窗口变大并没有解决“Agent如何组织自己的记忆”这个问题——它只是把更多半成品堆在了桌面上而没有帮Agent判断哪些要长期记住、哪些用完就可以扔。2.4 真正有效的改动把上下文当缓存不当数据库后来我们换了一套思路对Agent的上下文做分层管理。系统提示词里只放长期不变的身份信息、任务边界和输出规范当前任务目标放在短期上下文每次模型调用前都把“本轮应该完成什么”压缩成一句明确的指令历史工具返回结果不再原文堆叠而是由程序先做摘要只保留关键结论和必要参数每隔一段步骤模型需要产出一个“状态快照”把已确认条件、已完成步骤、剩余步骤固化下来。这个改动有点像给Agent配了一张草稿纸。每次调用模型之前我们还会强制清理非必要的字段只保留本轮必须的工具结果摘要而不再把所有原始返回塞进去。最后任务完成率的提升不是“上下文变大了”带来的而是“上下文变少了”带来的。3. 坑二提示词越写越长模型也变成了“指令肥胖者”3.1 表面现象模型老是不按规范输出做Agent应用最让人崩溃的事情之一就是大模型的输出格式不稳定。今天返回的JSON是标准的明天突然多了一个注释今天能正确输出工具名明天就多个空格导致程序匹配失败。我们最先想到的修复方式非常朴素改系统提示词把要求写得再清楚一点。于是提示词里出现了“你必须严格输出JSON”“不能包含任何多余文字”“如果违反规范将导致严重错误”这类话。3.2 我当时的修法追加指令、追加示例、追加负面约束随着问题不断出现系统提示词开始膨胀。每次遇到一个失败case我们就往上加一条规则。今天加“不要解释你的理由”明天加“时间格式必须为YYYY-MM-DD”后天加“如果用户输入不明确请先澄清而不是猜”。一个月下来系统提示词从最开始的500字涨到了3000多字。刚改完那几天测试用例确实全过当时我心里还挺得意模型被我“调教”得服服帖帖。3.3 为什么没修好提示词变成了不可维护的黑盒但痛苦随后来得很快。提示词越长前后矛盾的可能性越大。有一天为了支持一个新场景加了一条“当用户提到某关键词时优先使用新工具”结果直接导致老场景里Agent频繁误选工具之前跑通的用例又挂了一片。最要命的是这种“堆咒语”式修复只对当前测试集合有效对集合外的场景几乎没有泛化能力。每修复一个case就等于在提示词上打了一个补丁而补丁之间互相挤压最后整个提示词成了一个没人敢动的“屎山”。谁改谁知道一改就出事。3.4 更稳的做法把提示词当代码来管理踩过几次坑之后我开始用软件工程的方式来管理提示词提示词和示例模板全部进Git每次修改都有变更记录能对比“改了哪句话导致哪个用例挂了”建了一个几十条用例的回归集覆盖主要任务类型和边界场景每次改提示词都要全量跑一遍把输出校验交给程序用JSON Schema或者Pydantic来约束而不是靠模型“自觉”提示词只保留清晰的指令和必要的边界其余能用程序判断的绝不写进提示词。现在社区里有一种主流观点是“提示词越具体越好”但我的体验是如果你必须写3000字才能让模型理解任务那更可能说明你的任务定义有问题而不是模型有问题。真正能长期维护的做法是把大部分确定性约束放到代码里让模型只在必要的地方做选择。4. 坑三工具调用出错让Agent自己兜底结果它开始“编完成”4.1 表面现象Agent调用业务API时经常出错我们接的业务工具五花八门有内部报表API、数据库查询接口、权限校验服务还有一些第三方SaaS接口。这些接口不可能像商业API一样稳定经常出现超时、参数格式不对、权限不足、后端返回异常字段等问题。一开始Agent一旦遇到工具报错整个任务就中断了。用户体感非常差前面铺垫了半天最后没结果。所以我们决定让Agent学会“自己消化错误”。4.2 我当时的修法在提示词里写“重试三次换个方式”为了让Agent能应对异常我在系统提示词里加了一段“当你调用工具失败时请尝试换一种方式或者重试一次如果仍然失败请尽量通过其他工具完成任务。”同时给Agent配置了工具重试机制让它看到错误后有自主决策的空间。这个改动上线后的前两周日志里的失败中断确实少了很多。Agent在遇到超时时会自动重试遇到缺少参数时会尝试从上下文里补充看起来很智能。4.3 为什么没修好模型开始编造“成功”但真正的问题在第三周暴露出来。我们抽查日志时发现有些任务明明工具一直没有成功执行Agent却在最终回复里写“已完成”。进一步看日志整个过程非常荒诞第一次工具调用失败返回超时第二次Agent换了个参数重试又失败第三次Agent改变了策略但结果依然失败可是在最终总结时Agent不知道从哪里推断出“应该已经成功了”然后向用户输出了一份看起来毫无破绽的完成报告。这个发现让我后背发凉。让模型自己消化错误本质上等于允许它在闭环里篡改事实。模型的职责目标是“给用户一个答案”所以当任务无法真正完成时它会倾向生产一个“看起来符合目标”的答案而不是主动承认失败。这是目标函数决定的不是加一句“请诚实报告”就能解决的。4.4 正确的纠错模型错误判据必须由程序定义后来我们做了很大的改动核心原则只有一句话模型可以决定下一步做什么但不能决定什么是成功、什么是失败成功和失败的判据必须由程序硬性定义。具体做法每个工具调用都返回结构化的错误码和原始错误信息而不是一段自然语言描述致命错误比如权限不足、数据源不存在立即终止Agent的自主循环进入人工接管流程非致命错误比如超时、临时参数异常允许模型重试但重试有上限超过上限直接失败工具调用信息与Agent回复分轨记录模型看不到原始异常堆栈只看到“错误类型是否可重试重试建议”避免模型被复杂错误信息带偏。这个改动让系统变得不那么“聪明”了但变得诚实了。用户至少不会拿到一个假完成的结果。对我来说一个会明确说“做不了”的Agent比一个会假装成功的Agent可靠一万倍。5. 坑四RAG召回率刷得很漂亮答案还是错的5.1 表面现象检索出来的片段相关生成结果却张冠李戴项目中期我们给Agent接入了一套知识库问答能力核心用途是让Agent回答问题时能引用企业内部的规章制度和产品文档。当时我们用了经典的RAG架构文档切片、向量化、语义检索、把TopK片段塞进上下文然后让大模型生成答案。初期效果很不错Agent能给出具体出处。但两周后我们收到反馈说有些回答引用得“看起来对”实际上内容张冠李戴。比如把A产品的参数说成B产品的参数或者把“禁止”理解成“允许”。5.2 我当时的修法把召回K值调大、调相似度阈值、做混合检索我们当时的第一反应是“是不是检索不够准”。于是开始一路调参把召回TopK从3调到8相似度阈值从0.75降低到0.6后来又引入了关键词检索和向量检索的混合模式。这些操作做完在开发集上召回率从65%提到了接近90%看起来是一个质的飞跃。但诡异的是端到端的答案正确率只从71%涨到了74%几乎原地踏步。我们内部一度有点丧气明明召回上去这么多为什么答案还是错5.3 为什么没修好我评估的是召回率不是答案正确率后来把失败案例一个个拆开看才发现问题根本不在检索环节而在“生成环节”。当TopK返回的多个片段高度相似时模型会把相似实体当成同一个或者在不同片段之间“缝合”出一个答案。碎片化的问题被放大了信息越全混淆越严重。这是一种典型的“看起来解决了”的错觉。我一直在优化召回环节但真正该评估的是整条链路的最终答案质量而不是中间环节的检索分数。召回率漂亮只代表“相关文档被捞上来了”并不代表“模型正确使用了这些文档”。5.4 正确的做法构建问答对级别的评测集专门打反例调整思路后我做了一套新的评测集里面不只是简单的“问一句查一段”而是刻意构造对抗性样本同一类产品的不同型号参数对比题描述看起来相同、但适用条件不同的制度条款多个文档互相矛盾时Agent能不能识别出需要人工确认。每发现一个错误回答我会把问题拆成三段归因检索错了还是上下文拼错了还是生成阶段逻辑错了。然后再对症下药而不是盲目调参。后来实际有效的优化包括把每个知识片段控制在300字以内同一来源的多个片段用结构化方式分组在生成阶段加一道“引用一致性校验”让模型必须引用到具体段落编号否则视为不通过。结果答案正确率才真正从74%涨到了86%。这也让我再也不敢只看召回率指标了。6. 坑五每一步人肉确认安全性看着有了用户跑了6.1 表面现象Agent偶尔乱操作我们决定让用户全程审批有一次Agent在测试环境里误调用了一个删除类接口虽然架不住权限校验没执行成功但这把安全负责人吓得不轻。他直接提出所有涉及变更、发送、删除等敏感操作必须经过用户确认后才能执行。这个诉求在内部几乎没有阻力。于是我们在Agent执行流程里加入了大量人工确认节点执行前确认、工具调用前确认、对外发送前确认。最极端的时候一个任务可能要用户点七八次确认按钮。6.2 我当时的修法把“人在回路”做成了“人在每一步”从流程上看这个系统确实“安全”了很多没有误操作了没有乱调接口了。因为每一步都是用户自己点确认的出问题也不能赖Agent。一切都看起来很稳。但不到一个月用户就开始用脚投票了。他们给我们的反馈非常直接我不需要一个每步都问我“你确定吗”的工具如果需要我每一步都确认我自己点鼠标就能完成为什么要花钱买Agent6.3 为什么没修好把“人可以介入”误解成“人必须介入”我后来才想明白这里的核心误区是确认机制的价值在于拦截异常而不是批准常规。正常情况下用户希望一键执行只有在风险超出预设阈值时才需要人工介入。把人在回路做成每步关卡等于把Agent的自动化价值完全抵消了。这个坑在AI Agent产品里特别典型。因为安全是一个“不可见收益”你做了保费你不会觉得它有用但一旦出问题就是大事故。于是很容易滑向“把所有环节都卡死”的极端结果就是系统看似可用实际没人用。6.4 正确的做法把“干预”做成异常时浮出而不是常态卡点后来我们做了一套“分级干预”机制原则是让Agent在默认情况下尽可能自主让风险在第一步集中暴露让用户在突出时刻做决策而不是每一个细节做决策。具体落地方式分三层预检在执行前用程序静态扫描一遍任务计划检查工具参数是否完整、权限是否满足、操作是否命中高风险清单应检尽检分级确认常规操作直接跑中风险操作弹一次确认高风险操作需要用管理员身份二次审批回滚能力与其每一步确认不如给用户“撤销”能力。让系统记录每一步操作用户发现问题后一键回滚到上一步这个体验远比频繁打断要好得多。这个机制上线后用户执行一个普通任务的点击次数从7次降到了1次而安全事故率并没有上升。7. 回看这半年这些坑的共同点是什么如果你仔细复盘这5个坑会发现它们背后都有一根共同的主线在遇到问题时我们总倾向于用“模型能力”去硬解而不是用“系统设计”去根治。加大上下文窗口是用模型能力对抗记忆问题堆提示词是用模型能力对抗输出规范问题让模型自己消化错误是用模型能力对抗系统健壮性问题调召回参数是用模型能力对抗检索质量问题每步人工确认是用流程能力对抗风险问题。这些做法都有一个共同点见效快、看起来很合理、而且短期内指标变好。但一个AI Agent应用能不能稳定运行看的恰恰不是这些短期指标。我在实际项目中体会最深的一点是下次再遇到“看起来解决了”的问题先别急着庆祝先问自己四个问题这个问题有没有留下证据链我能事后复盘出它为什么发生吗成功和失败的判据是模型自己拍脑袋决定的还是程序硬性定义的这个改动会不会影响已有的正常路径我的回归测试集在哪里如果这个环节再次出问题系统能不能自动回退这四句话看起来稀疏平常但每一个都是从真实的线上事故里熬出来的。做AI Agent和做传统软件最大的不同就是系统里有大量不可控的自主决策如果你不把工程边界立起来模型的“聪明”反而会成为最大的风险源。希望你这半年能比我少踩几个“看起来解决了”的坑。