1. 从“演示惊艳”到“上线翻车”Agent项目不稳定的真实面貌做Agent项目的人大概都经历过这种落差Demo阶段模型能流畅地调用搜索、查数据库、发邮件甚至还能自己规划多步任务围观的人都说“这东西要成了”。可一旦接入真实用户、真实数据、真实并发问题就来了——同一个问题问两遍答案不一样昨天跑通的流程今天卡在第三步工具调用参数偶尔少一个字段整个链路直接崩掉。用户反馈就一句话“它有时候很聪明但我不敢用。”这个现象背后其实不是模型“变笨了”而是Agent系统里那些在Demo阶段被忽略的工程问题在真实场景下被放大了。Agent和普通的大模型对话应用最大的区别在于它不是一次输入一次输出而是一个带状态的、多轮次的、依赖外部工具的循环系统。这个循环里任何一个环节不稳定最终表现就是“时好时坏”。我先把结论摆在这里Agent项目“看起来聪明、用起来不稳定”核心矛盾集中在四个地方——工具调用的可靠性、上下文的组织与衰减、状态的持久化管理、以及缺乏可量化的评估集。这四个词也是当前Agent开发圈讨论最多的关键词。接下来我会逐个拆开讲每个部分都会说清楚“为什么会这样”“怎么排查”“怎么改”尽量给到可以直接抄作业的方案。这篇文章适合两类人看一类是正在做Agent项目、被稳定性问题折磨的开发者另一类是准备入局Agent、想提前避开这些坑的工程师。不需要你有很深的模型训练背景但需要对API调用、状态管理这些基础工程概念有基本认知。2. 工具调用Agent最脆弱的“手和脚”2.1 为什么工具调用是故障高发区Agent之所以比普通聊天机器人“能干”是因为它能调用外部工具——搜索、计算器、数据库查询、代码执行、发请求等等。但工具调用恰恰是整个链路里最容易出问题的一环。原因很简单模型输出的是自然语言而工具需要的是结构化参数。这两者之间的转换天然存在不确定性。举个最常见的例子。你给Agent定义了一个查询天气的工具参数是city和date。用户问“明天北京冷不冷”模型需要输出类似{city: 北京, date: 2024-06-15}这样的结构化调用。但实际运行时模型可能输出{city: 北京市, date: 明天}也可能把参数名写成location甚至直接输出一段解释文字而不是工具调用。这些在Demo里可能因为测试用例少而没暴露但真实用户的问题千奇百怪边界情况一多失败率就上来了。更麻烦的是工具调用失败往往不是“优雅失败”。如果模型输出了非法JSON解析直接抛异常如果参数缺失工具端报错如果工具超时整个Agent循环可能挂起。这些错误如果没有被妥善捕获和处理用户看到的就是“Agent卡住了”或者“它胡说八道”。2.2 工具定义的三个关键细节要让工具调用稳定第一步是把工具定义写扎实。我见过太多项目工具描述就一句话参数说明也含糊然后指望模型“猜对”。这是不现实的。第一工具描述要写清楚“什么时候用”和“什么时候不用”。比如一个搜索工具不要只写“搜索信息”而要写“当需要获取实时信息、新闻、或模型知识库之外的事实性内容时使用当问题涉及计算或已有明确答案时不要调用”。这样能减少模型在不该调用时乱调用的情况。第二参数要尽量少且必填明确。参数越多模型出错的概率越高。如果一个工具需要五个参数考虑能不能拆成两个工具或者给参数设默认值。必填参数和可选参数要在schema里明确区分别让模型去猜。第三给参数加约束和示例。比如日期参数在描述里写“格式为YYYY-MM-DD例如2024-06-15”。枚举类型的参数把所有可能值列出来。这些细节看起来琐碎但能显著降低参数错误率。下面是一个工具定义的对比左边是常见的“偷懒写法”右边是相对可靠的写法维度偷懒写法可靠写法工具描述“查询天气”“查询指定城市指定日期的天气情况当用户询问天气、温度、是否下雨时使用”参数名infocity、date参数描述无“城市名称如北京、上海”、“日期格式YYYY-MM-DD”必填标记不明确明确required字段错误处理无定义参数非法时的返回格式2.3 工具调用的容错与重试策略即使工具定义写得再好模型偶尔输出格式错误也是正常的。关键是要有容错机制而不是一出错就崩。我的做法是分三层处理。第一层是解析层容错当模型输出的工具调用JSON解析失败时不要直接抛异常而是尝试用正则提取关键字段或者把原始输出回传给模型让它重新生成一次。这个“重试一次”的机制能救回相当一部分偶发错误。第二层是参数校验层在真正执行工具之前先校验参数是否合法。比如日期格式对不对、必填字段有没有缺、枚举值是否在允许范围内。校验不通过时把具体的错误信息返回给模型让它修正后重新调用。这比直接执行然后报错要友好得多。第三层是执行层兜底工具执行本身可能超时、可能返回异常。这时候要设置合理的超时时间并且给模型一个明确的“工具执行失败”的信号让它决定是重试、换工具、还是直接告诉用户暂时无法完成。注意重试次数一定要设上限通常1到2次就够了。无限重试会让Agent陷入死循环既浪费token又让用户等待。2.4 工具数量膨胀带来的选择困难还有一个容易被忽视的问题工具太多。刚开始做Agent可能就三五个工具模型选起来很准。但随着功能增加工具涨到二三十个模型就开始“选错工具”了。这不是模型能力问题而是选择空间太大相似工具之间容易混淆。解决办法有两个方向。一是工具分组把功能相近的工具归到一个类别下让模型先选类别再选具体工具降低单次决策的复杂度。二是动态工具加载根据当前对话的上下文只把相关的工具暴露给模型。比如用户问的是订单问题就只加载订单相关的工具而不是把所有工具都塞进prompt里。这两种方法我在不同项目里都用过动态加载的效果更明显但实现复杂度也更高。如果工具数量在十个以内先把描述写清楚通常就够了超过十五个就值得考虑动态加载了。3. 上下文管理Agent的“记忆”为什么靠不住3.1 上下文窗口不是越大越好现在很多模型都支持很长的上下文窗口动辄几十万甚至上百万token。这让很多人产生一个错觉既然窗口这么大那就把所有历史对话、所有工具返回结果都塞进去不就行了实际用下来会发现上下文越长Agent反而越容易“迷失”。原因有几个。首先模型对上下文中间部分的注意力天然弱于开头和结尾这是已知的“中间遗忘”现象。当上下文塞满了几十轮对话和大量工具返回的原始数据时真正关键的信息可能被淹没在中间模型根本“注意不到”。其次长上下文意味着更高的延迟和成本每一轮都要处理大量token响应变慢用户体验下降。最后无关信息越多模型被干扰的概率越大可能基于过时的信息做出错误决策。所以上下文管理的核心不是“塞更多”而是“留对的”。这其实就是上下文工程要解决的问题——在有限的窗口里放最相关的信息。3.2 上下文的分层组织方法我在实际项目里会把上下文分成几个层次来管理每一层有不同的保留策略第一层是系统指令和工具定义这部分相对固定放在上下文最前面确保模型始终能看到自己的角色和可用工具。第二层是任务相关的关键信息比如用户的原始需求、已经确认的关键参数、当前任务的进度。这部分需要显式维护不能指望模型从历史对话里自己提取。第三层是近期对话历史保留最近若干轮完整对话让模型能理解当前的对话语境。通常保留最近5到10轮就够了更早的对话可以压缩成摘要。第四层是工具调用结果这部分往往最占空间。我的做法是工具返回的原始数据不直接塞进上下文而是先做一次提取和压缩只把和当前任务相关的字段保留下来。比如搜索返回了十条结果可能只需要保留标题和摘要不需要把整个网页内容都放进去。这种分层管理的好处是上下文的使用是可控的、可预测的。你知道每一轮大概会消耗多少token也知道关键信息在什么位置不会出现“聊着聊着模型忘了自己在干什么”的情况。3.3 对话状态管理的实操方案对话状态管理是Agent稳定性的另一个关键。所谓状态就是Agent在当前任务中“记住了什么”。如果状态管理没做好用户说“帮我订一张去上海的票”Agent查了航班用户接着说“改成后天”Agent可能就不知道“改成后天”指的是哪个航班了。我的做法是维护一个显式的状态对象而不是完全依赖对话历史。这个状态对象里包含当前任务类型、已收集的参数、待确认的信息、已执行的操作。每一轮对话结束后更新这个状态对象下一轮开始时把状态对象序列化后放进上下文。这样做的好处是状态是结构化的、可检查的。当Agent行为异常时你可以直接看状态对象里存了什么快速定位是“没记住”还是“记错了”。相比之下如果状态完全隐含在对话历史里排查起来就非常困难。状态对象的更新可以用模型来做也可以用规则来做。简单场景下规则就够了比如“用户提到日期就更新date字段”。复杂场景下可以让模型输出一个状态更新的结构化结果然后合并到状态对象里。两种方式可以结合使用。3.4 上下文压缩与摘要的时机当对话轮次很多时就需要做上下文压缩。压缩的核心是“把旧信息变成摘要把关键信息保留下来”。但压缩的时机和方式很讲究。压缩太早可能丢掉后面还需要的信息压缩太晚上下文已经爆了。我的经验是当上下文使用量达到窗口的60%到70%时就开始考虑压缩。压缩时把最早的几轮对话合并成一段摘要摘要里保留任务目标、关键决策、已确认的参数去掉寒暄和无关细节。摘要可以由模型生成但要给明确的指令比如“用三句话总结以下对话中与当前任务相关的关键信息保留所有已确认的参数和决策”。生成后最好人工检查一下确保没有丢关键信息。在自动化流程里可以加一个校验步骤检查摘要里是否包含了状态对象里的关键字段。提示压缩后的摘要要放在上下文的靠前位置而不是中间这样模型更容易注意到。4. 状态持久化Agent“失忆”的工程根源4.1 内存态与持久态的取舍很多Agent项目在Demo阶段状态是存在内存里的——一个字典、一个变量进程活着状态就在进程重启状态就没了。这在单次会话里没问题但真实场景下用户可能中途离开再回来服务可能重启多实例部署时请求可能打到不同机器上。这时候内存态就不够用了。状态持久化要解决的问题就是让Agent的状态在进程之外也能存活。常见的方案有几种存数据库关系型或KV都行、存Redis、存文件。选哪种取决于你的场景。如果状态数据量小、读写频繁、对一致性要求不高Redis很合适。如果状态需要长期保存、需要查询和分析数据库更合适。如果只是单机部署、状态简单文件也能凑合。但不管选哪种核心原则是状态要能序列化和反序列化且反序列化后Agent能恢复到之前的状态。这里有个容易踩的坑状态对象里如果存了不可序列化的东西比如数据库连接、文件句柄持久化就会失败。所以状态对象要设计得“干净”只存数据不存资源。4.2 会话恢复的完整流程会话恢复是状态持久化的直接价值。用户昨天聊到一半今天回来说“继续”Agent应该能接上。这个流程大概是这样的用户发起请求带上会话ID。服务端根据会话ID从存储里读取状态对象和对话摘要。把状态对象、摘要、最近几轮对话组装成上下文。模型基于这个上下文继续处理。处理完成后更新状态对象和对话历史写回存储。这个流程看起来简单但有几个细节要注意。会话ID的生成和传递要可靠不能丢。状态读取失败时要有降级方案比如当作新会话处理而不是直接报错。状态写入最好异步做不要阻塞用户响应。还有一个实际问题是状态的一致性。如果用户快速连发两条消息可能两个请求同时读取了旧状态然后各自更新后写入的覆盖了先写入的。解决办法是加锁或者用乐观并发控制比如给状态加版本号写入时检查版本号是否变化。4.3 多轮任务中的状态一致性对于多轮任务型Agent状态一致性尤其重要。比如一个订票Agent用户先选了航班再选座位最后支付。这三个步骤的状态必须连贯不能出现“选了座位但航班信息丢了”的情况。我的做法是把任务状态设计成一个状态机每个状态有明确的允许操作和转移条件。比如“已选航班”状态下允许的操作是“选座位”和“取消”“已选座位”状态下允许的操作是“支付”和“返回”。这样即使用户乱序操作Agent也能给出合理的响应而不是陷入混乱。状态机的定义可以写在代码里也可以写在配置里。写在配置里的好处是修改方便不用改代码。但不管写在哪里状态转移的逻辑要清晰且要有测试覆盖。5. 评估集没有度量就没有稳定5.1 为什么Agent项目需要专门的评估集普通的大模型应用评估相对简单给一批输入看输出质量。但Agent的评估复杂得多因为它涉及多步决策、工具调用、状态变化。一个任务可能走了五步前四步都对最后一步错了整体就是失败。如果只看最终输出你根本不知道问题出在哪一步。评估集的作用就是把这个复杂过程拆解成可度量的指标。一个好的Agent评估集应该包含任务描述、期望的工具调用序列、期望的最终结果、以及一些边界情况。有了这些你才能量化“这个Agent到底稳不稳”。我见过很多团队Agent做完了测试就是自己手动试几个case觉得“差不多能用”就上线了。结果用户一用各种奇怪的问题都冒出来。这不是因为团队不认真而是因为手动测试覆盖不了真实场景的多样性。评估集就是把这种“凭感觉”变成“看数据”。5.2 评估集的构建方法构建评估集我的经验是分三步走。第一步从真实场景里收集case。不要自己拍脑袋想测试用例而是去看用户实际会问什么。可以从客服记录、用户反馈、产品需求文档里提取。初期收集50到100个case就够用了关键是覆盖主要场景和常见边界。第二步给每个case标注期望行为。期望行为包括应该调用哪些工具、调用顺序是什么、关键参数是什么、最终输出应该包含什么信息。标注不用特别精确但关键点要标出来。比如一个查询类任务标注“应该调用搜索工具参数包含关键词最终输出应包含至少三条相关信息”。第三步定期更新和扩充。Agent上线后会遇到评估集里没有的新情况。把这些新情况补充进去评估集就越来越贴近真实。我一般建议每个月review一次评估集把线上发现的bad case加进去。5.3 关键评估指标与自动化Agent的评估指标我关注这几个指标含义目标任务完成率成功完成任务的case占比越高越好核心任务应90%工具调用准确率工具选择和参数正确的比例95%平均步数完成任务平均需要多少轮越少越好异常高说明有绕路错误恢复率出错后能自行恢复的比例80%上下文利用率关键信息在上下文中的保留情况关键信息不丢失这些指标可以自动化计算。任务完成率可以用规则判断也可以用模型判断让另一个模型看结果是否满足要求。工具调用准确率通过对比实际调用序列和期望序列来算。平均步数和错误恢复率从日志里统计。自动化评估的好处是每次改prompt、换模型、调工具都能快速跑一遍评估集看指标有没有下降。这比手动测试靠谱得多也是Agent项目从“能用”走向“稳定”的关键一步。5.4 用评估集驱动迭代评估集不只是用来“打分”的更重要的是用来驱动迭代。当某个指标下降时你可以去看具体是哪些case失败了失败在哪一步然后针对性地改。比如发现工具调用准确率下降去看失败的case可能是某个工具的描述不够清楚或者两个工具功能重叠导致模型混淆。改完描述后再跑评估集看指标有没有回升。这种“改-测-改”的循环是Agent项目稳定性的基本保障。我自己的习惯是每次发版前必须跑一遍完整评估集核心指标不能低于上一个版本。如果低于要么修到不低于要么有明确的理由说明为什么可以接受。这个纪律看起来简单但坚持下来能避免很多线上事故。6. 从“聪明”到“可靠”工程化落地的几个实操心得6.1 日志与可观测性排查问题的第一手资料Agent出问题时最怕的是“不知道发生了什么”。所以从第一天起就要把日志做扎实。我要求日志里必须记录每一轮的输入上下文可以脱敏、模型的原始输出、工具调用的参数和结果、状态对象的变化、以及每一步的耗时。这些日志在排查问题时价值巨大。比如用户反馈“Agent答非所问”你看日志发现模型在某一轮的工具调用返回了空结果但Agent没有处理这个空结果直接基于空结果继续推理最后给出了错误答案。有了日志这个问题五分钟就能定位没有日志可能查一天都查不出来。可观测性还包括监控。关键指标要实时监控比如任务完成率、平均响应时间、错误率。一旦指标异常能及时告警。Agent系统的不稳定性往往是渐进的早发现早处理比等用户投诉再查要好得多。6.2 灰度发布与回滚机制Agent的更新不管是改prompt、换模型、还是加工具都可能引入新的不稳定。所以不要一次性全量发布而是先灰度。比如先放10%的流量到新版本观察核心指标有没有异常。如果正常再逐步扩大比例如果有异常立即回滚。回滚机制要提前准备好。prompt和配置最好版本化管理回滚就是切回上一个版本。模型如果支持多版本也要能快速切换。工具的变化如果涉及代码要有快速回滚的部署流程。这个做法在传统软件工程里很常见但在Agent项目里往往被忽略。很多人觉得“改个prompt而已不用这么麻烦”。但实际经验告诉我prompt的改动对Agent行为的影响可能比换模型还大灰度发布是必要的保险。6.3 常见问题速查表最后整理一个常见问题速查表都是我在实际项目里踩过的坑现象可能原因排查方向解决思路同一问题答案不一致上下文组织不稳定、温度参数高检查上下文组装逻辑、温度设置固定上下文结构、降低温度工具调用参数错误工具描述不清、参数约束缺失看失败case的工具定义补充描述、加参数示例和校验多轮对话丢失关键信息状态管理缺失、上下文压缩过度检查状态对象和摘要显式维护状态、调整压缩策略响应越来越慢上下文膨胀、工具超时看token消耗和工具耗时压缩上下文、设工具超时任务中途卡住工具执行失败未处理、重试无上限看日志里的错误和重试记录加错误处理、设重试上限会话恢复后行为异常状态反序列化不完整检查状态对象的序列化确保状态可完整恢复这张表可以贴在工位上出问题时先对照排查能省不少时间。6.4 一个容易被忽视的点模型温度与随机性最后说一个细节模型温度。很多Agent项目为了“让回答更自然”把温度设得比较高。但温度高意味着随机性大同样的输入可能得到不同的工具调用决策。对于需要稳定性的Agent来说这是大忌。我的建议是Agent项目里温度尽量设低甚至设成0。工具调用、状态更新这些环节需要的是确定性不是创造性。如果某些环节确实需要一点灵活性比如生成给用户的回复可以单独设一个稍高的温度但核心决策链路要稳。这个调整看起来小但对稳定性的提升立竿见影。我试过把一个Agent的温度从0.7降到0.1任务完成率直接提升了十几个百分点。原因就是工具调用的决策不再随机摇摆了。做Agent项目这两年我最大的体会是让Agent“聪明”靠的是模型能力让Agent“可靠”靠的是工程能力。模型会越来越强但工程上的坑该踩的一个都不会少。工具调用、上下文、状态、评估这四个词看起来朴素但每一个都值得花时间打磨。把这几块做扎实了Agent才能从“演示惊艳”走到“上线放心”。
