过去半年我一直在做一件事把一个看起来没啥问题的 LLM-Chat 聊天入口升级成一个支持多Agent协作的 Agent-Chat 入口。之所以用“升级”而不是“推翻重写”是因为一开始团队里不少人都觉得这事不大——聊天框嘛旁边加几个角色切换按钮、后台挂几个专属提示词不就行了真正动手以后才发现这压根不是按钮的问题而是整个入口层的定位、数据结构和交互协议都要跟着变。这篇内容就是把这次升级的完整思路和实践过程做个梳理从单模型闲聊到一个真正承担“调度中枢”职责的多Agent协作入口中间经历了什么设计取舍、踩了哪些工程坑、最后沉淀出哪些可复用的方案。适合正在做 AI 应用、想把聊天界面升级成 Agent 工作台的团队也适合刚接触多Agent架构、想搞清楚“入口层到底该长什么样”的开发者。全文以实际可落地为主不聊虚的概念。1. 升级之前LLM-Chat 的结构性瓶颈1.1 单模型对话入口到底哪里不够用先把问题说透。LLM-Chat 的本质是你有一个大厅大厅里只有一个“全能接待员”。这个接待员博学多才但有个天然限制同一时刻只有一副大脑、一套注意力、一个上下文窗口。用户提出需求它要么自己消化要么勉强调几个工具然后硬着头皮把所有事情做完。听起来好像也够用但你一旦把真实业务场景放进去问题就冒出来了。打个比方用户说“帮我查一下上周华东区的销售报表找出连续下滑超过 10% 的品类再分析一下可能的竞品原因最后把结论整理成邮件草稿。”这一句话里至少有四个环节查数、算指标、做归因分析、写邮件。如果都交给同一个全能助手它要在一轮上下文里反复切换工具、叠加多个判断逻辑中间任何一步出现工具调用错误后面的结果全都会跟着偏。而且上下文一旦长了模型很容易“忘”了最初的分析口径最后邮件草稿里的语气和前面的数据结论对不上。更深层的瓶颈是职责边界。一个 LLM-Chat 里塞进了数据分析、文案生成、日程管理、代码编写这些能力它缺乏“专业分工”的约束。数据分析应该走严谨的查询逻辑文案生成需要风格一致性日程管理牵扯到第三方权限。硬把它们放在同一个模型会话里意味着所有风险、权限、上下文污染都混在一起。出了问题你连是谁的锅都说不清更不要说针对某个角色去单独优化、单独测试。再说一个实际体验上的问题多轮复杂任务时用户根本看不到“过程”。传统聊天框只展示最终文本工具调用、中间计算、状态变化全部藏在后台。用户面对一个不断转圈圈的输入框只能干等。哪怕最后结果出来了用户也不知道它是怎么拿到的、中间用没用对表、哪一步消耗了大量 token。这种黑盒感在简单的问答场景还能忍到了“协作式工作场景”就完全不够了。1.2 多Agent协作入口的本质从“问答”转向“调度”升级的目标不是做一个界面更花哨的聊天框而是把它改造成一个“协作入口”。这里的关键认知转变是你不再是让一个万能模型回答用户的问题而是让一群各司其职的 Agent 共同完成一项任务。聊天界面退化成一种通用的交互协议真正的核心在它后面的编排层。我后来给团队讲这个概念时用得最多的类比是“饭店前台”和“厨房”的关系。LLM-Chat 相当于一个街头快餐摊老板一个人点单、炒菜、收钱忙得团团转。Agent-Chat 则是一家正经饭店前台负责接待、记录需求后厨分成凉菜、热菜、面点配菜间还有自己的备料流程。前台不需要知道每个菜怎么做它只要把单子准确传下去然后盯着出菜进度就行。如果把这个类比映射到系统设计上入口层其实就是那个“前台”——它负责接收用户意图、识别任务类型、把任务派发给对应角色再把结果汇总回来。它不负责具体执行不承载领域知识但它是整个多Agent系统的门面。用户看到的一切都是从入口进来的用户能被感知到的一切效率也都由入口决定。所以“Agent-Chat 的升级”真正要解决的问题是如何从“一个模型一把梭”的信息输入框变成一个“可路由、可编排、可观测、可干预”的协作控制台。围绕这个目标后面的所有设计才有落点。2. 多Agent协作入口的架构设计实战2.1 分层架构接入、编排、执行、存储确定了要往协作控制台的方向走之后第一件事是把代码结构和职责边界划分清楚。原来 LLM-Chat 的代码基本是“请求进来 → 拼提示词 → 调模型 → 输出文本”全挤在一个服务里。升级后我按四层来拆第一层是接入层负责处理用户消息的收发、会话建立、权限校验。它只做最基本的接口翻译不理解业务也不做路由判断。第二层是编排层也是这次升级的核心。它负责意图识别、任务分解、Agent 路由、进度跟踪。这一层相当于饭店前台的领班既要知道用户想要什么又得判断府上哪位师傅最合适。这一步的实现我放在下一节细讲。第三层是执行层由各个 Agent 组成。每个 Agent 有自己独立的角色设定、工具集合、记忆空间和执行逻辑。它们之间不直接互相调只通过编排层分配任务、回传结果。用“不直接调”这个原则很重要否则画着画着架构图Agent A 又开始直接调 Agent B 的私有工具边界就崩了。第四层是存储层包括会话记录、上下文快照、工具调用日志、状态数据。Agent-Chat 的数据量级比 LLM-Chat 大得多每个任务可能有多次工具调用、多轮中间状态没有独立的存储层后续做回放和审计会非常痛苦。这个分层看起来不复杂但实际操作中最大的阻力来自“历史代码惯性”。很多现成的业务逻辑已经写在了原来的对话处理函数里拆层的时候最容易犯的错是“只加新模块不拆旧逻辑”。结果新旧代码纠缠在一起编排层既要处理路由又背着旧业务的上下文清理。我的建议是升级期间干脆把旧链路整体打上“遗留模式”的标记新入口走独立的编排链路两边只共享底层存储和工具接口绝不共享控制流。过渡期丑一点没关系清晰最重要。2.2 任务分发的路由策略意图识别与规则兜底多Agent系统的路由策略是我起初想得最简单、实际做起来最折腾的部分。有人可能会说这不就是让大模型当路由器看完用户消息后输出一个要分发的 Agent 名称吗真这么简单就好了。模型当路由器有两个绕不过去的坑。第一是延迟问题你每来一条消息都要先让模型判断一次意图再走对应 Agent 的链路。两道模型推理叠加首字延迟直接翻倍。第二是稳定性问题模型的“路由判断”是概率性的用户随口说一句“那个、上次那个报告”它可能把本来该发给数据分析 Agent 的任务顺手分配给了文案助手然后整个任务的执行语境全错。我最终采用的是一种“规则优先模型兜底”的双层路由策略。规则层先跑一遍硬性匹配用户消息里包含明确的命令词、提到了特定的工具名、或者命中预设的正则和关键词表就直接走对应路由。这能覆盖大概 40% 的常见指令型请求速度快、零推理成本。剩下的模糊意图请求才进入模型路由并且模型路由只输出候选 Agent 列表和置信度不再直接终断。如果最高置信度低于某个阈值我这边设的是 0.6就转入一个“询问澄清”的状态由入口层反问用户而不是硬着头皮分发。除了路由还有一个特别容易忽略的细节路由结果要被记住。用户说“查一下上周的销售数据”路由到数据分析 Agent用户接着说“再把结论润色成汇报PPT”这条消息不能重新做全量路由而是要把意图附加上一条会话上下文——数据分析 Agent 的结果应当传递到文案汇报 Agent。这种上下文粘滞路由让我额外维护了一张“会话级路由状态表”记录当前活跃 Agent、已生成的中间产物引用ID、待流转的后续任务。没有这张表多Agent协作就会表现得像一群记忆只有七秒的临时工。3. 聊天界面与数据结构的升级改造3.1 消息不再是“文本”而是“事件流”这是我在升级过程中体会最深的一点。传统聊天界面消息就是两个字段角色和内容。但在 Agent-Chat 里这种模型彻底不够用。一个会话中用户发了消息系统在做路由判断Agent A 开始调用工具查数据工具返回中间结果Agent B 接手做分析然后修正了自己的想法最后给出结论——这条链路上每一步都是独立的消息片段而且它们之间有明确的依赖关系和状态属性。所以我把消息的数据模型从“纯文本”升级成了“事件流”。每一次变化都是一种事件类型用户消息、Agent 开始消息、工具调用发起、工具结果返回、Agent 中间思考、Agent 最终回复、系统通知、路由状态变化。每个事件都带一个全局递增的序号seq、一个会话 ID、一个事件类型、一个可选的事件块 ID用于把某一段工具调用链串在一起以及一个纯粹的 content 数组。这样做的好处是前端不需要猜测后端发生了什么。后端是什么状态前端就原样渲染什么状态。工具调用中前端可以展示一个可折叠的“运行中”状态块返回结果后还能展开看明细。用户不用再傻等一个转圈圈而是能看到“正在查询数据库”“正在生成图表”“正在汇总结论”。交互感知上的提升是立竿见影的。这段改造实际上还顺手解决了一个以前没注意的问题调度中途 Agent 出错时消息流里有完整的位置标记用户可以直接点击“从这条消息重新生成”而不需要把整个会话清空重来。这在传统的纯文本消息模型里几乎不可能实现。3.2 会话状态机与管理有了事件流之后下一步是把它变成更容易被程序理解的结构。多Agent协作会话本质上是一个异步过程原来 LLM-Chat 那种“请求-响应”同步模型完全无法支撑因为你不知道一个任务要流经多少个 Agent、触发多少次工具调用、中间要不要等待用户确认。我最终把每个会话定义成一个类似于“工作流实例”的东西显式维护状态机的流转。会话状态至少包含这几档初始化、路由中、等待工具结果、等待用户确认、执行完成、异常失败。不同状态之间允许转移并且只有有限几条合法路径。比如等待工具结果的会话可以转到执行完成也可以因为工具超时转到异常失败但绝不允许直接跳到等待用户确认——这是非法转移。实际产品中这套状态机还承担了“断线恢复”的功能。有一次测试环境出现节点重启用户浏览器端显示会话中断。重新连接后我把持久化的会话状态取出来发现它停在了“等待工具结果”上。系统没有傻乎乎地把整个任务重跑一遍而是先检查那个工具调用是否已超时再决定是续接还是重试。如果没有状态机这种场景只能让用户手动重新提交问题。我还在这套状态机上加了“用户干预”的入口允许用户在任何状态中止当前的链路直接给路由层发送一条“停止”指令。这对多Agent协作非常重要因为一旦任务被拆分下去执行链条往往很长用户很可能中途发现需求变了不能让系统犟着把原计划执行完。粒度上我做了两档软停止等当前工具返回后不再派发后续任务和硬停止立刻终止本轮 Agent 调用丢了就丢了。两档的代价完全不同硬停止会有一定的任务残留风险所以我把选择权明明白白交给了用户。3.3 上下文隔离与多Agent记忆管理多Agent系统里最复杂的不是路由是记忆和上下文。LLM-Chat 时期上下文就是一组会话历史一次性灌给模型Agent-Chat 不能让所有 Agent 都看到所有上下文——它们有的是涉密数据的有的是做日常写作的星罗棋布的角色共享一个超长上下文既不安全也没效率。我采用的方案是三层上下文模型。第一层是“会话公共摘要”包含用户的大致目标、已完成步骤、当前最重要的结论所有 Agent 在必要时都能读取。第二层是“Agent 私有上下文”只有被当前任务选中的 Agent 能读写里面保存它的角色设定、任务拆分结果、正在使用的工具参数。第三层是“临时执行上下文”专门给某一次工具调用或中间计算使用用完即清不进入任何历史记录。这个模型看着简单落地时最大的坑是“摘要漂移”。公共摘要是由另一个模型生成的它在概括时可能把关键的数字指标弄错或者漏掉某个用户特别强调的约束条件后面 Agent 拿到这个被污染的摘要整个结论就跑偏。为此我给公共摘要加了“原文溯源”每条摘要都附带对应的原文消息序号Agent 在不确定摘要信息时可以通过序号回查原始消息。这就避免了我看不见的模型在替我用“二手信息”做关键判断。4. 关键工程问题的解决记录4.1 并行调动冲突多Agent同时改同一份数据多Agent协作必然带来一个原本没有的工程问题并发。单模型时代你一次只处理一条消息根本不存在多个执行体同时去操作同一个数据源的问题。但多Agent架构下数据分析 Agent 可能正在查询某张表另一个报表生成 Agent 又在同一时间触发了一次写入操作。如果下面接的是一个普通的关系型数据库两边一撞轻则数据延迟重则脏读。我在实测中撞过一回事两个 Agent 同时读取了一个订单统计缓存各自基于旧缓存计算然后分别写回两份不同的汇总结果导致报表数据出现了一小时级的错乱。排查出来之后我在执行层做了三重约束。第一工具层做统一的“资源锁标记”所有写型工具在执行前必须先申请锁锁粒度精确到数据表或缓存键避免误伤并发读请求。第二编排层在同一会话内默认不派发两个有依赖冲突的任务并行执行而是把它们排成串行队列。第三所有写操作都改成“基于版本号的条件更新”更新时带上读取时的快照版本如果版本变化则丢弃当前结果并提示重新执行。这套组合拳也不复杂但它体现了一个思路多Agent系统不能把工具调用当成普通函数调用来对待。每次工具调用都可能是跨进程、跨数据源、跨时长的操作必须按“微服务之间通信”的标准来做安全设计。4.2 路由提示词与实际工具权限不匹配这个坑很隐蔽也很反直觉。重点在于Agent 的路由决策和工具权限矩阵是两套系统我却在一开始以为它们是一套东西。模型路由器判断用户意图时靠的是提示词里的描述但真正执行时Agent 能不能调用某个工具、能调哪个函数却由代码里的权限控制决定。典型翻车场景是路由提示词里写着“数据分析 Agent 可调用查询引擎和可视化工具”但权限配置文件里只给它的 API 密钥开了查询读权限可视化工具需要另一个密钥体系。结果模型愉快地把任务派发给数据分析 AgentAgent 一调可视化工具就返回 403整个链路从头崩到尾。这种行为在测试环境还不容易暴露因为测试环境里权限往往全开上到生产环境立刻现形。后续我把这套配置统一成了一个“能力注册中心”所有 Agent 的能力描述、可调用工具列表、API 权限范围全部集中在同一份注册信息里。编排层在路由完成之后除了把任务信息传给 Agent还会把当前可用的工具白名单也一起传递过去。Agent 侧接到任务时先做一次本地工具校验发现权限不匹配就立刻报一个结构化的“权限不足”错误而不是等到调接口时再爆一个裸 403。这样至少把错误信息变得可读、可定位。 这一套改下来生产环境的这类路由失败率直接下降了一个数量级而且排查问题时的信息完整度也好很多。4.3 可观测性看不见的 Agent 到底在忙什么多Agent系统对可观测性的要求远高于普通聊天机器人。普通聊天机器人出问题无外乎模型答得不准确多Agent系统出问题可能是路由错了、任务拆分错了、某个工具参数错了、某个 Agent 的上下文被污染了、甚至两个 Agent 之间衔接时信息丢失了。没有给力的追踪手段排查这些问题就像在黑屋子里找一只黑猫。我在系统里加了“全链路 Trace”的概念。每一次用户请求生成一个 traceID从入口层开始贯穿路由判断、任务拆分、每个 Agent 的执行、每次工具调用直至最终响应。所有中间步骤都打日志并且带上 traceID、事件类型、耗时、token 消耗。前端业务事件流展示给用户的只是界面层的信息后端排查时还有一份完整的多Agent执行轨迹可以回放。这个轨迹在调试时帮了大忙。有一次用户反馈某个分析结论明显不合理我把该请求的 traceID 找出来回放发现是路由阶段意图识别置信度只有 0.55但当时没触发澄清机制硬派给了文案 Agent。有了回放轨迹这个问题在十分钟内就被定性不是 Agent 能力问题而是路由阈值和兜底策略需要调整。如果没有 trace这种问题可能得靠吵架才能定位。另外我还建议在非生产环境给编排层增加一个“慢节点剖析”的额外旁路记录每个 Agent 的每次工具调用耗时分布。多Agent任务整体变慢时与其猜测是模型推理慢还是工具调用慢不如直接看耗时分布表谁拖后腿一目了然。4.4 降级策略Agent-Chat 失败时怎么办升级到 Agent-Chat 以后系统变得更聪明了但同时也变得更脆弱——链路长了出问题的可能面就大了。我也不可能保证每一次多Agent协作都能顺顺当当所以降级策略成了上线前最后弹压的一根稻草。我做的第一件事是给编排层加了一个“复杂度评估器”。消息进入以后先判断这条消息是否需要真正走多Agent协作。如果只是个简单的问候、简短查询直接走单模型的快速通道根本不进路由编排。这样做既省了 token 和延迟也大大降低了低价值请求的故障面。第二件事是设计了“自动降级到 LLM-Chat”的回退链路。当编排层检测到路由置信度低、多个 Agent 连续执行失败、或者工具接口大面积超时时系统不会硬撑着把流程走完而是把当前会话的状态打上一个标记退化为经典 LLM-Chat 模式由单个模型基于已有的公共摘要继续陪用户聊天。这个模式虽然能力弱一些但胜在稳定用户至少不会面对一个反复报错、什么都干不了的机器人。降级不是偷偷摸摸发生的。会话界面上会显示一条系统通知说明“当前系统负载较高已切换为基础对话模式”并保留用户重新发起多Agent协作的入口。实测下来用户对这种透明化的降级接受度远高于“任务失败”的报错。毕竟我们的目标是帮用户完成任务真完成不了至少把体验止损在一个服务区。5. 从实操中提炼的设计检查清单与后续演进5.1 六个必须提前想清楚的问题如果让我把这次升级的经验浓缩成一份可执行清单下面这六件事是我认为任何团队在动手前都该先回答的。第一每个 Agent 的边界如何定义能力边界、数据边界、权限边界三者必须一致。不要出现提示词里什么都能干、底层权限却这也不给那也不给的情况。第二路由失败时怎么办你的模型路由器不可避免地会犯糊涂是否设计了置信度阈值、澄清机制、规则兜底三层防线没有兜底的路由就是裸奔。第三消息结构能否表达过程如果数据模型还停留在“角色文本”建议先改数据结构再做前端体验升级顺序反了会返工。第四会话状态是否可恢复用户刷新页面、网络切换、服务重启后进行到一半的多Agent任务能否续上这是稳定性煞手锏。第五上下文如何隔离公共摘要、私有上下文、临时执行上下文三层是否清晰有没有原文回溯的通道多Agent同时工作时上下文污染是产出质量最大的隐形杀手。第六降级机制是否明确什么条件下触发降级、降级后如何呈现、用户能不能再升回去没有降级系统的可靠性承诺就得跟链路长度硬刚。这六个问题看着都像常识但我检查了我们上线的几个实际项目几乎每个项目都至少踩过其中两个。提前想清楚光是返工成本就能省下一大笔。5.2 沿着这个方向还能怎么继续演进这次升级替我们铺下了不少底子事件流消息模型、会话状态机、统一能力注册中心、全链路追踪。这套骨架其实可以往好几个方向继续生长。一个是跨会话的长期记忆。当前公共摘要还停留在每次会话内部未来完全可以沉淀成用户画像级别的长期记忆库让 Agent 在多轮任务之间记住用户偏好。另一个方向是扩展“多模输入”入口层现在收的是文本后续可以加入语音、图片、文件上传入口层只要把这些不同的输入统一转换成消息事件即可。还有一个方向是让 Agent 的协作关系从“编排层单线串联”走向“动态协商”。前端界面还是那个多Agent会话入口但后端编排逻辑可以引入更灵活的任务规划器让多个 Agent 根据执行情况实时调整协作策略。这些都是后话。就这次升级本身而言我最满意的并不是某一块代码或某一个界面效果而是团队对“入口”这两个字的理解发生了变化。以前我们觉得聊天框是产品的门面只要好看、流畅就够了现在我们知道在 Agent-Chat 这类系统里入口是指挥台它得让状态被看见、让任务可控制、让出错可回退。喜欢什么风格、用什么框架、画不画漂亮按钮反而都成了次要的事。如果你现在也正把一个 LLM-Chat 往多Agent协作方向改我想说的话其实很朴素先别急着上好看的 Agent 头像和花哨的流式输出特效把消息结构、状态机、路由兜底这三个基础桩打好你的升级之路会比我少掉好几根头发。 
长河君 · 2026/10/19 7:59:43 · 阅读 1.2k 从LLM-Chat到多Agent协作入口：架构升级实战指南
过去半年我一直在做一件事把一个看起来没啥问题的 LLM-Chat 聊天入口升级成一个支持多Agent协作的 Agent-Chat 入口。之所以用“升级”而不是“推翻重写”是因为一开始团队里不少人都觉得这事不大——聊天框嘛旁边加几个角色切换按钮、后台挂几个专属提示词不就行了真正动手以后才发现这压根不是按钮的问题而是整个入口层的定位、数据结构和交互协议都要跟着变。这篇内容就是把这次升级的完整思路和实践过程做个梳理从单模型闲聊到一个真正承担“调度中枢”职责的多Agent协作入口中间经历了什么设计取舍、踩了哪些工程坑、最后沉淀出哪些可复用的方案。适合正在做 AI 应用、想把聊天界面升级成 Agent 工作台的团队也适合刚接触多Agent架构、想搞清楚“入口层到底该长什么样”的开发者。全文以实际可落地为主不聊虚的概念。1. 升级之前LLM-Chat 的结构性瓶颈1.1 单模型对话入口到底哪里不够用先把问题说透。LLM-Chat 的本质是你有一个大厅大厅里只有一个“全能接待员”。这个接待员博学多才但有个天然限制同一时刻只有一副大脑、一套注意力、一个上下文窗口。用户提出需求它要么自己消化要么勉强调几个工具然后硬着头皮把所有事情做完。听起来好像也够用但你一旦把真实业务场景放进去问题就冒出来了。打个比方用户说“帮我查一下上周华东区的销售报表找出连续下滑超过 10% 的品类再分析一下可能的竞品原因最后把结论整理成邮件草稿。”这一句话里至少有四个环节查数、算指标、做归因分析、写邮件。如果都交给同一个全能助手它要在一轮上下文里反复切换工具、叠加多个判断逻辑中间任何一步出现工具调用错误后面的结果全都会跟着偏。而且上下文一旦长了模型很容易“忘”了最初的分析口径最后邮件草稿里的语气和前面的数据结论对不上。更深层的瓶颈是职责边界。一个 LLM-Chat 里塞进了数据分析、文案生成、日程管理、代码编写这些能力它缺乏“专业分工”的约束。数据分析应该走严谨的查询逻辑文案生成需要风格一致性日程管理牵扯到第三方权限。硬把它们放在同一个模型会话里意味着所有风险、权限、上下文污染都混在一起。出了问题你连是谁的锅都说不清更不要说针对某个角色去单独优化、单独测试。再说一个实际体验上的问题多轮复杂任务时用户根本看不到“过程”。传统聊天框只展示最终文本工具调用、中间计算、状态变化全部藏在后台。用户面对一个不断转圈圈的输入框只能干等。哪怕最后结果出来了用户也不知道它是怎么拿到的、中间用没用对表、哪一步消耗了大量 token。这种黑盒感在简单的问答场景还能忍到了“协作式工作场景”就完全不够了。1.2 多Agent协作入口的本质从“问答”转向“调度”升级的目标不是做一个界面更花哨的聊天框而是把它改造成一个“协作入口”。这里的关键认知转变是你不再是让一个万能模型回答用户的问题而是让一群各司其职的 Agent 共同完成一项任务。聊天界面退化成一种通用的交互协议真正的核心在它后面的编排层。我后来给团队讲这个概念时用得最多的类比是“饭店前台”和“厨房”的关系。LLM-Chat 相当于一个街头快餐摊老板一个人点单、炒菜、收钱忙得团团转。Agent-Chat 则是一家正经饭店前台负责接待、记录需求后厨分成凉菜、热菜、面点配菜间还有自己的备料流程。前台不需要知道每个菜怎么做它只要把单子准确传下去然后盯着出菜进度就行。如果把这个类比映射到系统设计上入口层其实就是那个“前台”——它负责接收用户意图、识别任务类型、把任务派发给对应角色再把结果汇总回来。它不负责具体执行不承载领域知识但它是整个多Agent系统的门面。用户看到的一切都是从入口进来的用户能被感知到的一切效率也都由入口决定。所以“Agent-Chat 的升级”真正要解决的问题是如何从“一个模型一把梭”的信息输入框变成一个“可路由、可编排、可观测、可干预”的协作控制台。围绕这个目标后面的所有设计才有落点。2. 多Agent协作入口的架构设计实战2.1 分层架构接入、编排、执行、存储确定了要往协作控制台的方向走之后第一件事是把代码结构和职责边界划分清楚。原来 LLM-Chat 的代码基本是“请求进来 → 拼提示词 → 调模型 → 输出文本”全挤在一个服务里。升级后我按四层来拆第一层是接入层负责处理用户消息的收发、会话建立、权限校验。它只做最基本的接口翻译不理解业务也不做路由判断。第二层是编排层也是这次升级的核心。它负责意图识别、任务分解、Agent 路由、进度跟踪。这一层相当于饭店前台的领班既要知道用户想要什么又得判断府上哪位师傅最合适。这一步的实现我放在下一节细讲。第三层是执行层由各个 Agent 组成。每个 Agent 有自己独立的角色设定、工具集合、记忆空间和执行逻辑。它们之间不直接互相调只通过编排层分配任务、回传结果。用“不直接调”这个原则很重要否则画着画着架构图Agent A 又开始直接调 Agent B 的私有工具边界就崩了。第四层是存储层包括会话记录、上下文快照、工具调用日志、状态数据。Agent-Chat 的数据量级比 LLM-Chat 大得多每个任务可能有多次工具调用、多轮中间状态没有独立的存储层后续做回放和审计会非常痛苦。这个分层看起来不复杂但实际操作中最大的阻力来自“历史代码惯性”。很多现成的业务逻辑已经写在了原来的对话处理函数里拆层的时候最容易犯的错是“只加新模块不拆旧逻辑”。结果新旧代码纠缠在一起编排层既要处理路由又背着旧业务的上下文清理。我的建议是升级期间干脆把旧链路整体打上“遗留模式”的标记新入口走独立的编排链路两边只共享底层存储和工具接口绝不共享控制流。过渡期丑一点没关系清晰最重要。2.2 任务分发的路由策略意图识别与规则兜底多Agent系统的路由策略是我起初想得最简单、实际做起来最折腾的部分。有人可能会说这不就是让大模型当路由器看完用户消息后输出一个要分发的 Agent 名称吗真这么简单就好了。模型当路由器有两个绕不过去的坑。第一是延迟问题你每来一条消息都要先让模型判断一次意图再走对应 Agent 的链路。两道模型推理叠加首字延迟直接翻倍。第二是稳定性问题模型的“路由判断”是概率性的用户随口说一句“那个、上次那个报告”它可能把本来该发给数据分析 Agent 的任务顺手分配给了文案助手然后整个任务的执行语境全错。我最终采用的是一种“规则优先模型兜底”的双层路由策略。规则层先跑一遍硬性匹配用户消息里包含明确的命令词、提到了特定的工具名、或者命中预设的正则和关键词表就直接走对应路由。这能覆盖大概 40% 的常见指令型请求速度快、零推理成本。剩下的模糊意图请求才进入模型路由并且模型路由只输出候选 Agent 列表和置信度不再直接终断。如果最高置信度低于某个阈值我这边设的是 0.6就转入一个“询问澄清”的状态由入口层反问用户而不是硬着头皮分发。除了路由还有一个特别容易忽略的细节路由结果要被记住。用户说“查一下上周的销售数据”路由到数据分析 Agent用户接着说“再把结论润色成汇报PPT”这条消息不能重新做全量路由而是要把意图附加上一条会话上下文——数据分析 Agent 的结果应当传递到文案汇报 Agent。这种上下文粘滞路由让我额外维护了一张“会话级路由状态表”记录当前活跃 Agent、已生成的中间产物引用ID、待流转的后续任务。没有这张表多Agent协作就会表现得像一群记忆只有七秒的临时工。3. 聊天界面与数据结构的升级改造3.1 消息不再是“文本”而是“事件流”这是我在升级过程中体会最深的一点。传统聊天界面消息就是两个字段角色和内容。但在 Agent-Chat 里这种模型彻底不够用。一个会话中用户发了消息系统在做路由判断Agent A 开始调用工具查数据工具返回中间结果Agent B 接手做分析然后修正了自己的想法最后给出结论——这条链路上每一步都是独立的消息片段而且它们之间有明确的依赖关系和状态属性。所以我把消息的数据模型从“纯文本”升级成了“事件流”。每一次变化都是一种事件类型用户消息、Agent 开始消息、工具调用发起、工具结果返回、Agent 中间思考、Agent 最终回复、系统通知、路由状态变化。每个事件都带一个全局递增的序号seq、一个会话 ID、一个事件类型、一个可选的事件块 ID用于把某一段工具调用链串在一起以及一个纯粹的 content 数组。这样做的好处是前端不需要猜测后端发生了什么。后端是什么状态前端就原样渲染什么状态。工具调用中前端可以展示一个可折叠的“运行中”状态块返回结果后还能展开看明细。用户不用再傻等一个转圈圈而是能看到“正在查询数据库”“正在生成图表”“正在汇总结论”。交互感知上的提升是立竿见影的。这段改造实际上还顺手解决了一个以前没注意的问题调度中途 Agent 出错时消息流里有完整的位置标记用户可以直接点击“从这条消息重新生成”而不需要把整个会话清空重来。这在传统的纯文本消息模型里几乎不可能实现。3.2 会话状态机与管理有了事件流之后下一步是把它变成更容易被程序理解的结构。多Agent协作会话本质上是一个异步过程原来 LLM-Chat 那种“请求-响应”同步模型完全无法支撑因为你不知道一个任务要流经多少个 Agent、触发多少次工具调用、中间要不要等待用户确认。我最终把每个会话定义成一个类似于“工作流实例”的东西显式维护状态机的流转。会话状态至少包含这几档初始化、路由中、等待工具结果、等待用户确认、执行完成、异常失败。不同状态之间允许转移并且只有有限几条合法路径。比如等待工具结果的会话可以转到执行完成也可以因为工具超时转到异常失败但绝不允许直接跳到等待用户确认——这是非法转移。实际产品中这套状态机还承担了“断线恢复”的功能。有一次测试环境出现节点重启用户浏览器端显示会话中断。重新连接后我把持久化的会话状态取出来发现它停在了“等待工具结果”上。系统没有傻乎乎地把整个任务重跑一遍而是先检查那个工具调用是否已超时再决定是续接还是重试。如果没有状态机这种场景只能让用户手动重新提交问题。我还在这套状态机上加了“用户干预”的入口允许用户在任何状态中止当前的链路直接给路由层发送一条“停止”指令。这对多Agent协作非常重要因为一旦任务被拆分下去执行链条往往很长用户很可能中途发现需求变了不能让系统犟着把原计划执行完。粒度上我做了两档软停止等当前工具返回后不再派发后续任务和硬停止立刻终止本轮 Agent 调用丢了就丢了。两档的代价完全不同硬停止会有一定的任务残留风险所以我把选择权明明白白交给了用户。3.3 上下文隔离与多Agent记忆管理多Agent系统里最复杂的不是路由是记忆和上下文。LLM-Chat 时期上下文就是一组会话历史一次性灌给模型Agent-Chat 不能让所有 Agent 都看到所有上下文——它们有的是涉密数据的有的是做日常写作的星罗棋布的角色共享一个超长上下文既不安全也没效率。我采用的方案是三层上下文模型。第一层是“会话公共摘要”包含用户的大致目标、已完成步骤、当前最重要的结论所有 Agent 在必要时都能读取。第二层是“Agent 私有上下文”只有被当前任务选中的 Agent 能读写里面保存它的角色设定、任务拆分结果、正在使用的工具参数。第三层是“临时执行上下文”专门给某一次工具调用或中间计算使用用完即清不进入任何历史记录。这个模型看着简单落地时最大的坑是“摘要漂移”。公共摘要是由另一个模型生成的它在概括时可能把关键的数字指标弄错或者漏掉某个用户特别强调的约束条件后面 Agent 拿到这个被污染的摘要整个结论就跑偏。为此我给公共摘要加了“原文溯源”每条摘要都附带对应的原文消息序号Agent 在不确定摘要信息时可以通过序号回查原始消息。这就避免了我看不见的模型在替我用“二手信息”做关键判断。4. 关键工程问题的解决记录4.1 并行调动冲突多Agent同时改同一份数据多Agent协作必然带来一个原本没有的工程问题并发。单模型时代你一次只处理一条消息根本不存在多个执行体同时去操作同一个数据源的问题。但多Agent架构下数据分析 Agent 可能正在查询某张表另一个报表生成 Agent 又在同一时间触发了一次写入操作。如果下面接的是一个普通的关系型数据库两边一撞轻则数据延迟重则脏读。我在实测中撞过一回事两个 Agent 同时读取了一个订单统计缓存各自基于旧缓存计算然后分别写回两份不同的汇总结果导致报表数据出现了一小时级的错乱。排查出来之后我在执行层做了三重约束。第一工具层做统一的“资源锁标记”所有写型工具在执行前必须先申请锁锁粒度精确到数据表或缓存键避免误伤并发读请求。第二编排层在同一会话内默认不派发两个有依赖冲突的任务并行执行而是把它们排成串行队列。第三所有写操作都改成“基于版本号的条件更新”更新时带上读取时的快照版本如果版本变化则丢弃当前结果并提示重新执行。这套组合拳也不复杂但它体现了一个思路多Agent系统不能把工具调用当成普通函数调用来对待。每次工具调用都可能是跨进程、跨数据源、跨时长的操作必须按“微服务之间通信”的标准来做安全设计。4.2 路由提示词与实际工具权限不匹配这个坑很隐蔽也很反直觉。重点在于Agent 的路由决策和工具权限矩阵是两套系统我却在一开始以为它们是一套东西。模型路由器判断用户意图时靠的是提示词里的描述但真正执行时Agent 能不能调用某个工具、能调哪个函数却由代码里的权限控制决定。典型翻车场景是路由提示词里写着“数据分析 Agent 可调用查询引擎和可视化工具”但权限配置文件里只给它的 API 密钥开了查询读权限可视化工具需要另一个密钥体系。结果模型愉快地把任务派发给数据分析 AgentAgent 一调可视化工具就返回 403整个链路从头崩到尾。这种行为在测试环境还不容易暴露因为测试环境里权限往往全开上到生产环境立刻现形。后续我把这套配置统一成了一个“能力注册中心”所有 Agent 的能力描述、可调用工具列表、API 权限范围全部集中在同一份注册信息里。编排层在路由完成之后除了把任务信息传给 Agent还会把当前可用的工具白名单也一起传递过去。Agent 侧接到任务时先做一次本地工具校验发现权限不匹配就立刻报一个结构化的“权限不足”错误而不是等到调接口时再爆一个裸 403。这样至少把错误信息变得可读、可定位。 这一套改下来生产环境的这类路由失败率直接下降了一个数量级而且排查问题时的信息完整度也好很多。4.3 可观测性看不见的 Agent 到底在忙什么多Agent系统对可观测性的要求远高于普通聊天机器人。普通聊天机器人出问题无外乎模型答得不准确多Agent系统出问题可能是路由错了、任务拆分错了、某个工具参数错了、某个 Agent 的上下文被污染了、甚至两个 Agent 之间衔接时信息丢失了。没有给力的追踪手段排查这些问题就像在黑屋子里找一只黑猫。我在系统里加了“全链路 Trace”的概念。每一次用户请求生成一个 traceID从入口层开始贯穿路由判断、任务拆分、每个 Agent 的执行、每次工具调用直至最终响应。所有中间步骤都打日志并且带上 traceID、事件类型、耗时、token 消耗。前端业务事件流展示给用户的只是界面层的信息后端排查时还有一份完整的多Agent执行轨迹可以回放。这个轨迹在调试时帮了大忙。有一次用户反馈某个分析结论明显不合理我把该请求的 traceID 找出来回放发现是路由阶段意图识别置信度只有 0.55但当时没触发澄清机制硬派给了文案 Agent。有了回放轨迹这个问题在十分钟内就被定性不是 Agent 能力问题而是路由阈值和兜底策略需要调整。如果没有 trace这种问题可能得靠吵架才能定位。另外我还建议在非生产环境给编排层增加一个“慢节点剖析”的额外旁路记录每个 Agent 的每次工具调用耗时分布。多Agent任务整体变慢时与其猜测是模型推理慢还是工具调用慢不如直接看耗时分布表谁拖后腿一目了然。4.4 降级策略Agent-Chat 失败时怎么办升级到 Agent-Chat 以后系统变得更聪明了但同时也变得更脆弱——链路长了出问题的可能面就大了。我也不可能保证每一次多Agent协作都能顺顺当当所以降级策略成了上线前最后弹压的一根稻草。我做的第一件事是给编排层加了一个“复杂度评估器”。消息进入以后先判断这条消息是否需要真正走多Agent协作。如果只是个简单的问候、简短查询直接走单模型的快速通道根本不进路由编排。这样做既省了 token 和延迟也大大降低了低价值请求的故障面。第二件事是设计了“自动降级到 LLM-Chat”的回退链路。当编排层检测到路由置信度低、多个 Agent 连续执行失败、或者工具接口大面积超时时系统不会硬撑着把流程走完而是把当前会话的状态打上一个标记退化为经典 LLM-Chat 模式由单个模型基于已有的公共摘要继续陪用户聊天。这个模式虽然能力弱一些但胜在稳定用户至少不会面对一个反复报错、什么都干不了的机器人。降级不是偷偷摸摸发生的。会话界面上会显示一条系统通知说明“当前系统负载较高已切换为基础对话模式”并保留用户重新发起多Agent协作的入口。实测下来用户对这种透明化的降级接受度远高于“任务失败”的报错。毕竟我们的目标是帮用户完成任务真完成不了至少把体验止损在一个服务区。5. 从实操中提炼的设计检查清单与后续演进5.1 六个必须提前想清楚的问题如果让我把这次升级的经验浓缩成一份可执行清单下面这六件事是我认为任何团队在动手前都该先回答的。第一每个 Agent 的边界如何定义能力边界、数据边界、权限边界三者必须一致。不要出现提示词里什么都能干、底层权限却这也不给那也不给的情况。第二路由失败时怎么办你的模型路由器不可避免地会犯糊涂是否设计了置信度阈值、澄清机制、规则兜底三层防线没有兜底的路由就是裸奔。第三消息结构能否表达过程如果数据模型还停留在“角色文本”建议先改数据结构再做前端体验升级顺序反了会返工。第四会话状态是否可恢复用户刷新页面、网络切换、服务重启后进行到一半的多Agent任务能否续上这是稳定性煞手锏。第五上下文如何隔离公共摘要、私有上下文、临时执行上下文三层是否清晰有没有原文回溯的通道多Agent同时工作时上下文污染是产出质量最大的隐形杀手。第六降级机制是否明确什么条件下触发降级、降级后如何呈现、用户能不能再升回去没有降级系统的可靠性承诺就得跟链路长度硬刚。这六个问题看着都像常识但我检查了我们上线的几个实际项目几乎每个项目都至少踩过其中两个。提前想清楚光是返工成本就能省下一大笔。5.2 沿着这个方向还能怎么继续演进这次升级替我们铺下了不少底子事件流消息模型、会话状态机、统一能力注册中心、全链路追踪。这套骨架其实可以往好几个方向继续生长。一个是跨会话的长期记忆。当前公共摘要还停留在每次会话内部未来完全可以沉淀成用户画像级别的长期记忆库让 Agent 在多轮任务之间记住用户偏好。另一个方向是扩展“多模输入”入口层现在收的是文本后续可以加入语音、图片、文件上传入口层只要把这些不同的输入统一转换成消息事件即可。还有一个方向是让 Agent 的协作关系从“编排层单线串联”走向“动态协商”。前端界面还是那个多Agent会话入口但后端编排逻辑可以引入更灵活的任务规划器让多个 Agent 根据执行情况实时调整协作策略。这些都是后话。就这次升级本身而言我最满意的并不是某一块代码或某一个界面效果而是团队对“入口”这两个字的理解发生了变化。以前我们觉得聊天框是产品的门面只要好看、流畅就够了现在我们知道在 Agent-Chat 这类系统里入口是指挥台它得让状态被看见、让任务可控制、让出错可回退。喜欢什么风格、用什么框架、画不画漂亮按钮反而都成了次要的事。如果你现在也正把一个 LLM-Chat 往多Agent协作方向改我想说的话其实很朴素先别急着上好看的 Agent 头像和花哨的流式输出特效把消息结构、状态机、路由兜底这三个基础桩打好你的升级之路会比我少掉好几根头发。