去年年中我所在的小组接到一个内部需求把每天堆积的客服工单从“人工分拣人工回复”变成“自动分类自动生成回复草稿”。当时市面上的 Agent 框架已经不少但看完文档反而更糊涂——框架只是把模型调用、工具调用、上下文管理打包好了真正决定一个 Agent 系统能不能落地的是你在动手之前有没有一套自己的方法论。这篇文章想把我在那次搭建 Agent 系统过程中的思路完整梳理出来先讲方法论再讲我理想中的 Agent 形态最后讲一次真实落地的全过程、踩过的坑、以及最后上线时被砍掉的那些“理想设计”。如果你也在纠结“Agent 系统到底该怎么搭”“为什么我的 Demo 能跑、一上真实场景就废”这篇文章应该能给你一些可以直接用的参考。它不是框架教程也不打算比较哪个产品更好用而是从一个写代码的人的角度把一件事情的完整思考链路摊开。1. Agent 系统和普通程序的区别先统一“Agent 到底是什么”1.1 它不是一个能聊天的接口而是一个会“闭环”的执行体很多人刚接触 Agent 时会觉得Agent 不就是把大模型接到业务系统里让它读数据、调接口、返回结果吗早期我也是这么想的直到我在第一个小 Demo 里发现一个现象同样一个问题模型这次能答对下次换个说法就答错同样一段日志模型有时候能自己定位问题有时候就卡在一步上反复重试。这个现象背后的本质是普通程序是“确定性”的同样的输入一定得到同样的输出而 Agent 系统是“概率性”的它的核心不是一次调用而是一个循环。模型输出的每一步都有一个概率分布它可能在规划时选错路径可能在调用工具时参数构造错误也可能对工具返回的结果产生误判。所以 Agent 系统的搭建方法论本质上不是“怎么写好一段 Prompt”而是“怎么设计一个让模型即使出错也能被纠正、被兜底、被观测的执行闭环”。我后来把 Agent 系统拆成三句话来理解感知Perception——拿到当前任务和上下文行动Action——决策并调用工具反思Reflection——观察行动结果判断是否完成没完成就进入下一轮。所有 Agent 框架无论说得多么复杂核心都是这个循环。方法论的第一件事就是确认你到底在搭一个“循环”而不是在写一个“链”。1.2 三个会把你带偏的常见误区我在团队内部讨论时发现最容易让项目跑偏的是下面这三种想法几乎每个做过 Agent 的人都能对号入座第一个误区是“把 Agent 当成 RAG 的加强版”。RAG 解决的是“让模型拿到私有知识”的问题而 Agent 解决的是“让系统具备执行能力”的问题。如果任务只是“根据知识库回答问题”用 RAG 就够了强上 Agent 只会增加延迟和不可控性。第二个误区是“模型越强Agent 越稳”。很多团队把希望全压在最新最强的模型上指望它自动完成一切。真实情况是再强的模型也会在工具调用上犯错而一套好的系统设计包括结构化输出、工具校验、人工审批节点可以让普通模型的稳定性接近强模型反过来说再强的模型也扛不住糟糕的系统设计。第三个误区是“Agent 就是要让模型自己做所有决策”。在真实业务里这并不是理想状态。理想状态是“模型做它擅长的系统和人来兜底它不擅长的”。哪些决策应该交给模型哪些决策应该由规则或人来控制这本来就是方法论的一部分。我一直认为先想清楚这些问题比先去选框架重要得多。因为框架能帮你省的是“工程实现的琐碎”而那些真正影响落地成效的“设计决策”框架一点忙都帮不上。2. 搭建 Agent 的方法论从模糊需求到稳定系统的四步拆解我在那次落地过程中把搭建方法总结成了四步每一步都有一个明确产出物。这个流程适合绝大多数“业务型 Agent”项目我这里用真实经历里的细节来说明每一步到底在做什么。2.1 第一步定义“完成”——先把模糊需求翻译成可验证标准任何 Agent 项目的第一步不是选模型也不是画架构图而是回答一个问题什么样的输出算“做好了”。如果你给不出验证标准后面所有迭代都会变成拍脑袋。以客服工单系统为例“自动回复工单”这个需求看起来很清楚但实际上它包含了太多模糊点工单需要分到什么类别回复到多详细算合格某些敏感类目是否允许自动回复还是必须转人工我当时的做法是把需求一层层拆成一份“验收清单”每一类都给出可量化指标验收清单示例 1. 工单分类准确率在测试集上达到 85% 以上人工复核标准 2. 回复草稿可用率有 70% 以上的草稿在不修改或只修改少量措辞后可直接发送 3. 敏感类目识别率涉及账号安全、投诉升级、法律类工单100% 转入人工 4. 单条工单处理时长从接收到产出草稿p95 小于 30 秒 5. 全流程人工介入率每 100 条工单人工介入不超过 40 条把“完成”定义清楚之后很多设计会自动浮现出来。比如第 3 条“敏感类目必须转人工”这条它的本质是给系统设置“不可为区域”这直接影响后续工具设计里的“风险分流节点”。没有这一步你搭出来的 Agent 只能算玩具因为它根本没法证明自己“干好了活”。2.2 第二步选定 Agent 形态——单智能体、多智能体还是编排模式定义好验收标准之后就要回答“用几个 Agent”的问题。这是一个特别容易被带偏的地方。行业里谈到 Agent 就喜欢讲“多智能体协作”好像 Agent 数量多了系统就更高级。但实际上真实落地中绝大多数业务场景更适合的是“单 Agent 多工具”的编排模式而不是一上来就拆好几个 Agent 互相传递消息。我当时做了一个简单的对比也建议你照着这个表格去思考自己的场景形态适用场景优点代价单 Agent 工具集任务链路清晰Agent 自主决定调用哪些工具实现简单、开销小、易于追踪单 Agent 的规划压力大复杂任务容易乱多 Agent 协作任务天然分角色如“研究员”和“写作员”每个 Agent 职责单一并发效率高通信成本高、上下文不一致、排错复杂、成本翻倍编排模式状态机/工作流主流程固定分支有限不依赖模型临场发挥最稳定完全可控成本最低扩展新场景时需要手工调整流程我最后的结论是对于客服工单这种“流程大体固定、只有少量分支”的场景用“编排模式 一个负责灵活分支的 Agent”是最优解。把 80% 的确定流程用代码写死只把 20% 需要临场判断的部分交给 Agent这一条的原则我会在后面落地部分再展开。2.3 第三步设计工具与边界——Agent 的能力半径由工具列表决定而不是由模型决定方法论里最关键、也最容易被忽略的一步是工具设计。很多人以为工具设计只是“把 API 包装一下传给模型”其实远远不止。Agent 的工具设计必须考虑三件事哪些能力暴露给模型、工具的参数如何约束、工具返回的结果如何被验证。“哪些能力暴露给模型”是一个明显的边界问题。你在设计工具时是在给 Agent 划定一个“能力半径”——它只能在这个半径内做事。比如客服工单场景里我暴露给 Agent 的工具只有查工单详情、查客户历史、查知识库文章、生成回复草稿。但我刻意没有暴露“修改订单状态”“直接发退款审批”这类高权限操作。原因很简单Agent 的边界不是“它能做什么”而是“你允许它做什么”能力半径越清晰失控风险越低。“工具参数的约束”同样重要。我在实践中的经验是不要相信模型能记住工具文档里的所有格式要求你必须把工具的参数设计成“强类型、少自由字段”。举个例子分类工具的参数就不是一个自由字符串而是一个枚举类型只允许取值“账号问题 / 退换货 / 投诉升级 / 咨询”。这样模型在构造参数时的自由度被压缩出错的概率也急剧下降。最后是工具返回的校验。这一步可参考的工程实践很多但我当时用的是最简单有效的一套每个工具返回都必须带上 status 字段成功返回业务数据失败返回错误码和可读信息。Agent 拿到失败结果后可以依据错误信息决定是重试还是换方案而不是对着一个 Exception 瞎猜。2.4 第四步评估与回滚——没有评估集就没有迭代权Agent 系统和其他系统最大的不同在于你没法保证一次改动会稳定提升效果。改一下 PromptA 类工单变好了B 类工单可能就崩了。所以方法论的最后一步是建立一个“回归测试集”每次修改必须在这一套测试集上跑一遍量化对比效果。我当时建的是一个 80 条工单的测试集覆盖固定分类、敏感类目、模糊表述、长文本、多问题混合等场景。每条测试都有一个“期望行为”标注有的要求正确分类有的要求触发转人工有的要求输出某个格式的草稿。每次改版后我都会跑出四个数字分类准确率、草稿可用率、敏感漏识别率、平均耗时。这四个数字有任何一项退步我都会回滚改动重新调整。这一套流程做下来虽然前期花了不少时间建测试集但后面每次迭代都变得非常快。你可以理解为方法论不是让系统“一次做对”而是让系统具备“持续变好且不倒退”的基础设施。没有评估集的 Agent 项目后期几乎一定会陷入“改一个错、出一个新错”的泥潭。3. 理想形态的 Agent 架构我心中一个“完整系统”应有的样子方法论解决的是“思考和决策”的问题架构则是把这些决策落到系统结构里。我在这次落地过程中画过一张理想中的 Agent 系统架构图虽然实际落地时砍掉了一部分但每个模块存在的理由、以及它们之间的协作关系我认为非常值得写下来说明。3.1 核心循环感知Plan—行动Act—观察Observe—反思Reflect任何 Agent 系统的核心引擎都是一个循环。我理想中的循环不是简单的“模型调工具、工具返回再调模型”而是显式地包含“反思”这一步。常见的 ReAct 模式解决了“边想边做”的问题但“做完了想想做得对不对”这个能力在很多框架中是被弱化的。以一次工单处理为例理想循环是这样的感知阶段系统先把工单文本、用户历史、必要的上下文信息组织成结构化的“任务输入”而不是直接把一大段文本丢给模型。规划阶段模型根据输入列出处理步骤比如“先判断工单分类再检索知识库最后生成回复草稿”。行动阶段调用第一步判断出的工具拿到结果。观察阶段把工具返回结果重新塞回上下文让模型看到行动产生了什么效果。反思阶段模型结合初始目标判断任务是否完成是否还需要补充信息或进行二次修改。这里最难的是“反思”的设计。很多实现里反思只是多了一行 Prompt“请检查你的回答是否正确”效果往往很差。我在理想架构里会为反思单独设置一个“目标对照清单”机制把初始任务拆成几个检查点要求模型逐一确认“是否完成”“完成依据是什么”“有没有遗漏信息”。这种结构化的反思比一句泛泛的“自我检查”可靠得多。3.2 记忆体系短期上下文与长期知识的分工在 Agent 系统里“记忆”要分成两类来看。一类是短期记忆即当前任务执行过程中产生的全部中间状态模型看到了什么、调用了哪个工具、得到了什么结果。这类记忆直接决定上下文是否完整同时也是后面做可观测性的基础。另一类是长期记忆即跨任务的业务知识和历史经验比如知识库文章、历史工单的处理记录、常见问题的标准答案。真正容易出问题的是短期记忆的增长。工具调用一多上下文很快就会膨胀模型开始在信息海洋里“淹没”。我理想中的方案是“上下文压缩”具体有三种手段同时使用每次工具调用之后只保留“摘要 关键字段”而不是把完整返回体塞进下一次调用历史多轮对话只保留最后 N 轮原文更早的部分用摘要替换涉及大量检索结果时先让模型做一轮“结果筛选”只挑出与当前任务最相关的 3 至 5 条继续处理。长期记忆部分我没有选择让我自己去搭建一套复杂的记忆向量库因为这完全取决于业务里沉淀了多少历史数据。对于客服场景现成的知识库检索比“让 Agent 自己记住历史”更实际。把知识检索当作一个普通的工具暴露给 Agent让它在需要的时候主动去查这比把所有知识塞进上下文里要经济得多。3.3 工具层与执行层的解耦一个容易忽略的架构原则在理想架构里Agent 的“决策逻辑”和“工具实现”必须是两个独立的层次。很多团队写 Agent 时会犯一个错误为了尽快跑通把业务判断逻辑直接写死在工具函数里。比如工具“生成回复草稿”内部不仅调了模型还把“敏感词过滤”“渠道判断”全写在了一起。短期看是省事长期看就是灾难。正确的解耦方式是工具层只做“纯净的数据读写和动作执行”不包含任何模型决策。例如查工单详情只负责按工单 ID 拉数据并格式化返回查知识库只负责检索并返回候选文章列表生成草稿只负责调模型并且只接收“分类结果、相关资料、客户诉求”这些结构化输入不负责判断要不要生成所有的“判断、分流、选择”都放到 Agent 的决策逻辑里去由 Prompt 或编排节点控制。这样做的最大好处是可替换性你今天用 A 模型明天换成 B 模型工具层完全不用动反过来如果某个 API 变了你只需要改工具层决策逻辑依然不受影响。3.4 可观测性与人机协同介入点最后理想形态必须包含两块大多数 Demo 项目完全忽略的东西可观测性和人工介入点。Agent 系统一旦进入生产环境没人敢让它在黑盒里自动执行。每一个 Agent 动作最好都被记录成一条“轨迹”内容包括决策理由、工具调用参数、返回结果、中间耗时。这个轨迹不仅用于排错更是以后迭代优化的“数据燃料”。人机协同的介入点同样要在架构里被设计成一个“显式节点”而不是临时加逻辑。引入哪些位置可以介入我归纳了四个典型位置工具调用前高风险操作先暂停等人工确认再执行任务规划后让用户选择是否采用这套规划输出生成后自动回复类任务在发送前由人工审批异常路径中Agent 连续重试失败后自动转人工在理想架构里这几个介入点不是散落的 if 判断而是标准化的“检查点机制”。每到一个检查点系统询问“是否放行”放行逻辑可以来自规则、人工操作或降级策略。这个概念极大提升了系统的可控性也是它最终能上线的一个关键条件。4. 一次真实落地某客服工单处理 Agent 的从零到一理论部分写了不少下面进入具体的落地记录。这个项目是对一次真实工作的复述细节做了脱敏但流程、问题、数值都是当时的真实情况。希望通过这一部分你能看到“方法论”和“理想形态”在现实压力下最终被剪裁成了什么样子。4.1 场景与约束为什么要选这个业务做突破口我们当时的选择标准有两条一是业务痛点足够痛二是系统边界足够清晰。客服工单处理完全符合。每天几百条工单人工逐一分类和回复耗时高、标准不统一管理层早就想自动化而工单系统的数据边界、类目体系又非常清楚适合让 Agent 介入。同时还有三个硬约束直接决定了方案的设计方向第一绝对不能出现“客户投诉没人理却自动回复了错误内容”的事故所以所有对外发送内容必须经人工确认。第二系统要在现有工单系统外面作为辅助层不能改动老系统的核心逻辑。第三订单信息、账户信息等属于敏感数据Agent 在运行过程中不能留存额外副本。第三个约束后来导致了我在理想架构里规划的“长期记忆模块”被整体砍掉后面会细说。4.2 从第一版到第四版我到底是怎么迭代的第一版很粗糙就是一个“调大模型生成回复”的脚本。我拿到工单文本拼一段 Prompt让模型分类并生成回信然后输出结果。跑完测试集一看分类准确率大约 60%草稿可用率不到 40%而且模型经常在分类时自己创造类目比如把“咨询退货流程”归类为“客户不满”。这一版其实算不上 Agent因为没有任何工具调用但从它身上我验证了一个事实光靠模型“脑子里的知识”处理业务远不够用。第二版开始引入工具。我写了三个工具查工单详情、查客户历史、查知识库。Agent 的执行逻辑是先调用“查工单详情”拿到完整结构化工单再决定是否查客户历史然后查知识库找标准回复素材最后才生成草稿。这一版的提升非常明显分类准确率从 60% 提高到 80%草稿可用率也到了 55%。但问题也很突出模型经常在一次工单处理中调用 5 到 6 次工具大部分是无效调用导致单条处理时常飙到 90 秒远超 30 秒的目标。第三版的核心工作是“给 Agent 的探索欲降温”。我在规划阶段加了硬性约束每一步只允许调用一个工具且调用前必须说明“为什么需要这个工具、预计获得什么信息”。这个约束本质上是在让模型“先想清楚再动手”。同时我还给工具列表做了精简把原先 8 个工具砍成 5 个砍掉的标准是“这个工具提供的信息是否对草稿生成有直接影响”。第三版的结果是分类准确率 84%草稿可用率 63%平均耗时降到 26 秒。整体可用了但离“理想状态”还有一个痛点在折磨我就是幻觉问题模型会在回复草稿里编造订单号、编造物流时间。第四版解决了幻觉核心手段是“结构化约束 校验”。我规定草稿生成工具的输出必须是一个 JSON包含两个字段content回复内容和 references引用的事实来源。content 里涉及的任何订单号、金额、时间都必须从 references 里选而 references 的数据必须来自工具返回不允许模型自己发明。另外我还加了一条系统检查规则如果草稿里出现数字且没有对应引用来源自动判定为“不可用草稿”触发重新生成。第四版跑出来的数据是分类准确率 88%草稿可用率 71%敏感类目漏识别率 0%平均耗时 23 秒。这个结果终于越过了验收线。4.3 踩坑现场幻觉、死循环与上下文爆炸这节专门讲讲前面提到的三个典型问题因为它的排查链路比结果更有参考价值。第一个坑是幻觉。现象其实很隐蔽从草稿表面看句子通顺、语气得体但里面出现的“已为您安排优先发货预计明日送达”是完全没有依据的。第一次排查时我一度怀疑是 Prompt 写得不够强于是花了两天时间优化提示词加了无数句“请务必基于事实回答”结果改善微乎其微。后来我意识到问题根本不在语义层而在数据层模型在生成时根本没有“引用来源”的概念。解决方式就是第四版那套结构化输出加校验的方案不是靠“禁止幻觉”的咒语而是通过机制让“无源信息”无法通过校验。第二个坑是死循环。有一次我观察到某个工单在调用知识库时反复报错Agent 就一直重试同一个工具连续调了 12 次。排查后发现工具代码在某个分支里返回了无法解析的异常信息而 Agent 的决策逻辑写的是“遇到工具失败就重试”它又没有区分“可重试错误”和“不可重试错误”。修复方式是在工具返回结构里增加 retryable 字段标记是否值得重试同时在编排层加了一个最大步数限制任何一条工单最多执行 8 步超出后强制转人工。这一步是后面上线时最重要的稳定性保障之一。第三个坑是上下文爆炸。长工单加上多轮工具调用之后上下文里堆积了大量无关内容模型开始答非所问。我最初的解决办法是删减工单的“详情记录”但效果不好。后来换成了“分阶段摘要”的处理策略每次工具返回后都执行一次“信息压缩”只保留当前任务需要的关键信息压缩后的文本再参与下一轮调用。举个例子查客户历史接口返回了 30 条订单记录我不会把这 30 条全给模型而是让模型先挑选与本次工单相关的 2 至 3 条再参与草稿生成。上下文小了注意力更集中效果反而上升。如果你也在被这三个问题折磨我的建议是不要只改 Prompt要去检查你的工具返回结构、上下文管理策略和错误重试机制。这三个层面的系统化修复远比调整措辞有效。4.4 上线后的真实运行形态被“砍”出来的可行性最终上线的系统形态和我在第 3 节描述的理想形态比被砍掉了两块也保留了一块非常重要的东西。被砍掉的第一块是“长期记忆向量库”。原因很简单业务数据不能外传也没有适合的向量化存储环境更重要的是我们很快发现这个场景里知识库检索已经能覆盖 90% 的“记忆”需求额外的长期记忆模块性价比太低。被砍掉的第二块是“多智能体协作”团队最初设想过“一个负责分类的判断 Agent 一个负责回复的写作 Agent”但实践中发现单 Agent 状态管理明显更简单两个 Agent 只是在传递一个字符串却徒增了系统复杂度。被完全保留下来的是“人工审批节点”和“轨迹记录”。每次自动生成的草稿在发送前必须由人工在界面上确认可以选择直接发送、修改后发送、或者转人工重写。结果上线三个月后人工确认的平均耗时从原来完全人工处理的 8 分钟降到了 1 分半而每一封经确认发送的邮件其 Agent 决策轨迹都可以在后台完整回放。这成了整个项目最受认可的两个能力。5. 理想与现实的差距复盘后我想通的事项目上线之后我花了一周时间做复盘。最想说的不是“我们做成了”而是理想架构和真实落地之间的差距这些差距背后其实是几条更通用的原则。5.1 被剪掉的不一定是“不重要的”只是“当前代价大于收益”复盘时我重新审视了被砍掉的长期记忆模块。它真的没用吗也不是。如果未来系统要处理的是“同一客户连续多次反馈需要理解长期诉求”那长期记忆就是刚需。但在当时的场景和约束下搭建一个合规、可维护、效果稳定的记忆模块成本远超它带来的收益。Agent 系统设计和别的系统设计有一个共性任何模块引入之前都要问一句“它能代替哪个已有环节的成本还是只是新增了一个环节”。新增模块如果没有降低整体成本它就是在给系统增加复杂度。5.2 落地过程中真正发挥价值的往往是那些“不够 AI”的设计复盘时我也总结了一个有点反直觉的体会这个项目里发挥最大作用的不是某个聪明的 Agent 算法而是那些看起来“不够 AI”的工程手段结构化的工具返回格式status、data、error、retryable 四个字段最大步数限制与强制转人工输出 JSON 化加引用来源校验每条工单的轨迹日志这几项没有一个依赖模型能力它们全是传统的、可靠的软件工程手段。但它们让“模型那部分概率性能力”变得可控、可验证、可回退。我后来和别人交流时一直强调一个观点Agent 废品的比例未必比传统代码高真正的难点在于传统代码出错你能精准定位Agent 出错却需要你从一段模糊的轨迹里还原“模型当时是怎么想的”。如果没有上面这些工程垫层你连还原的依据都没有。5.3 给后来者的建议如果重来一次我会从哪几件事开始最后聊点实用的。如果让我再来一次面对一个全新的 Agent 项目我会按下面这五件事推进顺序基本不许乱先写“验收清单”把“完成”的定义量化越具体越好根据验收清单画出系统的“可介入点”确定哪些环节需要人工兜底用一个最简单的小脚本跑通“模型产生第一版输出”的流程尽快暴露问题从第一版暴露出的问题反推“需要哪些工具”“工具需要什么返回结构”在真实评估集上跑分而不是凭感觉看几条例子就判断效果还有一个细节我想多说一句Agent 项目的测试集维护一定要从第一天就开始。它不是上线前才补的东西而是伴随整个迭代过程一直在长的东西。每当你发现一个真实场景里系统出错的新模式就要立刻把它对应的工单加入测试集。这个动作坚持下来你的 Agent 系统会越用越稳因为你每天都在给它的“回归防线”添砖加瓦。说实话搭建 Agent 系统的过程给我最大的感受是新技术并没有让软件工程的基本原则失效反而让它们变得更加重要。你仍然需要关注数据结构、关注错误处理、关注可观测性、关注人的介入点。Agent 能带来的是自动化和灵活性但真正能让它稳定跑在生产环境里的依然是那些最可靠、最朴素的工程习惯。最后分享一个我做项目时一直保留的小习惯每天迭代结束时把当天崩过的 case 截出来配上“为什么会崩、准备怎么修、下次怎么防”三行注释存到一个草稿文件夹里。一个月后回看这个文件夹你能看到这个 Agent 系统是怎么一步步变靠谱的。这个过程比最终结果更能帮你理解“Agent 系统到底应该怎么搭”。
去年年中我所在的小组接到一个内部需求把每天堆积的客服工单从“人工分拣人工回复”变成“自动分类自动生成回复草稿”。当时市面上的 Agent 框架已经不少但看完文档反而更糊涂——框架只是把模型调用、工具调用、上下文管理打包好了真正决定一个 Agent 系统能不能落地的是你在动手之前有没有一套自己的方法论。这篇文章想把我在那次搭建 Agent 系统过程中的思路完整梳理出来先讲方法论再讲我理想中的 Agent 形态最后讲一次真实落地的全过程、踩过的坑、以及最后上线时被砍掉的那些“理想设计”。如果你也在纠结“Agent 系统到底该怎么搭”“为什么我的 Demo 能跑、一上真实场景就废”这篇文章应该能给你一些可以直接用的参考。它不是框架教程也不打算比较哪个产品更好用而是从一个写代码的人的角度把一件事情的完整思考链路摊开。1. Agent 系统和普通程序的区别先统一“Agent 到底是什么”1.1 它不是一个能聊天的接口而是一个会“闭环”的执行体很多人刚接触 Agent 时会觉得Agent 不就是把大模型接到业务系统里让它读数据、调接口、返回结果吗早期我也是这么想的直到我在第一个小 Demo 里发现一个现象同样一个问题模型这次能答对下次换个说法就答错同样一段日志模型有时候能自己定位问题有时候就卡在一步上反复重试。这个现象背后的本质是普通程序是“确定性”的同样的输入一定得到同样的输出而 Agent 系统是“概率性”的它的核心不是一次调用而是一个循环。模型输出的每一步都有一个概率分布它可能在规划时选错路径可能在调用工具时参数构造错误也可能对工具返回的结果产生误判。所以 Agent 系统的搭建方法论本质上不是“怎么写好一段 Prompt”而是“怎么设计一个让模型即使出错也能被纠正、被兜底、被观测的执行闭环”。我后来把 Agent 系统拆成三句话来理解感知Perception——拿到当前任务和上下文行动Action——决策并调用工具反思Reflection——观察行动结果判断是否完成没完成就进入下一轮。所有 Agent 框架无论说得多么复杂核心都是这个循环。方法论的第一件事就是确认你到底在搭一个“循环”而不是在写一个“链”。1.2 三个会把你带偏的常见误区我在团队内部讨论时发现最容易让项目跑偏的是下面这三种想法几乎每个做过 Agent 的人都能对号入座第一个误区是“把 Agent 当成 RAG 的加强版”。RAG 解决的是“让模型拿到私有知识”的问题而 Agent 解决的是“让系统具备执行能力”的问题。如果任务只是“根据知识库回答问题”用 RAG 就够了强上 Agent 只会增加延迟和不可控性。第二个误区是“模型越强Agent 越稳”。很多团队把希望全压在最新最强的模型上指望它自动完成一切。真实情况是再强的模型也会在工具调用上犯错而一套好的系统设计包括结构化输出、工具校验、人工审批节点可以让普通模型的稳定性接近强模型反过来说再强的模型也扛不住糟糕的系统设计。第三个误区是“Agent 就是要让模型自己做所有决策”。在真实业务里这并不是理想状态。理想状态是“模型做它擅长的系统和人来兜底它不擅长的”。哪些决策应该交给模型哪些决策应该由规则或人来控制这本来就是方法论的一部分。我一直认为先想清楚这些问题比先去选框架重要得多。因为框架能帮你省的是“工程实现的琐碎”而那些真正影响落地成效的“设计决策”框架一点忙都帮不上。2. 搭建 Agent 的方法论从模糊需求到稳定系统的四步拆解我在那次落地过程中把搭建方法总结成了四步每一步都有一个明确产出物。这个流程适合绝大多数“业务型 Agent”项目我这里用真实经历里的细节来说明每一步到底在做什么。2.1 第一步定义“完成”——先把模糊需求翻译成可验证标准任何 Agent 项目的第一步不是选模型也不是画架构图而是回答一个问题什么样的输出算“做好了”。如果你给不出验证标准后面所有迭代都会变成拍脑袋。以客服工单系统为例“自动回复工单”这个需求看起来很清楚但实际上它包含了太多模糊点工单需要分到什么类别回复到多详细算合格某些敏感类目是否允许自动回复还是必须转人工我当时的做法是把需求一层层拆成一份“验收清单”每一类都给出可量化指标验收清单示例 1. 工单分类准确率在测试集上达到 85% 以上人工复核标准 2. 回复草稿可用率有 70% 以上的草稿在不修改或只修改少量措辞后可直接发送 3. 敏感类目识别率涉及账号安全、投诉升级、法律类工单100% 转入人工 4. 单条工单处理时长从接收到产出草稿p95 小于 30 秒 5. 全流程人工介入率每 100 条工单人工介入不超过 40 条把“完成”定义清楚之后很多设计会自动浮现出来。比如第 3 条“敏感类目必须转人工”这条它的本质是给系统设置“不可为区域”这直接影响后续工具设计里的“风险分流节点”。没有这一步你搭出来的 Agent 只能算玩具因为它根本没法证明自己“干好了活”。2.2 第二步选定 Agent 形态——单智能体、多智能体还是编排模式定义好验收标准之后就要回答“用几个 Agent”的问题。这是一个特别容易被带偏的地方。行业里谈到 Agent 就喜欢讲“多智能体协作”好像 Agent 数量多了系统就更高级。但实际上真实落地中绝大多数业务场景更适合的是“单 Agent 多工具”的编排模式而不是一上来就拆好几个 Agent 互相传递消息。我当时做了一个简单的对比也建议你照着这个表格去思考自己的场景形态适用场景优点代价单 Agent 工具集任务链路清晰Agent 自主决定调用哪些工具实现简单、开销小、易于追踪单 Agent 的规划压力大复杂任务容易乱多 Agent 协作任务天然分角色如“研究员”和“写作员”每个 Agent 职责单一并发效率高通信成本高、上下文不一致、排错复杂、成本翻倍编排模式状态机/工作流主流程固定分支有限不依赖模型临场发挥最稳定完全可控成本最低扩展新场景时需要手工调整流程我最后的结论是对于客服工单这种“流程大体固定、只有少量分支”的场景用“编排模式 一个负责灵活分支的 Agent”是最优解。把 80% 的确定流程用代码写死只把 20% 需要临场判断的部分交给 Agent这一条的原则我会在后面落地部分再展开。2.3 第三步设计工具与边界——Agent 的能力半径由工具列表决定而不是由模型决定方法论里最关键、也最容易被忽略的一步是工具设计。很多人以为工具设计只是“把 API 包装一下传给模型”其实远远不止。Agent 的工具设计必须考虑三件事哪些能力暴露给模型、工具的参数如何约束、工具返回的结果如何被验证。“哪些能力暴露给模型”是一个明显的边界问题。你在设计工具时是在给 Agent 划定一个“能力半径”——它只能在这个半径内做事。比如客服工单场景里我暴露给 Agent 的工具只有查工单详情、查客户历史、查知识库文章、生成回复草稿。但我刻意没有暴露“修改订单状态”“直接发退款审批”这类高权限操作。原因很简单Agent 的边界不是“它能做什么”而是“你允许它做什么”能力半径越清晰失控风险越低。“工具参数的约束”同样重要。我在实践中的经验是不要相信模型能记住工具文档里的所有格式要求你必须把工具的参数设计成“强类型、少自由字段”。举个例子分类工具的参数就不是一个自由字符串而是一个枚举类型只允许取值“账号问题 / 退换货 / 投诉升级 / 咨询”。这样模型在构造参数时的自由度被压缩出错的概率也急剧下降。最后是工具返回的校验。这一步可参考的工程实践很多但我当时用的是最简单有效的一套每个工具返回都必须带上 status 字段成功返回业务数据失败返回错误码和可读信息。Agent 拿到失败结果后可以依据错误信息决定是重试还是换方案而不是对着一个 Exception 瞎猜。2.4 第四步评估与回滚——没有评估集就没有迭代权Agent 系统和其他系统最大的不同在于你没法保证一次改动会稳定提升效果。改一下 PromptA 类工单变好了B 类工单可能就崩了。所以方法论的最后一步是建立一个“回归测试集”每次修改必须在这一套测试集上跑一遍量化对比效果。我当时建的是一个 80 条工单的测试集覆盖固定分类、敏感类目、模糊表述、长文本、多问题混合等场景。每条测试都有一个“期望行为”标注有的要求正确分类有的要求触发转人工有的要求输出某个格式的草稿。每次改版后我都会跑出四个数字分类准确率、草稿可用率、敏感漏识别率、平均耗时。这四个数字有任何一项退步我都会回滚改动重新调整。这一套流程做下来虽然前期花了不少时间建测试集但后面每次迭代都变得非常快。你可以理解为方法论不是让系统“一次做对”而是让系统具备“持续变好且不倒退”的基础设施。没有评估集的 Agent 项目后期几乎一定会陷入“改一个错、出一个新错”的泥潭。3. 理想形态的 Agent 架构我心中一个“完整系统”应有的样子方法论解决的是“思考和决策”的问题架构则是把这些决策落到系统结构里。我在这次落地过程中画过一张理想中的 Agent 系统架构图虽然实际落地时砍掉了一部分但每个模块存在的理由、以及它们之间的协作关系我认为非常值得写下来说明。3.1 核心循环感知Plan—行动Act—观察Observe—反思Reflect任何 Agent 系统的核心引擎都是一个循环。我理想中的循环不是简单的“模型调工具、工具返回再调模型”而是显式地包含“反思”这一步。常见的 ReAct 模式解决了“边想边做”的问题但“做完了想想做得对不对”这个能力在很多框架中是被弱化的。以一次工单处理为例理想循环是这样的感知阶段系统先把工单文本、用户历史、必要的上下文信息组织成结构化的“任务输入”而不是直接把一大段文本丢给模型。规划阶段模型根据输入列出处理步骤比如“先判断工单分类再检索知识库最后生成回复草稿”。行动阶段调用第一步判断出的工具拿到结果。观察阶段把工具返回结果重新塞回上下文让模型看到行动产生了什么效果。反思阶段模型结合初始目标判断任务是否完成是否还需要补充信息或进行二次修改。这里最难的是“反思”的设计。很多实现里反思只是多了一行 Prompt“请检查你的回答是否正确”效果往往很差。我在理想架构里会为反思单独设置一个“目标对照清单”机制把初始任务拆成几个检查点要求模型逐一确认“是否完成”“完成依据是什么”“有没有遗漏信息”。这种结构化的反思比一句泛泛的“自我检查”可靠得多。3.2 记忆体系短期上下文与长期知识的分工在 Agent 系统里“记忆”要分成两类来看。一类是短期记忆即当前任务执行过程中产生的全部中间状态模型看到了什么、调用了哪个工具、得到了什么结果。这类记忆直接决定上下文是否完整同时也是后面做可观测性的基础。另一类是长期记忆即跨任务的业务知识和历史经验比如知识库文章、历史工单的处理记录、常见问题的标准答案。真正容易出问题的是短期记忆的增长。工具调用一多上下文很快就会膨胀模型开始在信息海洋里“淹没”。我理想中的方案是“上下文压缩”具体有三种手段同时使用每次工具调用之后只保留“摘要 关键字段”而不是把完整返回体塞进下一次调用历史多轮对话只保留最后 N 轮原文更早的部分用摘要替换涉及大量检索结果时先让模型做一轮“结果筛选”只挑出与当前任务最相关的 3 至 5 条继续处理。长期记忆部分我没有选择让我自己去搭建一套复杂的记忆向量库因为这完全取决于业务里沉淀了多少历史数据。对于客服场景现成的知识库检索比“让 Agent 自己记住历史”更实际。把知识检索当作一个普通的工具暴露给 Agent让它在需要的时候主动去查这比把所有知识塞进上下文里要经济得多。3.3 工具层与执行层的解耦一个容易忽略的架构原则在理想架构里Agent 的“决策逻辑”和“工具实现”必须是两个独立的层次。很多团队写 Agent 时会犯一个错误为了尽快跑通把业务判断逻辑直接写死在工具函数里。比如工具“生成回复草稿”内部不仅调了模型还把“敏感词过滤”“渠道判断”全写在了一起。短期看是省事长期看就是灾难。正确的解耦方式是工具层只做“纯净的数据读写和动作执行”不包含任何模型决策。例如查工单详情只负责按工单 ID 拉数据并格式化返回查知识库只负责检索并返回候选文章列表生成草稿只负责调模型并且只接收“分类结果、相关资料、客户诉求”这些结构化输入不负责判断要不要生成所有的“判断、分流、选择”都放到 Agent 的决策逻辑里去由 Prompt 或编排节点控制。这样做的最大好处是可替换性你今天用 A 模型明天换成 B 模型工具层完全不用动反过来如果某个 API 变了你只需要改工具层决策逻辑依然不受影响。3.4 可观测性与人机协同介入点最后理想形态必须包含两块大多数 Demo 项目完全忽略的东西可观测性和人工介入点。Agent 系统一旦进入生产环境没人敢让它在黑盒里自动执行。每一个 Agent 动作最好都被记录成一条“轨迹”内容包括决策理由、工具调用参数、返回结果、中间耗时。这个轨迹不仅用于排错更是以后迭代优化的“数据燃料”。人机协同的介入点同样要在架构里被设计成一个“显式节点”而不是临时加逻辑。引入哪些位置可以介入我归纳了四个典型位置工具调用前高风险操作先暂停等人工确认再执行任务规划后让用户选择是否采用这套规划输出生成后自动回复类任务在发送前由人工审批异常路径中Agent 连续重试失败后自动转人工在理想架构里这几个介入点不是散落的 if 判断而是标准化的“检查点机制”。每到一个检查点系统询问“是否放行”放行逻辑可以来自规则、人工操作或降级策略。这个概念极大提升了系统的可控性也是它最终能上线的一个关键条件。4. 一次真实落地某客服工单处理 Agent 的从零到一理论部分写了不少下面进入具体的落地记录。这个项目是对一次真实工作的复述细节做了脱敏但流程、问题、数值都是当时的真实情况。希望通过这一部分你能看到“方法论”和“理想形态”在现实压力下最终被剪裁成了什么样子。4.1 场景与约束为什么要选这个业务做突破口我们当时的选择标准有两条一是业务痛点足够痛二是系统边界足够清晰。客服工单处理完全符合。每天几百条工单人工逐一分类和回复耗时高、标准不统一管理层早就想自动化而工单系统的数据边界、类目体系又非常清楚适合让 Agent 介入。同时还有三个硬约束直接决定了方案的设计方向第一绝对不能出现“客户投诉没人理却自动回复了错误内容”的事故所以所有对外发送内容必须经人工确认。第二系统要在现有工单系统外面作为辅助层不能改动老系统的核心逻辑。第三订单信息、账户信息等属于敏感数据Agent 在运行过程中不能留存额外副本。第三个约束后来导致了我在理想架构里规划的“长期记忆模块”被整体砍掉后面会细说。4.2 从第一版到第四版我到底是怎么迭代的第一版很粗糙就是一个“调大模型生成回复”的脚本。我拿到工单文本拼一段 Prompt让模型分类并生成回信然后输出结果。跑完测试集一看分类准确率大约 60%草稿可用率不到 40%而且模型经常在分类时自己创造类目比如把“咨询退货流程”归类为“客户不满”。这一版其实算不上 Agent因为没有任何工具调用但从它身上我验证了一个事实光靠模型“脑子里的知识”处理业务远不够用。第二版开始引入工具。我写了三个工具查工单详情、查客户历史、查知识库。Agent 的执行逻辑是先调用“查工单详情”拿到完整结构化工单再决定是否查客户历史然后查知识库找标准回复素材最后才生成草稿。这一版的提升非常明显分类准确率从 60% 提高到 80%草稿可用率也到了 55%。但问题也很突出模型经常在一次工单处理中调用 5 到 6 次工具大部分是无效调用导致单条处理时常飙到 90 秒远超 30 秒的目标。第三版的核心工作是“给 Agent 的探索欲降温”。我在规划阶段加了硬性约束每一步只允许调用一个工具且调用前必须说明“为什么需要这个工具、预计获得什么信息”。这个约束本质上是在让模型“先想清楚再动手”。同时我还给工具列表做了精简把原先 8 个工具砍成 5 个砍掉的标准是“这个工具提供的信息是否对草稿生成有直接影响”。第三版的结果是分类准确率 84%草稿可用率 63%平均耗时降到 26 秒。整体可用了但离“理想状态”还有一个痛点在折磨我就是幻觉问题模型会在回复草稿里编造订单号、编造物流时间。第四版解决了幻觉核心手段是“结构化约束 校验”。我规定草稿生成工具的输出必须是一个 JSON包含两个字段content回复内容和 references引用的事实来源。content 里涉及的任何订单号、金额、时间都必须从 references 里选而 references 的数据必须来自工具返回不允许模型自己发明。另外我还加了一条系统检查规则如果草稿里出现数字且没有对应引用来源自动判定为“不可用草稿”触发重新生成。第四版跑出来的数据是分类准确率 88%草稿可用率 71%敏感类目漏识别率 0%平均耗时 23 秒。这个结果终于越过了验收线。4.3 踩坑现场幻觉、死循环与上下文爆炸这节专门讲讲前面提到的三个典型问题因为它的排查链路比结果更有参考价值。第一个坑是幻觉。现象其实很隐蔽从草稿表面看句子通顺、语气得体但里面出现的“已为您安排优先发货预计明日送达”是完全没有依据的。第一次排查时我一度怀疑是 Prompt 写得不够强于是花了两天时间优化提示词加了无数句“请务必基于事实回答”结果改善微乎其微。后来我意识到问题根本不在语义层而在数据层模型在生成时根本没有“引用来源”的概念。解决方式就是第四版那套结构化输出加校验的方案不是靠“禁止幻觉”的咒语而是通过机制让“无源信息”无法通过校验。第二个坑是死循环。有一次我观察到某个工单在调用知识库时反复报错Agent 就一直重试同一个工具连续调了 12 次。排查后发现工具代码在某个分支里返回了无法解析的异常信息而 Agent 的决策逻辑写的是“遇到工具失败就重试”它又没有区分“可重试错误”和“不可重试错误”。修复方式是在工具返回结构里增加 retryable 字段标记是否值得重试同时在编排层加了一个最大步数限制任何一条工单最多执行 8 步超出后强制转人工。这一步是后面上线时最重要的稳定性保障之一。第三个坑是上下文爆炸。长工单加上多轮工具调用之后上下文里堆积了大量无关内容模型开始答非所问。我最初的解决办法是删减工单的“详情记录”但效果不好。后来换成了“分阶段摘要”的处理策略每次工具返回后都执行一次“信息压缩”只保留当前任务需要的关键信息压缩后的文本再参与下一轮调用。举个例子查客户历史接口返回了 30 条订单记录我不会把这 30 条全给模型而是让模型先挑选与本次工单相关的 2 至 3 条再参与草稿生成。上下文小了注意力更集中效果反而上升。如果你也在被这三个问题折磨我的建议是不要只改 Prompt要去检查你的工具返回结构、上下文管理策略和错误重试机制。这三个层面的系统化修复远比调整措辞有效。4.4 上线后的真实运行形态被“砍”出来的可行性最终上线的系统形态和我在第 3 节描述的理想形态比被砍掉了两块也保留了一块非常重要的东西。被砍掉的第一块是“长期记忆向量库”。原因很简单业务数据不能外传也没有适合的向量化存储环境更重要的是我们很快发现这个场景里知识库检索已经能覆盖 90% 的“记忆”需求额外的长期记忆模块性价比太低。被砍掉的第二块是“多智能体协作”团队最初设想过“一个负责分类的判断 Agent 一个负责回复的写作 Agent”但实践中发现单 Agent 状态管理明显更简单两个 Agent 只是在传递一个字符串却徒增了系统复杂度。被完全保留下来的是“人工审批节点”和“轨迹记录”。每次自动生成的草稿在发送前必须由人工在界面上确认可以选择直接发送、修改后发送、或者转人工重写。结果上线三个月后人工确认的平均耗时从原来完全人工处理的 8 分钟降到了 1 分半而每一封经确认发送的邮件其 Agent 决策轨迹都可以在后台完整回放。这成了整个项目最受认可的两个能力。5. 理想与现实的差距复盘后我想通的事项目上线之后我花了一周时间做复盘。最想说的不是“我们做成了”而是理想架构和真实落地之间的差距这些差距背后其实是几条更通用的原则。5.1 被剪掉的不一定是“不重要的”只是“当前代价大于收益”复盘时我重新审视了被砍掉的长期记忆模块。它真的没用吗也不是。如果未来系统要处理的是“同一客户连续多次反馈需要理解长期诉求”那长期记忆就是刚需。但在当时的场景和约束下搭建一个合规、可维护、效果稳定的记忆模块成本远超它带来的收益。Agent 系统设计和别的系统设计有一个共性任何模块引入之前都要问一句“它能代替哪个已有环节的成本还是只是新增了一个环节”。新增模块如果没有降低整体成本它就是在给系统增加复杂度。5.2 落地过程中真正发挥价值的往往是那些“不够 AI”的设计复盘时我也总结了一个有点反直觉的体会这个项目里发挥最大作用的不是某个聪明的 Agent 算法而是那些看起来“不够 AI”的工程手段结构化的工具返回格式status、data、error、retryable 四个字段最大步数限制与强制转人工输出 JSON 化加引用来源校验每条工单的轨迹日志这几项没有一个依赖模型能力它们全是传统的、可靠的软件工程手段。但它们让“模型那部分概率性能力”变得可控、可验证、可回退。我后来和别人交流时一直强调一个观点Agent 废品的比例未必比传统代码高真正的难点在于传统代码出错你能精准定位Agent 出错却需要你从一段模糊的轨迹里还原“模型当时是怎么想的”。如果没有上面这些工程垫层你连还原的依据都没有。5.3 给后来者的建议如果重来一次我会从哪几件事开始最后聊点实用的。如果让我再来一次面对一个全新的 Agent 项目我会按下面这五件事推进顺序基本不许乱先写“验收清单”把“完成”的定义量化越具体越好根据验收清单画出系统的“可介入点”确定哪些环节需要人工兜底用一个最简单的小脚本跑通“模型产生第一版输出”的流程尽快暴露问题从第一版暴露出的问题反推“需要哪些工具”“工具需要什么返回结构”在真实评估集上跑分而不是凭感觉看几条例子就判断效果还有一个细节我想多说一句Agent 项目的测试集维护一定要从第一天就开始。它不是上线前才补的东西而是伴随整个迭代过程一直在长的东西。每当你发现一个真实场景里系统出错的新模式就要立刻把它对应的工单加入测试集。这个动作坚持下来你的 Agent 系统会越用越稳因为你每天都在给它的“回归防线”添砖加瓦。说实话搭建 Agent 系统的过程给我最大的感受是新技术并没有让软件工程的基本原则失效反而让它们变得更加重要。你仍然需要关注数据结构、关注错误处理、关注可观测性、关注人的介入点。Agent 能带来的是自动化和灵活性但真正能让它稳定跑在生产环境里的依然是那些最可靠、最朴素的工程习惯。最后分享一个我做项目时一直保留的小习惯每天迭代结束时把当天崩过的 case 截出来配上“为什么会崩、准备怎么修、下次怎么防”三行注释存到一个草稿文件夹里。一个月后回看这个文件夹你能看到这个 Agent 系统是怎么一步步变靠谱的。这个过程比最终结果更能帮你理解“Agent 系统到底应该怎么搭”。
