1. 演示很惊艳、上线就翻车：Agent项目的稳定性困局到底卡在哪

做Agent项目的人大概都经历过这种落差：内部演示时，模型规划得头头是道，工具调用一气呵成，多轮对话也能接得住，会议室里一片叫好；可真到了线上，用户随便换个说法、多问两轮、网络抖一下，整个流程就开始跑偏——要么工具参数拼错，要么把上一轮的结论当成事实继续往下推，要么干脆卡在某个循环里出不来。这种"看起来很聪明，用起来不稳定"的现象，几乎是每个Agent开发者都会撞上的墙。

我自己带过几个Agent项目，从早期的单工具问答，到后来的多工具编排、多Agent协作，踩过的坑基本能凑成一本小册子。回头看，问题的根子往往不在模型本身有多笨，而在于我们把一个概率系统当成了确定性系统来设计和交付。传统后端服务里，输入确定、逻辑确定、输出就确定；而Agent的每一层——意图理解、工具选择、参数生成、结果解读——都带着不确定性，这些不确定性还会沿着调用链层层放大。演示时你看到的是单次采样的最优表现，线上跑的是成千上万次采样的分布，两者根本不是一回事。

这篇文章想聊的就是这件事：为什么Agent项目容易"演示惊艳、上线翻车"，以及从工程角度怎么把它做稳。我会围绕工具调用、上下文管理、状态管理、评估集这几个关键词展开，把每个环节里最容易出问题的地方拆开讲，给出我自己验证过的做法和参数。适合已经动手写过Agent、或者正准备把Demo推向生产的同学，也适合想搞清楚"Agent工程到底难在哪"的初学者。全文不讲空泛的方法论，只讲能落地的东西。

2. 工具调用：Agent最像"聪明"的地方，也是最容易崩的地方

2.1 工具调用的本质是一次"结构化生成"，不是函数调用

很多人第一次写Agent，脑子里想的是"模型判断该调哪个函数，然后调用它"。这个心智模型是错的。真实发生的是：模型根据当前上下文，生成一段符合工具Schema的文本，框架再把这段文本解析成参数去执行。也就是说，工具调用本质上是受约束的文本生成，而不是编译器级别的函数调用。

这个区别决定了所有稳定性问题。函数调用里，参数类型错了编译器直接报错；而模型生成的参数，类型对了但语义可能完全错——比如用户说"帮我查下上周的订单"，模型可能生成start_date: "上周"这种字符串，而不是具体日期。它"看起来"完成了调用，实际执行必然失败。

所以第一件事：永远不要相信模型生成的参数是可直接执行的。我现在的习惯是，在工具执行层前面加一道参数校验与归一化，把模型输出的"意图参数"转成"执行参数"。这一步看起来多余，但它拦掉的线上故障能占到三成以上。

2.2 工具描述写得好不好，直接决定调用成功率

工具调用的准确率，很大程度上不取决于模型多强，而取决于工具描述（description）和参数Schema写得多清楚。我见过太多项目，工具描述就一句话"查询订单信息"，参数就一个query字符串，然后抱怨模型老是调错。这不是模型的问题，是你没给它足够的判断依据。

我的经验是，工具描述要包含四要素：

• 这个工具做什么：一句话说清能力边界，比如"根据订单号查询单个订单的详细状态，不支持按时间范围批量查询"。
• 什么时候用、什么时候不用：明确排除场景，比如"当用户询问的是退款进度时，请使用退款查询工具，不要用本工具"。
• 参数的含义和格式：每个参数都要写清楚类型、格式、示例，尤其是日期、枚举这类容易出错的。
• 返回值的结构：让模型知道调用后会拿到什么，方便它决定下一步。

下面是我常用的一个工具定义模板，用JSON Schema表达：

