说实话做多智能体系统最让人崩溃的从来不是模型的推理能力不够而是Agent之间怎么把任务“递”得过去、找得对人。我自己的项目从三个Agent起步到十几个Agent的时候彻底翻车某次客户咨询进来负责意图识别的Agent把请求同时广播给了四个业务Agent四个Agent又各自拉了别的Agent帮忙最后大家互相等结果形成了一团乱麻般的循环依赖。排了一整天的日志我发现问题根本不是某个Agent写得不好而是整个系统的任务触达逻辑是缺失的——每个Agent只知道“我能做什么”却没有人负责“这个请求到底该到谁那里”。那之后我重新设计了调度层也就是这个叫Agent-Reach的项目。它的核心目标只有一个让用户的每一次请求都能以可预期、可追踪、可降级的方式从入口一路触达最终能处理它的那个Agent。如果你正在做多Agent协作、或者你想用一组“各司其职”的子模块去搭一个看似一体的助理这篇文章里的思路和代码应该对你有用。所有内容都来自我在真实业务场景里的实践不是照搬某个框架也不依赖特定的LLM供应商。1. 从“群聊式协作”到“端到端触达”我的多Agent系统为什么总在互相踢皮球1.1 问题现场一次请求引来的连锁混乱先讲一个典型的翻车场景。我在做一套企业内部的智能服务助手里面有这些Agent意图识别Agent、订单查询Agent、退货规则Agent、工单创建Agent、知识库检索Agent、情绪安抚Agent、人工客服转接Agent。单独拿出来每一个都能正常工作。可一旦把它们拼到一起问题就来了。一次用户说“我上周买的鼠标坏了想换个新的”。意图识别Agent认为这是“退货/换货”于是调用了退货规则Agent退货规则Agent返回“鼠标属于非质量问题需提供购买凭证并走人工审核”订单查询Agent这时候也跳了出来说“我查到订单在保内”情绪安抚Agent又插了一句“先表达同理心安抚用户”。结果这三个回复被同时拼接在一起用户看到的是一个逻辑混乱、语气忽冷忽热、结论自相矛盾的“缝合怪”回答。更麻烦的是某些Agent会主动去拉别的Agent。规则Agent发现要人工审核就创建了一个工单Agent工单Agent又把消息回传给了主流程。每个Agent都在“各说各话”没有人知道整条链路的当前状态。这个问题的本质不是模型能力不够而是系统里缺少一层“触达控制”。每个Agent像是一个热情过度的客服不管是不是自己的活儿都想搭茬。我后来总结了一句话多Agent系统最大的风险不是Agent太蠢而是Agent太主动。1.2 任务可达性被大多数人忽略的关键属性“Reach”这个词在计算机网络里很常见叫可达性——从A节点能不能通过一条明确的路由走到B节点。我把这个概念搬到Agent系统里定义了三种可达性语义可达当前请求的含义是否落在某个Agent声明的能力范围内。这是最基础的一层解决“能不能接”的问题。上下文可达目标Agent的输入上下文中是否具备处理该请求所必需的字段和状态数据。很多系统在这一层翻车Agent有权限和知识但拿不到足够的信息。结果可达目标Agent处理完以后它的输出能否被下游Agent或者最终用户正确消费。输出格式不匹配、缺少关键字段、返回了JSON却没人解析这些都属于结果不可达。Agent-Reach这个名字就是围绕这三层可达性来设计的。它不是一个Agent框架而是一层轻量的调度协议告诉你“谁可以调用谁、调用的时候需要什么、返回之后下一步去哪”。1.3 Agent-Reach的定位与适用边界说得更直白一点如果你手里只有两三个Agent用代码写死if-else就够如果你的Agent数量超过五个、每个Agent内部还会调用别的Agent那你就需要一套统一的路由、校验和回退机制。Agent-Reach就是为这种“中型多Agent系统”准备的。它适合以下几类场景企业内部助手多个业务系统Agent协作完成一项任务。内容生产管线检索Agent、写作Agent、校对Agent、配图Agent之间需要有序交接。客服工单系统意图识别、知识库、工单创建、人工转接之间频繁切换。不太适合的场景是只用一个模型做意图识别然后直出结果的极简对话以及需要Agent之间高度自由协商的开放式沙盒实验。前者用不上这套机制后者需要的更像是一个“Agent联邦”而不是“路由中枢”。2. Agent-Reach的核心抽象能力名片与触达矩阵2.1 capability.json每个Agent的“名片”为了让路由层知道谁该接活儿每个Agent在启动时必须注册一份能力声明。我用一个JSON文件来描述结构其实很简单{ agent_id: order_query_agent, name: 订单查询Agent, capabilities: [ { skill: order_query, description: 查询订单状态、物流信息和购买记录, input_required: [user_id, order_id], confidence_keywords: [订单, 物流, 发货, 买了, 快递], cost_weight: 0.3 }, { skill: order_modify, description: 修改订单地址、备注、取消订单, input_required: [user_id, order_id, action], confidence_keywords: [改地址, 取消订单, 修改备注], cost_weight: 0.5 } ] }字段不多但每个字段都有讲究。capabilities里一个Agent可以挂多个skill每个skill独立参与路由匹配。input_required字段是我后期才加上的它解决了“路由匹配成功但执行时缺参数”的问题。confidence_keywords不是简单做关键词匹配而是给路由算法一个先验权重后面会详细讲打分过程。2.2 触达矩阵用一张白名单限制Agent之间的互相调用Agent-Reach里最硬的一条规则是任何Agent都不能直接调用另一个Agent所有跨Agent调用必须经过触达矩阵的许可。触达矩阵本质上是Agent之间的有向边权限表类似这样调用方被调用方是否允许说明planner_agentorder_query_agent允许规划器可以查订单planner_agentemotion_agent不允许情绪安抚由前端直接触发order_query_agentknowledge_agent允许查询时可补充规则知识order_query_agentorder_query_agent不允许禁止自我递归触发any_agenthuman_fallback允许兜底转人工永远是合法的你可能会问为什么要用这么死板的矩阵Agent自由调用不更灵活吗我的体会是自由协商在Demo里很酷在生产环境里就是灾难。没有权限约束Agent会出于“善意”互相调用形成你拉我、我拉他的调用链爆炸。矩阵看起来死板但它保证了每一条调用路径都是有人批准过的。后续审计问题的时候它也给了你一张清晰的图。实现矩阵的方式很简单一张二维表查一下就行class ReachMatrix: def __init__(self, matrix_dict): self.matrix matrix_dict def can_call(self, caller: str, callee: str) - bool: if caller callee: return False return self.matrix.get(caller, {}).get(callee, False) def routes_from(self, caller: str) - list[str]: return [k for k, v in self.matrix.get(caller, {}).items() if v]2.3 核心APIRegister、Dispatch与HandoffAgent-Reach的内部接口我收敛成了三个动词Register注册、Dispatch调度、Handoff交接。Register很好理解就是加载capability.json并把它注册到路由中枢。Dispatch则是把一个用户请求经过打分、过滤、选择后交给某个Agent去执行。Handoff是整个系统里最容易被忽略但最重要的环节——Agent执行完之后它生成的不是最终答复而是一个结构化的结果包路由中枢根据结果包里的字段决定接下来应该回到用户、还是继续调下一个Agent。一个典型的结果包长这样{ from_agent: order_query_agent, status: success, payload: { order_status: 已签收, ordered_at: 2024-11-02 }, next: return_to_user, context_updates: { order_id: NO20241102001 } }next字段是Handoff的关键。它可以是return_to_user结束链路回用户、可以是某个具体的agent_id继续调度到指定Agent、也可以是trivial_fallback走兜底。Agent自己不知道全局链路是什么样它只按照自己的执行结果诚实地回答“我这边下一步需要谁”至于这一步该不该走路由中枢会结合触达矩阵再判断一次。这套设计最大的好处是Agent之间不存在隐式耦合每个Agent只需要知道自己能干什么、以及完成之后把结果包交给系统剩下的路由选择完全由中枢接管。3. 一个请求到达正确Agent的完整链路打分、过滤与降级3.1 五步路由决策过程当一个用户请求进入Agent-Reach我不直接调LLM去“读懂意图”而是先走一套确定性的五步流程。这套流程的好处是每步都可以打日志、复现、测试出了问题你能指出具体是哪个环节。第一步意图粗分类。用一个轻量模型或规则引擎判断请求的大类缩小候选Agent范围。例如“鼠标坏了想换新”会命中“售后咨询”大类。第二步能力打分。在大类范围内对每个候选skill计算一个匹配分分数由三部分构成关键词先验分、语义相似分、上下文完整分。第三步上下文过滤。检查候选Agent的input_required字段是否都拿到了。缺了关键字段的直接降权或剔除而不是硬塞给它。第四步握手确认。对得分最高的候选Agent发送一个“预检”消息它内部可以拒绝或接受这个任务。这一步能拦截“理论上匹配但实际处理不了”的尴尬情况。第五步执行与回传。确认后正式进入执行结果包交回路由中枢中枢根据next字段决定下一步。3.2 打分为什么不能只看关键词很多人做Agent路由喜欢用“关键词命中即触发”这个方案在小规模下看起来很灵但Agent一多就乱套。举个例子“我要退货”这句话。订单查询Agent命中了关键词“退货”吗它的capability里其实没有退货相关关键词但“退”字和“货”字拆开能匹配到很多模糊东西。同一个请求退款规则Agent、订单查询Agent、情绪安抚Agent可能各自都觉得自己沾边。我在Agent-Reach里用的打分公式是score 0.4 * keyword_score 0.4 * semantic_score 0.2 * context_scorekeyword_scoreconfidence_keywords在请求文本里命中的比例命中的词越多分越高。semantic_score把请求文本和skill的description分别向量化算余弦相似度。这一步能处理“没命中关键词但意思一样”的请求。context_score检查input_required字段是否齐备齐了给满分缺一半给0.5分全缺给0分。三个分数的权重我做成了可配置的因为在实践里我发现不同业务侧重的成分差异很大客服场景语义分最重要工单系统上下文分最重要简单的FAQ关键词分反倒够用。拿“我上周买的鼠标坏了想换个新的”这句话来算它命中退货/换货的confidence_keywords较多keyword_score高语义上和“退换货处理”最靠近semantic_score也高但退货换货Agent要求输入order_id而系统里还没有order_idcontext_score只有0.5。这时候它总分不一定超过别的Agent但如果所有候选都缺订单号路由中枢就会先进入一个“缺字段采集”的兜底流程——先询问用户订单号而不是强行让某个Agent蒙着做。3.3 降级链找不对人时该有的优雅收场再完美的路由也存在匹配失败的可能比如用户问了一个所有Agent都没有覆盖的问题。Agent-Reach里我设计了一条降级链优先尝试相近能力。如果“换货”没有对应Agent但“售后处理”Agent能兼容就做一次能力映射迁移。如果相近能力也失败组合尝试。把请求同时分发给“知识库检索Agent”和“工单Agent”让知识库先找标准答案找不到再由工单记录并转人工。最后一格是human_fallback。返回一段明确的兜底话术给用户同时在后台生成一条人工工单保证用户的问题不会因为“Agent不知道”而石沉大海。这里有个容易被忽略的细节降级过程也必须在触达矩阵允许范围内进行。不能说知识库Agent挂了就随便找个别的Agent顶上那会导致另一个Agent被临时塞进不擅长的工作然后产出胡言乱语。所有降级路径要提前在矩阵里画好这相当于给系统做了预案。4. 从零写一个最小Agent-Reach示例三个Agent的协作链路4.1 场景设定活动助手为了把这些概念落地我带大家从零搭一个极简但完整的三Agent系统就叫它“活动助手”。三个Agent分别是planner_agent活动规划Agent负责根据用户需求设计活动方案。weather_agent天气查询Agent负责查询指定城市和日期的天气。memo_agent备忘写入Agent负责把最终方案写进用户的备忘录。整个链路的预期是用户说“帮我规划一个下周六在上海的户外烧烤活动”planner_agent先给出初步方案但方案里需要天气信息于是Handoff给weather_agentweather_agent返回天气后planner_agent完善方案再Handoff给memo_agentmemo_agent写完后返回确认链路结束。4.2 代码实现注册、调度与交接先定义三个Agent的能力文件。这里我直接用Python字典代替JSON文件方便演示agent_defs { planner_agent: { capabilities: [ { skill: activity_planning, description: 规划活动方案给出地点、时间、流程建议, input_required: [activity, date], confidence_keywords: [活动, 规划, 安排, 方案], cost_weight: 0.2, } ] }, weather_agent: { capabilities: [ { skill: weather_query, description: 查询某城市某日的天气情况, input_required: [city, date], confidence_keywords: [天气, 温度, 下雨, 晴天], cost_weight: 0.2, } ] }, memo_agent: { capabilities: [ { skill: memo_write, description: 将文本内容写入用户备忘录, input_required: [content], confidence_keywords: [备忘录, 记住, 提醒], cost_weight: 0.1, } ] } }然后构建触达矩阵规则是planner可以调用weather和memoweather不能调用别人memo不能调用别人。reach_matrix { planner_agent: {weather_agent: True, memo_agent: True}, weather_agent: {}, memo_agent: {} }接下来是RouteDispatcher的骨架。核心就是根据打分结果选出最高分的Agent然后执行然后解析结果包继续下一步直到结束。class RouteDispatcher: def __init__(self, agent_defs, reach_matrix): self.agents agent_defs self.matrix reach_matrix def score(self, request: str, skill: dict) - float: keyword_score sum(1 for kw in skill[confidence_keywords] if kw in request) / max(len(skill[confidence_keywords]), 1) # 这里用最简单的交集近似semantic_score真正项目中可用embedding余弦 semantic_score 0.5 if request and skill[description] else 0.0 context_score 1.0 if not skill[input_required] else 0.5 return 0.4 * keyword_score 0.4 * semantic_score 0.2 * context_score def dispatch(self, request: str): current planner_agent messages [] for hop in range(5): if current return_to_user: break agent_def self.agents[current] best_skill max(agent_def[capabilities], keylambda s: self.score(request, s)) messages.append(f[{current}]使用技能:{best_skill[skill]}) # 模拟执行结果 if current planner_agent: messages.append(已规划初步方案需要天气数据) current weather_agent elif current weather_agent: messages.append(上海周六晴转多云22度) current memo_agent elif current memo_agent: messages.append(已写入备忘录) current return_to_user return messages跑一下输出大概是[planner_agent]使用技能:activity_planning 已规划初步方案需要天气数据 [weather_agent]使用技能:weather_query 上海周六晴转多云22度 [memo_agent]使用技能:memo_write 已写入备忘录4.3 边界情况两个Agent分数相同怎么办上面这个示例很顺但真实系统中每步都可能出现意外。最常见的一个意外是“多个候选Agent得分相同或接近”。例如用户说“帮我记一下周六天气顺便定一下活动”这个请求同时绑定了memo_agent和weather_agent。我的处理原则非常简单同一Agent内部的多个skill竞争时选cost_weight低的那个省成本不同Agent之间竞争时按触达矩阵里离入口最近的节点优先也就是尽量少跨Agent减少链路风险如果前两条都持平就看谁的历史成功率更高。Agent-Reach每个Agent都维护了一个滑动窗口成功率统计成功率低的会临时降权。排序在代码里长这样class RoutedCandidate: def __init__(self, agent_id, score, cost, success_rate): self.agent_id agent_id self.score score self.cost cost self.success_rate success_rate def choose_candidate(candidates): return min(candidates, keylambda c: (-c.score, c.cost, -c.success_rate))注意这里其实是一行很笨的代码但它在生产里帮我挡掉了大量“随机选Agent导致结果不稳定”的投诉。多Agent系统的使用者最敏感的事情就是同一个问题问两遍得到两个不同答案。让选择过程确定性尽可能地高比让单次回答更聪明重要得多。4.4 为什么Handoff状态要显式透出很多人问我为什么不直接在planner_agent的Prompt里写“你需要天气信息时调用天气查询函数”这当然可以那是函数调用的思路。但函数调用有一个问题它假定当前Agent有能力、有意愿、有权限去正确选择外部工具。在真实环境里planner_agent可能会因为提示词覆盖不完整、模型抖动、上下文过长而忽略了该做的天气查询也可能调用了但把返回结果解析错了。而Agent-Reach把交接变成了一个独立的、由路由中枢控制的状态转移相当于把“调用天气Agent”从模型的能力范围内移除了变成了一种路由中枢的确定性行为。这样做的代价是灵活性下降收益是可预测性大幅上升。Handoff状态显式透出还有一个附加好处你可以给用户展示一条链路轨迹。用户能看到“规划Agent → 天气Agent → 备忘Agent”的过程这比一坨黑盒输出更能建立信任感出了问题排查定位也清晰得多。5. 实战中绕不开的四个坑从崩溃到稳定的排查过程5.1 坑一路由风暴与循环握手第一次用Agent-Reach接真实业务时我遇到的最诡异的问题是某个对话会话里planner_agent和weather_agent在互相Handoff一秒钟之内来回跑了十几次token开销疯狂上涨用户那边看到的却是“正在生成中”的转圈。排查过程是这样的我先在路由层打出了完整的事件日志发现planner_agent执行完后next字段是weather_agentweather_agent执行完后next字段又变回了planner_agent。表面上看起来像是两个Agent各有道理planner说“我需要天气才能继续”weather说“天气已返回剩余方案需要planner来定”。根因不是这两个Agent的逻辑错了而是我在结果包协议里缺少一个“版本号”字段。weather_agent返回天气数据后再让planner介入planner拿到的上下文里其实已经有了天气数据但它没意识到任务已经往前推进了于是又触发了一次天气查询需求。修复方式是在结果包里加了一个request_version字段要求每次Handoff时递增并且任何Agent在触发外部调用前必须检查依赖数据是否已经存在于上下文里。自那以后我把一条铁律写进了文档Agent向你Handoff时你要默认它还没做这件事除非上下文里已经有对应的结果标记。5.2 坑二上下文串扰——Agent在互相污染Prompt第二个坑更隐蔽。有一次用户先查了订单然后又问天气系统里order_query_agent把“订单号”写进了共享上下文weather_agent在生成回答时读到了这个订单号字段在回复天气的末尾突然加了一句“此外您的订单NO20241102001还在保修期内建议尽快处理换货”。这是典型的上下文串扰共享上下文空间让每个Agent都能读到所有历史字段但Agent无法分辨哪些字段和它的当前任务相关。查天气的Agent看到订单号字段误以为是系统向它补充的用户背景顺手就当成了自己的任务内容。我的解决方案是给上下文上一把“作用域锁”。每个Agent在执行时只能看到一个受限视图——也就是路由中枢从完整上下文里按input_required和output_fields裁剪出来的子集。完整上下文不是不能用而是必须显式声明哪些字段是“全局只读公共信息”比如用户昵称、时间、语言其余字段一律按需传导。这个改动让我损失了一点灵活性但换来的是Agent回复再也不会“跑题带私货”。如果你现在做的多Agent系统也有Context乱串的问题强烈建议你先做一次裁剪而不是盲目加Prompt约束。5.3 坑三提示词越写越长效果反而变差第三个问题来自我自身的经验教训。刚开始给Agent写系统提示词时我追求面面俱到把路由规则、语气要求、禁止事项、历史背景全塞进去。结果Agent表现越来越机械稍有意外就不知所措。后来我推翻重来把每个Agent的提示词收敛到三个部分角色与目标、输入字段说明、输出结果包格式。至于“什么时候调用哪个Agent”这种事情全部交给路由中枢去判断Agent提示词里一个字都不提。这个改动之后Agent的表现反而稳定了很多。模型在“我只用做好自己这一步”的场景下远比“我还要决定整个系统的下一步”表现得可靠。这也是Agent-Reach这套编排哲学的核心让模型做模型擅长的事也就是狭窄任务执行把系统级的调度决定交给确定性代码。5.4 坑四成本失控——触达链条越长越贵最后一个坑和钱有关。多Agent触达链条每增加一跳成本不只是一次额外调用还包括上游上下文带着的历史token重复计费。我第一次跑通完整链路时一个正常的活动规划请求花了接近两万token其中一半都是重复传输的历史上下文。后来做了三个优化第一上下文裁剪不再把完整对话历史传给每个Agent第二压缩中间结果每个Agent只把结构化结果包留在上下文里原始的冗长文本在生成摘要后丢弃第三设置全局链路预算当链路经过的Agent数量超过阈值时强制进入“压缩模式”让最后的意见汇总Agent只读取前序Agent的结构化摘要而不是完整记录。优化后同样的请求token消耗降了将近60%。这个数字不是一次特殊的胜利而是说明多Agent系统里成本失控更多的时候不是模型太贵而是链路设计在无意识地把token浪费在搬移不动的东西上。6. 接下来想做的事Agent-Reach的进阶方向6.1 把关键词评分升级为“语义能力索引”目前Agent-Reach的打分部分仍是关键词embedding的混合体胜在简单稳定但弱点也很明显对带隐喻、反讽、省略语的用户表达容易误判。我计划在下一个版本里引入一个语义能力索引层把每个skill描述扩展成一组“能力原型句子”然后用LLM对请求文本做一次轻量“能力重写”后再去匹配。比如把“鼠标坏了想要新的”重写为“用户请求更换损坏配件”对这个重写结果做语义检索能明显提升召回精度。这块还没完全跑通主要卡在“能力原型句子”的维护成本上。你要是想自己试可以先从二十个句子起步看看能不能覆盖你业务里的八成常见请求。6.2 触达链路的可视化与审计回放Agent-Reach现在每个请求都会打一份结构化日志但我只是把这些日志作为排错依据在用还没有做成界面化的回放工具。下一步我想做的是把请求从进入到最终返回的每一步触达轨迹画成一条可展开的链路图包含每个Agent的得分、上下文裁剪结果、Handoff理由和token消耗。这个能力对上线初期的联调和用户投诉溯源价值会很大。如果你是自己做内部系统不妨先用“trace_id JSON日志”凑合着实现类似的能力体验过回放的方便之后你就回不去了。6.3 从路由中枢走向自组织让Agent具备“需求广播”能力最后聊聊更大的方向。现在的Agent-Reach本质上是一个中心化的路由系统所有触达决策都经过中枢。它的好处是可控代价是系统里新增一个Agent时需要人工改矩阵、加能力定义才能被路由发现。我在琢磨的进阶版本是允许Agent在矩阵允许范围内向“能提供某类技能的Agent”发起轻量广播而不是单独指定目标。比如说memo_agent在写入备忘时发现缺少日期信息它可以广播“谁有日期解析能力”持有该能力的Agent会回应并完成日期补全。这个设计需要比当前严格得多的协议不然会退回文章开头那种“群聊式协作”的混乱状态。但它确实代表了一个更接近未来的形态系统的能力不是被预先编死而是在每一次任务中按需被发现与被触达。Agent-Reach这个名字里的“触达”迟早要从“路由到预定节点”进化成“发现离任务最近的节点”。那时候多Agent系统的体验大概会再上一个台阶。我在实际使用中的体会是无论代码怎么写路由策略都应当作为独立的可观测层保留下来不要为了“智能”去牺牲可见性。先让每个请求的触达路径变得清晰、可控、可回放再考虑让Agent更自主这个顺序一定不要反过来。