Agent项目稳定性困局：工具调用、上下文与状态管理的工程实践

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轮关键摘要当前任务相关片段后者的任务完成率反而更高。原因就是全量历史里混着大量已经过时的中间结论、被否定的方案、无关的寒暄这些都在干扰模型的判断。所以上下文管理的核心不是能装多少而是该装什么。我一般把上下文分成几层来管理层级内容保留策略系统层角色设定、工具定义、全局约束始终保留尽量精简任务层当前任务目标、已确认的关键事实结构化维护随任务更新对话层最近若干轮原始对话滑动窗口保留最近5-10轮摘要层更早历史的压缩摘要定期生成替换原始历史检索层按需召回的相关知识片段动态注入用完即弃这套分层不是拍脑袋来的而是对应了什么信息需要始终在场、什么信息可以压缩、什么信息按需加载三种不同的生命周期。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就能从演示惊艳走到线上可靠。这条路没有捷径但每一步都值得。