1. 为什么你的Agent总是“演示惊艳上线翻车”做Agent项目的人大概率都经历过这种落差Demo里它像个全能助理能查资料、能调接口、能多轮追问甚至还能自己规划任务可一旦放到真实环境里跑用户稍微换个说法、多问两轮、或者某个工具返回慢了一点它就开始胡言乱语、重复调用、忘记目标甚至直接卡死。表面看是“模型不够聪明”实际上绝大多数问题根本不在模型本身而在工具调用、上下文管理、状态流转、评估体系这四个工程环节上。我过去一年参与过几个Agent项目的落地从客服工单自动处理到内部知识助手踩过的坑几乎都能归到同一类把Agent当成一个“更聪明的聊天机器人”来设计而不是当成一个“有状态、有边界、有失败恢复能力的执行系统”来设计。这两者的区别就像你拿一个会背菜谱的人去开餐厅和真正建一套能出餐、能退单、能补货的后厨系统完全是两码事。这篇文章不聊虚的就围绕一个核心问题展开Agent项目为什么经常“看起来很聪明用起来不稳定”我会从整体设计思路、核心细节、实操落地、问题排查四个层面把工具调用、上下文、状态管理、评估集这些关键点拆开讲清楚。适合正在做Agent开发、准备做Agent开发或者已经被Agent稳定性折磨过的朋友。读完你至少能明白你的Agent到底卡在哪一层以及怎么用工程手段把它从“玩具”变成“工具”。2. 整体设计与思路拆解Agent不是模型是系统2.1 先搞清楚Agent和普通LLM应用的本质区别普通LLM应用比如一个问答机器人它的核心链路很短用户输入 → 拼提示词 → 模型生成 → 返回结果。整个过程是无状态的一次请求结束上下文就丢了。这种模式简单、可控但能力上限也低因为它不能主动做事。Agent不一样。Agent的核心是**“感知-决策-行动-观察”的循环**。它需要根据当前目标决定下一步做什么调用什么工具拿到结果后再判断是否继续。这就引入了一个根本性变化Agent是有状态的而且状态会跨多轮、跨多个工具调用持续演化。我见过很多项目代码结构上就是把LLM调用包在一个while循环里然后塞几个工具函数进去就管这叫Agent。这种写法在Demo阶段能跑通因为Demo的路径短、输入干净、工具稳定。但真实环境里用户输入是模糊的工具返回是多样的网络是波动的模型输出是不确定的。四个不确定性叠加系统必然不稳定。所以第一个设计原则把Agent当成一个分布式系统来设计而不是一个函数调用链。分布式系统的核心问题它都有状态一致性、超时重试、幂等性、可观测性、失败隔离。你不在这些地方下功夫模型再强也救不了。2.2 工具调用为什么“能调”和“调得稳”是两回事工具调用是Agent最核心的能力也是最容易出问题的地方。很多开发者第一次接工具调用时觉得只要把函数描述写好、参数schema定义清楚模型就能正确调用。实际跑起来你会发现问题远不止“调不调得对”。常见的问题包括模型在不需要调用工具时强行调用调用时参数格式错误同一个工具被连续重复调用工具返回错误后模型不知道如何处理多个工具之间的依赖顺序混乱。这些问题背后其实是工具调用的边界定义和错误处理机制没有设计好。我的经验是工具调用要分三层来设计。第一层是工具描述层也就是给模型看的函数说明。这里的关键不是写得多详细而是写得多“无歧义”。比如一个查询订单的工具参数是订单号你就要明确告诉模型订单号必须是用户提供的如果用户没提供你应该先询问而不是自己编一个。第二层是调用约束层在代码层面限制模型的调用行为比如设置最大调用次数、禁止连续调用同一工具、对参数做前置校验。第三层是结果处理层工具返回后不是直接把原始结果丢给模型而是要先做结构化处理把错误信息、空结果、超时情况都转成模型能理解的格式。注意不要指望模型自己学会“什么时候不该调工具”。这个边界必须由代码来兜底。模型负责决策代码负责约束。2.3 上下文管理不是塞得越多越好而是留得越准越好上下文是Agent的“工作记忆”。很多项目不稳定根源就在上下文管理上。常见做法是把所有历史对话、所有工具返回结果、所有系统提示词一股脑塞进上下文窗口。短期看没问题因为现在模型上下文窗口越来越大动辄128K、200K甚至1M。但上下文越长模型注意力越分散关键信息越容易被淹没。我做过一个对比测试同一个多轮任务把完整历史塞进去和只保留最近三轮加关键摘要后者的任务成功率反而更高。原因很简单模型不是数据库它不擅长从大量冗余信息里精准提取当前需要的那一条。上下文管理的核心不是“记住所有”而是“在正确的时间让模型看到正确的信息”。具体怎么做我通常分三步。第一步分层存储把对话历史、工具调用记录、任务状态分开存不要混在一起。第二步动态裁剪根据当前任务阶段只把相关的历史片段注入上下文。比如用户正在确认订单信息那就只注入订单相关的历史之前的闲聊和无关查询全部裁掉。第三步关键信息摘要对长对话做滚动摘要把已经确认的事实、已达成的共识、未完成的任务用结构化格式保留下来而不是保留原始对话。这里有个容易忽略的点工具返回结果往往很长但模型真正需要的可能只是其中一两个字段。比如一个天气查询工具返回了完整JSON模型只需要温度和天气状况。如果你把整个JSON塞进上下文不仅浪费窗口还容易让模型在后续推理中被无关字段干扰。所以工具返回后最好先做一次“信息抽取”只把关键字段注入上下文。2.4 状态管理Agent的“记忆”到底该怎么管状态管理和上下文管理经常被混为一谈其实它们是两个层面的事。上下文是给模型看的状态是给系统用的。状态管理要解决的是当前任务进行到哪一步了哪些信息已经确认了哪些工具已经调用过了下一步应该做什么我见过最典型的翻车场景是用户在多轮对话中修改了某个条件比如一开始说“帮我查北京的天气”后来改口“算了查上海的”。如果状态管理没做好Agent可能还在用北京的信息继续执行或者两个城市的信息混在一起。这就是状态没有正确更新导致的。我的做法是引入一个显式的任务状态对象用结构化数据记录当前任务的关键信息。这个对象不直接塞给模型而是由代码维护在需要的时候把相关字段转成自然语言注入上下文。比如{ task_id: weather_query_001, status: in_progress, confirmed_slots: { city: 上海, date: 今天 }, pending_slots: [需要确认是否要查明天], tool_calls: [ {tool: weather_api, params: {city: 北京}, status: cancelled}, {tool: weather_api, params: {city: 上海}, status: success} ] }这样做的好处是状态变更由代码控制模型只负责在当前状态下做决策不负责记住所有历史。状态对象还可以持久化支持断点恢复这对长任务特别重要。2.5 评估集没有评估你根本不知道Agent哪里不稳这是最容易被忽视、但最重要的一环。很多团队做Agent开发阶段靠人工试上线后靠用户反馈中间没有系统化的评估。结果就是你知道它不稳定但不知道具体哪里不稳、什么条件下不稳、改了一个地方会不会引入新问题。评估集不是简单的“测试用例”它要覆盖Agent的完整行为空间。我通常把评估集分成四类正常路径、边界情况、异常恢复、多轮交互。正常路径就是标准流程验证基本功能。边界情况包括空输入、超长输入、模糊指代、多意图混合。异常恢复模拟工具超时、工具报错、模型输出格式错误等场景看Agent能不能正确降级或重试。多轮交互则专门测试状态流转和上下文管理比如用户中途改需求、连续追问、跨话题切换。评估指标也不能只看“最终答案对不对”。对于Agent过程指标往往更重要工具调用次数是否合理、无效调用占比多少、平均任务完成轮数、异常恢复成功率。这些指标能帮你定位到具体是哪个环节拖了后腿。提示评估集要持续迭代。每次线上发现新的失败案例就把它加进评估集形成回归测试。没有这个闭环你的Agent永远在“修一个坏一个”。3. 核心细节解析与实操要点3.1 工具调用的参数设计别让模型猜工具调用的稳定性从参数设计就开始了。很多开发者定义工具参数时习惯用自然语言描述比如“city: 城市名称”。这看起来没问题但模型可能会传入“北京市”、“北京”、“Beijing”、“帝都”等各种形式。如果你的工具后端没有做归一化就会直接报错。我的做法是在参数schema里用枚举或正则约束格式同时在工具描述里明确告诉模型“如果用户没有提供你应该先询问”。比如{ name: query_weather, description: 查询指定城市的天气。如果用户没有明确提供城市名称不要猜测先向用户确认。, parameters: { type: object, properties: { city: { type: string, description: 城市名称必须是中文标准名称例如北京、上海、广州 }, date: { type: string, enum: [today, tomorrow], description: 查询日期只支持今天或明天 } }, required: [city] } }这里的关键是required字段和描述里的约束语句。模型看到required就知道这个参数不能省看到“不要猜测先确认”就知道缺参数时应该追问而不是编造。另一个实操要点是工具返回格式的统一。不管底层API返回什么到了Agent这一层都应该转成统一的结构{ success: true, data: {...}, error: null, hint: 如果用户问的是温度直接使用data.temperature字段 }hint字段很有用它相当于给模型的“使用说明”告诉模型这个结果里哪些字段是关键的、怎么用。这能显著减少模型误读返回结果的情况。3.2 上下文裁剪的实操策略什么时候裁、裁什么上下文裁剪不是简单截断而是有策略地保留和丢弃。我通常按以下优先级来决定保留什么优先级内容类型保留策略最高系统提示词和工具定义始终保留但可以精简高当前任务状态摘要始终保留结构化注入高最近2-3轮对话完整保留中已确认的关键事实摘要保留中最近一次工具调用结果保留关键字段低早期对话历史摘要或丢弃低已完成的工具调用详情只保留状态标记具体操作时我会在每轮对话结束后做一次“上下文整理”把新产生的信息分类更新任务状态对象然后重新生成下一轮要注入的上下文。这个过程是代码驱动的不依赖模型自己判断。还有一个技巧是用“锚点”标记关键信息。比如在上下文里用[已确认]、[待确认]、[已取消]这样的标签帮助模型快速识别信息状态。这比让模型自己从对话历史里推断要可靠得多。3.3 状态机的引入让Agent的执行路径可预测如果你的Agent任务步骤比较多强烈建议引入显式状态机。状态机的好处是每个状态下的可用动作是有限的模型只需要在有限选项里做选择而不是自由发挥。这能大幅降低不确定性。比如一个订单处理Agent可以定义这些状态等待用户提供订单号→查询订单→确认订单信息→等待用户选择操作→执行操作→完成。每个状态下只允许调用特定的工具只允许输出特定类型的内容。模型的任务变成“在当前状态下选择正确的下一步”而不是“从零规划整个流程”。状态机的实现可以用代码硬编码也可以用配置驱动。我倾向于配置驱动把状态转移规则写成JSON或YAML这样调整流程时不用改代码。但要注意状态机不能太死板要留出“异常跳转”的口子比如用户突然问了一个无关问题Agent应该能暂时跳出主流程回答完再回来。3.4 评估集的构建方法从真实失败中学习评估集不是拍脑袋想出来的而是从真实场景中沉淀出来的。我的做法是项目初期先手动构造20-30个核心用例覆盖主要功能路径。上线后每次发现线上失败案例就把它脱敏后加入评估集。三个月后评估集自然会长到几百条覆盖各种边界情况。评估集的每条用例应该包含输入用户消息序列、预期行为应该调用什么工具、应该输出什么类型的结果、判定标准怎么算通过。判定标准要尽量自动化比如工具调用参数是否匹配、最终答案是否包含关键信息。对于难以自动判定的可以用另一个模型做裁判但裁判模型也需要定期校准。注意评估集要定期跑最好每次代码变更后都跑一遍。我见过太多团队改了一个提示词结果把之前修好的问题又改坏了就是因为没有回归测试。4. 实操过程与核心环节实现4.1 从零搭建一个稳定Agent的最小闭环假设我们要做一个“会议安排助手”能查日程、找空闲时间、创建会议。我按上面的思路走一遍完整流程。第一步定义任务状态对象。{ task_id: meeting_scheduler_001, status: collecting_info, slots: { participants: [], duration: null, preferred_date: null, meeting_title: null }, confirmed: false, tool_history: [] }第二步定义工具集。[ { name: check_calendar, description: 查询指定人员在指定日期的日程安排。如果日期未提供默认查询今天。, parameters: { person: {type: string, description: 人员姓名}, date: {type: string, description: 日期格式YYYY-MM-DD} }, required: [person] }, { name: create_meeting, description: 创建会议。只有在所有必填信息都确认后才能调用。, parameters: { title: {type: string}, participants: {type: array, items: {type: string}}, start_time: {type: string}, duration_minutes: {type: integer} }, required: [title, participants, start_time, duration_minutes] } ]第三步设计主循环。主循环的逻辑是读取当前状态 → 根据状态决定注入哪些上下文 → 调用模型 → 解析模型输出 → 如果是工具调用执行工具并更新状态 → 如果是文本回复返回给用户 → 循环直到任务完成或需要用户输入。关键点在于每次调用模型前都要重新生成上下文。不是把历史一股脑塞进去而是根据当前状态只注入相关字段。比如当前状态是collecting_info那就注入已收集的slots和缺失的slots让模型知道还差什么信息。第四步处理工具调用结果。工具返回后先做结构化处理提取关键字段更新状态对象然后生成一个简短的“观察结果”注入下一轮上下文。比如check_calendar返回了某人今天有三个会议那注入给模型的就是“张三今天10:00-11:00有会14:00-15:00有会其余时间空闲”而不是原始JSON。第五步设置终止条件。Agent不能无限循环。我通常设置三个终止条件任务完成、达到最大轮数比如10轮、连续两次工具调用失败。达到任一条件就退出循环返回当前状态给用户。4.2 参数计算与选择超时、重试、最大轮数怎么定这些参数没有标准答案但可以根据经验给一个起点然后根据评估结果调整。参数建议起点调整依据单次工具调用超时10秒根据工具后端P99延迟调整工具调用最大重试次数2次幂等工具可重试非幂等慎用Agent最大执行轮数10轮根据任务复杂度调整上下文最大token数模型窗口的60%留出余量给模型输出连续失败阈值2次连续失败后应降级或转人工超时设置特别重要。我见过一个项目工具调用没设超时结果某个外部API挂了Agent就一直等用户那边直接卡死。后来加了10秒超时和2次重试稳定性立刻上来了。重试要注意幂等性。查询类工具可以随便重试但创建订单、发送消息这类操作重试前必须确认上一次是否真的失败了否则可能重复创建。我的做法是给每个工具标记idempotent: true/false非幂等工具的重试要格外谨慎最好先查询状态再决定。4.3 实操现场一次典型的失败恢复过程说一个真实案例。用户让Agent帮忙“把下周的团队会议改到周五下午”。Agent先查了日历发现周五下午大家都有空然后准备创建会议。但创建时工具返回了“时间冲突”错误因为会议室被占了。如果没做错误处理Agent可能直接把错误信息丢给用户或者反复重试创建。我的处理方式是在工具返回错误后先解析错误类型。如果是“时间冲突”就自动触发一个“查找替代时间”的子流程查一下周五其他时间段或者下周一是否有空然后把选项呈现给用户。这个过程在状态机里体现为creating_meeting状态收到冲突错误 → 转移到finding_alternative状态 → 调用check_calendar查找替代时间 → 转移到presenting_options状态 → 输出选项给用户。整个恢复过程不需要用户重新描述需求Agent自己完成了降级和补偿。这就是状态管理和错误处理的价值。4.4 评估集的实际运行怎么跑、怎么看结果评估集跑起来很简单写一个脚本遍历所有用例对每个用例模拟用户输入序列记录Agent的实际行为然后和预期行为对比。输出一份报告包含通过率、失败用例详情、关键指标统计。我通常关注这几个指标任务完成率最终是否完成了用户目标工具调用准确率调用的工具和参数是否正确无效调用率有多少次工具调用是不必要的或重复的平均轮数完成任务平均需要几轮交互异常恢复率遇到工具错误时成功恢复的比例这些指标比单纯的“回答对不对”更能反映Agent的健康状况。比如无效调用率高说明工具描述或上下文有问题异常恢复率低说明错误处理逻辑不完善。5. 常见问题与排查技巧实录5.1 工具调用类问题速查问题现象可能原因排查方法解决思路模型不调用工具直接回答工具描述不清晰或模型不知道何时该调检查工具描述是否说明了触发条件在描述里明确“当用户询问X时必须调用此工具”调用参数格式错误参数schema约束不够查看模型实际传入的参数增加枚举、正则、示例重复调用同一工具上下文里没有标记已调用检查工具调用历史是否注入在上下文里加“已调用”标记工具报错后模型不知所措错误信息没有结构化查看错误返回格式统一错误格式加hint字段多工具依赖顺序混乱缺少状态机约束检查是否允许自由选择工具引入状态机限制每步可用工具5.2 上下文类问题速查问题现象可能原因排查方法解决思路模型忘记之前确认的信息上下文裁剪过度检查任务状态是否注入把已确认事实结构化注入模型被无关历史干扰上下文塞了太多无关内容检查注入的历史范围按相关性动态裁剪长对话后模型开始胡言乱语上下文超长注意力分散检查token数做滚动摘要控制长度工具返回结果被误读原始结果太复杂检查注入的返回内容先抽取关键字段再注入5.3 状态管理类问题速查问题现象可能原因排查方法解决思路用户改需求后Agent还用旧信息状态没有更新检查状态更新逻辑每次用户输入后重新解析并更新slots任务卡住不推进状态机没有出口检查状态转移条件增加超时和降级路径多轮后状态混乱状态对象没有持久化检查状态存储持久化状态支持恢复并发任务互相干扰状态没有隔离检查task_id隔离每个任务独立状态对象5.4 独家避坑技巧技巧一给模型“思考空间”但不要让它“自由发挥”。在提示词里加一个“当前状态”区块明确告诉模型现在处于哪个阶段、已有哪些信息、还缺什么。这比让模型自己从历史里推断要可靠得多。技巧二工具返回结果里加一个“建议下一步”字段。比如查询日历后返回结果里加一句“如果用户想创建会议请调用create_meeting工具”。这相当于给模型一个轻量级的引导能显著减少模型在下一步决策时的犹豫和错误。技巧三用“影子模式”上线。新Agent上线前先让它和人工并行跑一段时间。人工处理真实请求Agent在后台也处理同样的请求但不直接回复用户。对比两者的结果找出Agent的失败模式。这比直接上线然后被用户骂要稳妥得多。技巧四评估集里一定要有“对抗样本”。比如用户故意说反话、故意提供矛盾信息、故意在任务中途切换话题。这些在真实场景里很常见但开发时容易忽略。我通常会专门构造一批这样的用例专门测试Agent的鲁棒性。技巧五日志要记录“决策依据”。每次模型调用除了记录输入输出还要记录当前状态、注入的上下文摘要、模型选择的工具和参数。这样出问题时你能快速定位是上下文问题、状态问题还是模型本身的问题。没有这些日志排查基本靠猜。5.5 一个容易被忽视的细节工具调用的“副作用”管理有些工具是有副作用的比如创建会议、发送邮件、修改数据。这类工具一旦调用成功就不能简单重试。我的做法是对有副作用的工具调用前先记录“意图”调用后记录“结果”中间状态标记为“进行中”。如果调用超时或失败先查询实际状态确认是否已经生效再决定是否重试。这个逻辑在状态对象里体现为{ tool_calls: [ { tool: create_meeting, params: {...}, status: in_progress, intent_id: intent_001, result: null } ] }调用成功后更新为success失败后更新为failed超时后标记为unknown并触发状态查询。这样即使系统崩溃重启也能根据状态对象恢复执行不会重复创建会议。6. 把Agent从“聪明”做到“可靠”的关键认知做Agent项目最怕的就是把“模型能力”当成“系统能力”。模型再强它也只是一个组件不能替代工程上的状态管理、错误处理、边界约束和评估体系。我见过太多项目提示词写得天花乱坠工具接了几十个但一上真实环境就崩根本原因就是工程底座没打好。如果你正在做Agent或者准备做我的建议是先把状态管理和评估集做起来再考虑加更多工具和更复杂的规划能力。状态管理决定了Agent能不能“记住自己在干什么”评估集决定了你能不能“知道它哪里不行”。这两个东西没有后面加什么都是空中楼阁。另外不要追求“全自动”。很多场景下Agent只需要做“辅助决策”而不是“完全替代”。比如让它整理信息、给出建议、执行确认后的操作而不是让它从头到尾自己跑。人机协作的模式往往比全自动更稳定、更实用。最后分享一个我自己的习惯每次Agent出问题我都会问自己三个问题——是上下文没给对是状态没更新还是工具边界没定义好这三个问题能覆盖80%以上的稳定性问题。剩下的20%才轮到模型本身。