{ "name": "query_order_by_id", "description": "根据订单号查询单个订单的详细状态。仅用于已知订单号的精确查询；若用户只提供了时间范围或商品名，请先调用 search_orders 获取订单号。", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，格式为纯数字，长度16位，例如 2024051612345678" } }, "required": ["order_id"] } }

注意description里那句"若用户只提供了时间范围……请先调用 search_orders"，这就是在引导模型的决策路径。工具之间的调用顺序，很多时候不是靠框架硬编码，而是靠描述里的自然语言提示来约束的。

2.3 工具数量一多，选择准确率断崖式下跌

这是很多人忽略的一个规律：当可选工具从3个增加到15个，模型选对工具的概率会明显下降。原因很简单，工具描述之间会互相干扰，语义相近的工具尤其容易混淆。我实测过一个场景，8个工具时选择准确率还有九成，加到20个之后掉到七成出头。

应对办法有几个，我一般组合使用：

• 工具分组：按业务域把工具分成几组，先让模型选组，再在组内选具体工具。相当于把一次20选1拆成两次5选1，准确率能拉回来不少。
• 动态工具集：根据当前对话状态，只把相关的工具塞进上下文。比如用户还在确认身份阶段，就别把下单、退款工具暴露出来。
• 合并粗粒度工具：能合并的接口尽量合并。与其给模型get_user_name、get_user_phone、get_user_address三个工具，不如给一个get_user_profile返回完整信息，减少选择负担。

提示：工具数量控制在单次上下文里不超过10个，是我目前比较稳的经验值。超过这个数，就要考虑分组或动态裁剪了。

2.4 工具执行失败后的处理，才是稳定性的分水岭

演示时工具总是成功返回，线上却经常超时、报错、返回空。工具失败后的处理逻辑，才是Agent稳不稳的关键。我见过太多项目，工具一报错，整个Agent就抛出异常或者开始胡言乱语。

正确的做法是把工具执行结果——无论成功还是失败——都作为结构化观察结果回灌给模型，让它自己决定下一步。比如：

{ "status": "error", "error_type": "timeout", "message": "订单查询服务超时，请稍后重试或改用其他方式", "retryable": true }

模型看到retryable: true，可以选择重试；看到error_type: "not_found"，可以转而告诉用户没找到。关键是不要让异常直接冒泡到框架层，而是转成模型能理解的观察结果。同时要在框架层设置最大重试次数和总超时，防止模型陷入"失败-重试-失败"的死循环。我一般设单工具重试2次、整个任务总时长60秒封顶，超了就优雅降级。

3. 上下文：Agent的"记忆"越用越乱，问题出在无差别堆砌

3.1 上下文不是越长越好，噪声会淹没信号

大模型的上下文窗口越来越大，从早期的4K到现在的百万级，很多人就觉得"那就把所有历史都塞进去呗"。这是个危险的误区。上下文变长，信噪比会下降，模型在长上下文里定位关键信息的能力会衰减，而且成本和延迟都上去了。

我做过一个对比实验：同一个多轮任务，把完整历史全塞进去，和只保留"最近N轮+关键摘要+当前任务相关片段"，后者的任务完成率反而更高。原因就是全量历史里混着大量已经过时的中间结论、被否定的方案、无关的寒暄，这些都在干扰模型的判断。

所以上下文管理的核心不是"能装多少"，而是"该装什么"。我一般把上下文分成几层来管理：

这套分层不是拍脑袋来的，而是对应了"什么信息需要始终在场、什么信息可以压缩、什么信息按需加载"三种不同的生命周期。

3.2 对话状态管理：别让模型自己"记"，要用外部状态兜底

"对话状态管理"这个词听起来很工程，其实说的是一件很朴素的事：这轮对话进行到哪一步了、已经收集到哪些信息、还差什么。很多Agent项目把这件事完全交给模型，靠上下文里的历史让模型"自己记"，结果就是多轮之后状态漂移——用户明明已经提供了地址，模型又问一遍；或者用户改了需求，模型还按旧需求走。

我的做法是外部维护一份结构化的对话状态，每轮对话后更新，并在下一轮把它作为明确的上下文注入。比如：

{ "task": "预订会议室", "slots": { "date": "2024-05-20", "time_range": null, "room_capacity": 10, "equipment": ["projector"] }, "missing_slots": ["time_range"], "confirmed": false }

模型每轮看到这份状态，就知道"还差时间段没填"，会主动去问，而不是靠记忆猜。这份状态由框架根据模型的输出更新，模型只负责"从用户这句话里抽取了哪些槽位"，抽取结果经过校验后写入状态。这样即使模型某轮抽错了，状态层也能做校验和纠正，不会一路错下去。

注意：状态更新一定要做幂等和冲突检测。用户说"改成下午三点"，你要能识别这是对time_range的覆盖，而不是新增一个时间段。这类逻辑放在代码里做，比指望模型理解可靠得多。

3.3 上下文压缩：摘要不是随便让模型总结一段

当对话轮次变多，必须做压缩。但"让模型总结一下前面的对话"这种做法，往往会丢掉关键细节。我踩过的坑是：模型把"用户拒绝了A方案，选择了B方案"总结成了"用户讨论了方案选择"，结果后面Agent又去推荐A方案。

有效的压缩要保留决策和事实，丢弃过程。我一般用结构化的摘要模板，强制模型按固定字段输出：

• 已确认事实：用户明确提供的信息（订单号、地址、偏好等）。
• 已做决策：确定了什么方案、排除了什么选项。
• 未决问题：还没解决、需要继续跟进的点。
• 用户情绪/约束：比如"用户明确表示不想再收到推荐"。

这样压缩后的摘要信息密度高，且不会丢关键约束。摘要的触发时机我一般设在对话超过10轮或**上下文token超过窗口的60%**时，而不是等到快满了才压缩——留出余量给后续对话。

3.4 上下文污染：一个错误结论如何毁掉整场对话

有个隐蔽但致命的问题叫上下文污染：某一轮模型产生了一个错误结论，这个结论被写进上下文，后续所有推理都建立在这个错误基础上，越滚越偏。比如模型误判用户想退款，后面就一直在退款流程里打转，用户怎么解释都拉不回来。

防污染的关键是区分"模型推测"和"已确认事实"。我在状态里给每个字段标注来源和置信度，只有用户明确确认过的才标记为confirmed，模型推测的标记为inferred。当用户的新输入和inferred字段冲突时，直接以用户输入为准覆盖；和confirmed字段冲突时，触发一次确认。这样能有效阻断错误结论的传播。

4. 状态管理：Agent跑着跑着就"失忆"或"精神分裂"

4.1 无状态设计和有状态设计的取舍

Agent服务该不该有状态，是个架构层面的选择。纯无状态（每轮把完整上下文传进来）的好处是易扩展、易恢复，坏处是上下文传输成本高、状态一致性难保证。有状态（服务端维护会话）的好处是上下文管理集中，坏处是扩容和故障恢复复杂。

我的经验是折中：会话的权威状态存在外部存储（比如Redis或数据库），服务本身尽量无状态。每轮请求带上会话ID，服务从存储里加载状态、处理、再写回。这样既能集中管理状态，又能水平扩展。存储里存的是结构化状态和摘要，原始对话可以另存，按需加载。

4.2 长任务的检查点：让Agent能"断点续跑"

Agent执行长任务时，最怕中途失败要从头再来。比如一个需要调用五六个工具、耗时几分钟的任务，跑到第四步挂了，如果没做检查点，用户就得重新描述一遍需求。

我的做法是在每个关键步骤完成后写检查点，记录当前进度、已获得的中间结果、下一步计划。任务失败重启时，从最近的检查点恢复，而不是从头开始。检查点的粒度要权衡：太细写入频繁，太粗恢复代价大。我一般按"工具调用完成"为粒度，一次工具调用成功就落一次检查点。

def execute_step(state, step): result = call_tool(step.tool, step.params) state.completed_steps.append({ "step": step.name, "result": result, "timestamp": now() }) save_checkpoint(state.session_id, state) return result

这段伪代码的重点是save_checkpoint的位置——在工具执行成功之后、进入下一步之前。这样即使下一步崩溃，恢复时也不会重复执行已完成的工具（对于有副作用的工具，重复执行是灾难）。

4.3 并发与幂等：同一个会话被点了两次怎么办

线上环境里，用户重复点击、网络重试、消息队列重投，都会导致同一个请求被处理多次。如果Agent的操作有副作用（下单、发消息、扣款），重复执行就是事故。

解决办法是幂等键：每个用户请求带一个唯一ID，服务端处理前先查这个ID是否已处理过，处理过就直接返回上次结果。对于Agent这种多步骤流程，幂等要贯穿到每个工具调用——给每个工具调用也带上幂等键，确保即使流程重跑，副作用也只发生一次。

提示：幂等键的生成要包含会话ID、轮次、操作类型，避免不同操作的键碰撞。我一般用{session_id}:{turn_id}:{tool_name}的格式。

4.4 状态版本冲突：多端同时操作时的处理

如果Agent支持多端（比如用户在网页和App同时操作同一个会话），就会出现状态版本冲突。两个端各自基于旧状态做了修改，后写入的会覆盖先写入的。

处理方式是乐观锁：状态带一个版本号，更新时校验版本号是否匹配，不匹配就拒绝并让客户端重新加载。对于Agent场景，更实际的做法是串行化同一会话的请求，用会话级的锁保证同一时刻只有一个请求在处理。这样虽然牺牲了一点并发，但避免了状态错乱，对大多数Agent应用来说是划算的。

5. 评估集：没有它，你根本不知道Agent是变好了还是变坏了

5.1 为什么"感觉变好了"是最危险的判断

Agent项目最要命的一点是：改动的影响很难凭感觉判断。你调了个提示词，试了几个case觉得不错，就上线了，结果线上另一批case全崩了。因为Agent的行为是分布式的，你手测的那几个case根本代表不了整体。

所以评估集是Agent工程的必需品，不是可选项。没有评估集，你的每次迭代都是赌博。我现在的习惯是，项目一开始就同步搭评估集，哪怕只有几十条，也比没有强。

5.2 评估集怎么建：覆盖真实分布，而不是挑好做的

评估集最容易犯的错是只收集容易的、成功的case，结果评估分数虚高，线上照样翻车。好的评估集要覆盖：

• 正常路径：标准输入，验证基本功能。
• 边界情况：空输入、超长输入、特殊字符、多语言混杂。
• 对抗样本：故意误导、前后矛盾、诱导越权。
• 多轮场景：需要多轮才能完成的任务，验证状态管理。
• 失败恢复：工具报错、超时后的表现。

我一般从线上真实日志里采样构建评估集，按场景分层，保证每类都有足够样本。规模上，初期50-100条能覆盖主要场景，成熟后往500条以上扩。关键是持续更新——线上发现新的失败模式，就补进评估集，防止回归。

5.3 评估什么：结果对不够，过程也要对

Agent的评估不能只看最终答案对不对，还要看过程对不对。一个任务最终完成了，但中间调了三次错误的工具、绕了一大圈，这种"侥幸成功"在线上很容易变成失败。

我一般从几个维度评估：

这几个维度里，工具选择准确率和参数正确率是最能提前预警线上问题的。任务完成率往往滞后，等它掉下来，线上已经出事了。

5.4 自动化评估的坑：用模型评模型要小心

用大模型做自动评估（LLM-as-judge）很流行，但坑不少。最常见的是评估模型和被评估模型同源，导致它对自己的错误模式不敏感，评分偏高。还有就是评估标准模糊，同一个case两次评分不一致。

我的做法是：能用规则判定的绝不用模型。工具选择、参数正确性这些，直接和期望值比对，客观可靠。只有开放式生成的质量，才用模型评估，而且要给出明确的评分标准和示例，最好用和被评估模型不同的模型来评。评估结果要人工抽检，校准评估器的可靠性。

6. 把Agent做稳的几个工程习惯

6.1 给Agent加"护栏"：关键操作必须有人确认

再稳的Agent也会有出错的时候，所以高风险操作必须加人工确认。比如涉及支付、删除、对外发送的操作，Agent可以准备好参数，但执行前要用户确认。这不是不信任Agent，而是承认概率系统必然有长尾错误。

护栏的设计要分级：低风险操作（查询、读取）直接执行；中风险操作（修改、创建）执行后告知；高风险操作（删除、支付、对外发送）执行前确认。分级标准按业务定，但原则是"不可逆的操作要格外谨慎"。

6.2 可观测性：把Agent的每一步都记下来

Agent出问题时，最难的是定位是哪一步出的错。所以完整的链路追踪是必须的：每轮对话的输入、模型的原始输出、工具调用的参数和结果、状态的变更、耗时，全都要记下来。

我一般用结构化的日志，每个会话一个trace，每个步骤一个span，方便按会话回放整个执行过程。这样线上出问题，能快速定位是模型理解错了、工具返回异常、还是状态更新有bug。没有这套可观测性，排查Agent问题基本靠猜。

6.3 灰度与回滚：新版本先小流量验证

Agent的改动影响面大，绝不能全量直接上。新版本先放小流量（比如5%），对比新旧版本的关键指标（完成率、工具准确率、用户反馈），确认没有退化再逐步放量。同时要保证能快速回滚——提示词、工具定义、模型版本都要可配置、可切换，出问题几分钟内切回旧版本。

6.4 提示词和工具定义要版本化

提示词和工具定义是Agent的"代码"，必须纳入版本管理。每次改动记录改了什么、为什么改、评估结果如何。这样出问题能追溯，也能对比不同版本的效果。我见过太多项目，提示词改来改去，最后没人知道线上跑的是哪一版，出了问题无从查起。

7. 我在实际项目里踩出来的几条经验

最后分享几条我自己踩坑踩出来的体会，都是文档里不会写的。

第一条：演示要故意演示失败路径。内部演示时，别只演顺利的流程，主动演一下工具报错、用户改需求、多轮纠缠的场景。这既能暴露问题，也能让相关方对Agent的能力边界有合理预期，避免上线后落差太大。

第二条：评估集要当成资产来养。我现在的习惯是，每次线上发现一个bad case，第一件事就是把它加进评估集。日积月累，评估集就成了项目的"免疫系统"，新改动跑一遍，能挡掉大部分回归。

第三条：别追求一步到位的复杂架构。很多团队一上来就搞多Agent协作、复杂编排，结果稳定性一塌糊涂。我的建议是从单Agent、少工具、简单流程做起，把工具调用、上下文、状态、评估这四件事做扎实，再逐步加复杂度。稳比炫重要得多。

第四条：给模型"不确定"的出口。当模型不确定时，要允许它说"我不确定，需要确认"，而不是硬着头皮编一个答案。在提示词里明确告诉它，遇到信息不足时应该提问而不是猜测。这一条能显著降低幻觉带来的错误。

第五条：把用户当协作者，而不是旁观者。Agent不可能全知全能，让用户参与进来——确认关键信息、纠正错误理解、提供缺失上下文——反而能让整体体验更稳。好的Agent设计不是让用户感觉不到AI的存在，而是让用户知道什么时候该介入。

Agent项目的稳定性，说到底是个工程问题，不是模型问题。把工具调用做严谨、把上下文管清楚、把状态维护好、把评估集建起来，这四件事做到位，Agent就能从"演示惊艳"走到"线上可靠"。这条路没有捷径，但每一步都值得。