做多Agent系统这一年我最大的感受是模型能力决定一个Agent的上限而系统设计决定一群Agent的下限。Agent-Reach就是我为了解决这个问题在公司内部主导落地的一套编排与治理框架。单Agent跑Demo很容易可一旦把三五个Agent放进生产环境问题就变得狰狞——请求进来了不知道该交给谁Agent之间互相调用形成环路工具权限越界把不该看的内部数据漏给了下游场景。所谓Reach我把它理解成触达一个用户请求最终能否被正确触达给合适的AgentAgent的工具调用能否触达它该触达的系统任务失败后能否把控制权触达回上一个环节。Agent-Reach的核心是一张触达矩阵、一个路由决策引擎、一套工具权限控制。它解决的问题不是让某个Agent更聪明而是让一群Agent不内耗、不乱跑、犯错了还能查得到。这篇文章适合两类读者一类是手上已经有多个Agent在生产环境跑、正在头疼任务调度和权限混乱问题的人另一类是准备把Agent从技术Demo推向真实业务的工程师。我会把Agent-Reach的设计思路、实现要点、以及线上踩过的坑都写出来希望能帮大家少走一些弯路。1. 多Agent系统失控的根源触达边界模糊1.1 为什么Agent一多就乱先讲一个我观察到的普遍现象。很多团队最开始只有一个Agent比如一个客服机器人。所有请求都进这一个入口思路很清晰意图识别、检索知识库、生成回复。但业务规模上来之后一个Agent扛不住于是拆成订单助手、售后助手、退款助手、商品推荐助手好几个。问题就从这一刻开始了。第一个问题是请求分发没有标准。订单助手拿不下售后问题它不会说这个我做不了而是会尝试自己编一个答案或者把问题转给某个好像能处理的Agent而这个目标Agent往往是猜的。你去看日志会发现它转交的理由千奇百怪同一个类型的请求今天转给这个Agent明天转给另一个。第二个问题是工具权限没有隔离。早期图省事所有Agent共用一套工具调用接口结果就是售后助手能查订单、能改价格、能调库存。这在Demo阶段看不出毛病一旦真实业务接入就是事故。我见过一个团队因为没做权限隔离一个测试Agent误调了删除接口把一批测试数据清掉了好在只是测试环境但也足够让人后怕。第三个问题是链路调用没有记录。A调B、B调C、C又调A看起来每个Agent都在干活但日志里只有零散的调用记录没有人知道任务为啥没完成。排查问题的时候只能一个一个Agent去翻日志翻半天还是一头雾水。我把这几个问题总结成一个词触达边界模糊。所谓边界有三层——任务该触达谁、工具能触达什么、调用链可以触达多深。Agent-Reach就是把这三层边界做成了可配置、可执行、可观测的东西从系统层面把谁该干什么固定下来。1.2 触达矩阵把治理逻辑变成一张表Agent-Reach里最核心的抽象是一张叫触达矩阵Reach Matrix的配置表。我第一次给团队成员讲这个概念的时候用了这样一个类比就像一栋大楼的消防疏散图每个房间能通向哪条走廊、哪个门是单向的、哪个区域禁止进入全都画得清清楚楚。Agent之间的协作关系本质上也应该是一张这样的图。这张表长这样Agent可处理任务域可调用工具可访问数据域可调用下游Agent订单助手订单查询、订单确认get_order, confirm_orderorders库只读售后助手仅转交售后助手退款申请、售后审核get_order, create_refundorders库只读、refunds库读写无商品推荐助手商品检索、偏好分析search_products, get_user_profileproducts库只读、user_profiles库脱敏订单助手仅查询这张表不是给人看的是给路由引擎和权限拦截器看的。每次请求进来路由引擎根据任务类型从矩阵里选出候选Agent每次Agent要调用工具权限拦截器检查调用方是否在对应单元格里。规则一旦固化Agent就不可能再乱跑。有人会问让大模型自己判断不就可以了吗我的回答是大模型擅长的是语义理解不擅长严格遵守权限边界。今天你让它明白售后助手不能改价格明天换个Prompt写法它可能就忘了。与其赌模型的自觉不如把边界下沉到系统层用确定性规则约束不确定性行为。这是Agent-Reach设计的第一原则。2. 路由决策引擎请求进来之后的完整旅程2.1 三层路由意图识别、容量判断、上下文粘性路由决策引擎是Agent-Reach的大脑但它不是一个巨大的模型而是一套轻量的决策链路。一个请求进来后会依次经过三层判断每一层解决一类问题。第一层是意图识别。这里我建议用一个小型的分类模型或者直接调大模型API做一次结构化输出。不要复用业务Agent来做意图识别原因很简单业务Agent有自己的任务上下文让它又干活又当路由结果往往是两件事都做不好。我们把意图识别独立成一个组件输入是用户原始query输出是标准化的任务类型比如order_query、refund_apply、product_recommend。这一步的输出精度直接决定后续路由质量所以我要求意图分类的置信度低于0.7时宁可让请求走人工兜底通道也不要强行分给某个Agent。分错了再补救比一开始就走人工通道成本高得多。第二层是容量判断。矩阵表告诉路由引擎谁能干但没告诉谁现在有空。每个Agent实例在上线时要注册自己的最大并发数、当前队列长度、平均处理时长。路由引擎在派发前会算一道简单的负载判断如果目标Agent的当前队列长度超过最大并发数的80%就把请求排到备用Agent或者丢进延迟队列。这里有个容易踩的细节不要只看并发数还要看任务类型。订单查询是短任务几百毫秒就结束退款审核是长任务可能要等人工审批。容量判断要按任务类型的维度分别统计否则短任务会被长任务堵死整个Agent的吞吐直接垮掉。第三层是上下文粘性判断。这是最容易忽略、也最影响用户体验的一层。假设用户先问了我的订单送到哪了紧接着又问那退款呢。第二句话单独看语义很模糊但如果路由引擎知道上一轮会话是哪个Agent处理的就能把这一轮继续粘到同一个Agent上让它带着前面的上下文来处理。Agent-Reach里给每个会话维护了一个agent_binding字段记录最近一轮是由哪个Agent处理的。路由时如果当前query的意图与上一轮Agent的任务域有重叠优先选择该Agent。这层判断不能省——任务一旦被切到不同Agent上下文就断了用户会明显感觉这个机器人不记得我说过什么。2.2 路由结果不只返回目标还要返回回滚路径很多路由系统只关心这个请求发给谁但Agent-Reach会多存一个东西回滚路径。什么叫回滚路径简单说当目标Agent无法完成任务时它有权把任务交还给路由引擎此时路由引擎需要知道这个任务从哪儿来、还能退回给谁。比如商品推荐助手在推荐过程中需要确认用户有没有下单资格它把子任务路由给订单助手订单助手查完发现用户没有下单记录于是整个主任务失败。此时如果商品推荐助手没有回滚路径它就只能硬着头皮编一个推荐结果如果有回滚路径它可以明确告诉用户我这边暂时无法为您推荐因为需要先有订单记录并把这个结论连同中间过程的调用链一起返回给上层。为了保证这一点Agent-Reach在每个任务对象里增加了一个rollback_path字段本质是一个栈结构。每经过一次子Agent路由就把当前Agent的标识压栈任务失败或主动放弃时从栈顶依次弹出逐层返回。这听起来简单但实际效果立竿见影——它让Agent敢于承认我做不到而不是硬编答案。在我的经验里一个会承认失败的Agent比一个假装成功的Agent可靠得多。用户宁可听到暂时查不到也不想收到一个看似正经实则胡编的答复。3. 工具权限治理让每个Agent只碰它该碰的东西3.1 工具注册表与最小权限原则权限这块我的建议可以用一句话概括永远不要相信Agent的自律相信注册表和拦截器。Agent-Reach里有一个工具注册表Tool Registry所有Agent能调用的工具必须先在这里登记。登记时不是只写工具名和函数指针而是要声明它的调用参数结构、返回值结构、调用方授权范围、以及是否需要敏感操作复核。举个例子get_order这个工具注册表里会写明允许调用方为订单助手、售后助手、商品推荐助手参数必须包含order_id且类型为字符串返回值中包含用户姓名、手机号等PII字段因此默认脱敏输出。权限拦截器会在每个工具调用发生前做三件事一是校验调用方Agent是否在授权列表中二是校验参数是否符合声明结构防止恶意或错误的参数注入三是检查返回值是否包含不允许该调用方看到的字段如果有则自动脱敏。这套逻辑一旦上线你就再也不用担心售后Agent顺手查了不该查的数据这种问题。这里要强调一个实践细节权限规则一定要做成动态配置而不是写死在代码里。业务边界是会变的今天售后助手可以查订单明天可能就不可以了。如果规则写死在代码里每一次调整都要发版Agent-Reach的治理矩阵就失去了意义。我们的做法是把矩阵表放在一个独立的配置服务里支持热更新。配置变更后存量会话不强制重载新会话立刻生效兼顾了稳定性和灵活性。这个细节看着不起眼但实际运维中帮我们省了大量发版时间。3.2 敏感操作的复核与留痕有些操作即使Agent有权限也不应该让它悄无声息地执行。比如创建退款、修改订单价格、删除用户数据这一类操作在Agent-Reach里被标记为敏感操作。敏感操作的处理链路是Agent发起调用请求权限拦截器校验通过然后进入复核队列——注意不是直接执行。复核队列的消费方有两种一种是预设的人工审批人收到审批通知后在管理后台确认另一种是配置好的业务规则比如退款金额小于某个阈值且订单状态正常时自动通过。复核通过后工具才真正执行执行结果连同审核人、审核时间、触发Agent、原始请求参数一起写入审计日志。有读者可能觉得这会影响Agent的执行效率——确实会退款操作从秒级变成了分钟级甚至小时级。但我的观点是涉及到钱的场景慢一点是应该的。Agent的价值在于把高频、低风险的流程自动化而不是替人类做高风险决策。我们线上的数据是约70%的退款申请走自动规则通过剩下30%进入人工复核整体效率仍然比纯人工提升了3倍以上。效率和安全的平衡点可以参考这个比例去调。审计日志这块也别偷懒。日志里至少要记录触发Agent标识、会话ID、工具名、请求参数脱敏后、执行结果、时间戳、链路追踪ID。这套日志不仅是事后追责的依据更是后续优化路由策略、排查隐患的数据基础。后面我会专门讲一个靠审计日志定位线上事故的案例。4. 线上踩坑实录一次Agent互相调用引发的雪崩4.1 事故背景与表现Agent-Reach上线第三周我们遇到了一次比较刺激的事故。事故的起点是一个很普通的用户请求帮我查一下我上周买的东西能不能退。意图识别判定为售后咨询路由给售后助手。售后助手判定需要先确认订单状态于是调用get_order订单服务正常返回后售后助手又调用create_refund发起退款申请。到这里一切正常。问题出在另一个入口。商品推荐助手在给另一个用户做推荐时需要确认该用户是否具备下单资格于是它调用了订单助手的子任务接口。订单助手在处理这个子任务时为了完善用户画像又反向调用了商品推荐助手的服务。于是出现了A调用B、B调用A的环形调用。由于两个Agent都在等对方返回而Agent-Reach当时还没有设置调用深度上限这个环越转越大最终把两个Agent的线程池全部占满连带影响了同一进程里的其他Agent。事故持续了大概40分钟期间所有Agent响应超时。4.2 排查链路从混沌日志里找出真相这类事故最难受的地方在于症状是全局性的——所有Agent都卡了根因却是局部性的——两个Agent之间的一个环。如果只盯着系统变慢了这个表象排查三天也未必有结果。我们当时的排查思路是复盘式的。第一步从网关日志里找到第一批超时的请求提取出它们经过的Agent链路ID。第二步用链路ID在审计日志里把完整的调用链拉出来发现多条链路都出现了order_assistant到recommend_assistant再到order_assistant这种循环模式。第三步在代码里确认这两个服务的调用关系发现商品推荐助手会调订单助手的接口而订单助手的完善画像逻辑里又反向调用了商品推荐——这个反向调用是历史需求遗留当时因为只调一下应该没问题的侥幸心理留了下来。就是这一行应该没问题差点把整个系统拖垮。这里想给一个实操建议多Agent系统的日志一定不能只按Agent维度打必须给每次请求生成全局链路ID并且在所有日志、所有工具调用、所有审计记录里透传这个ID。没有链路ID这种跨Agent事故就像大海捞针。Agent-Reach从这次事故之后把链路ID的透传作为硬性要求写进了代码规范任何Agent之间的调用如果发现上游传入的链路ID为空直接拒绝受理并返回错误。这一步很粗暴但非常有效它逼着所有开发者在写Agent调用时都带上链路上下文。4.3 修复方案调用环检测与深度限制排查出根因之后我们做了两件事来修复。第一件事是删掉历史遗留的反向调用代码。订单助手不再需要完善用户画像这个需求本来就是多余的删掉之后环形调用从根源上消失。但光删代码不够因为谁也不敢保证未来不会出现新的环。所以第二件事是给Agent-Reach的路由引擎增加了两层防线。第一层防线是调用深度限制。每个任务对象里维护一个call_depth计数器每经过一次Agent调用加1默认上限是5。超过上限时路由引擎不再派发新Agent而是直接把任务标记为失败返回业务链路过深请人工介入。这个上限设置成几要看业务复杂度我建议从3到5开始先观察正常业务的调用深度分布再慢慢放宽不要一上来就设一个很大的数。第二层防线是调用环检测。Agent-Reach在任务对象里维护了一个已访问Agent列表每次路由前先检查目标Agent是否已经在列表中。如果已经在说明这条路走回头路了直接阻断并向路由引擎抛出环警告。这个检测本质上是图算法里最简单的路径上重复节点判断成本极低但能挡住绝大部分因配置或代码失误导致的环。4.4 这次事故给我的三个教训事后总结我觉得有三个方面值得所有做多Agent系统的人记住。第一Agent之间的调用必须有明确的业务动机。如果一个Agent要调另一个Agent必须在配置里说明调用的目的是什么如果只是顺手调一下这个调用就不该存在。Agent-Reach里我加了一条校验规则所有跨Agent调用必须注册在触达矩阵中矩阵里没有的调用路径一律不允许。这条规则把代码里那些隐性的调用关系全部逼到了显性配置里以后谁再想偷偷加调用过不了矩阵这一关。第二优先级最高的永远是失败要能查到。多Agent系统出错不可怕可怕的是出错之后无从查起。链路ID、审计日志、调用深度计数这些看起来是额外工作真到事故发生时它们是救命的东西。没有这套东西那次40分钟的雪崩事故我们可能得排查一整天。第三不要试图用更强的Prompt来解决结构性问题。环调用也好权限越界也好本质是系统结构问题Prompt写几万字也堵不住一个设计漏洞。我后来在公司内部反复讲一句话Agent的能力要靠模型Agent的秩序要靠系统。5. 部署形态与落地从小项目到可观测体系5.1 最小可用版本一张表加一个拦截器如果你只是想在自己的项目里快速验证Agent-Reach的思路不需要一上来就做完整框架。我建议的最小可用版本只需要三个组件一张触达矩阵配置、一个路由函数、一个权限拦截函数。路由函数的核心逻辑可以很朴素输入意图类型和会话上下文查矩阵表过滤出候选Agent加上负载判断和上下文粘性判断返回目标Agent。权限拦截函数更简单输入工具名和调用方Agent标识查矩阵表里的工具授权列有权限就放行没有就拒绝。这两个函数加起来可能不到300行代码但已经能解决任务乱分发和工具越权这两大核心问题。如果连配置表都不想维护也可以先做成代码里的静态字典。我见过一些团队用Python字典维护触达矩阵效果也不差。但一旦Agent数量超过5个业务域开始交叉我就强烈建议把矩阵迁到配置服务里去用管理后台可视化管理。人不喜欢改代码但很喜欢点按钮这句话在工程管理里颠扑不破。后台可以做得简单一点哪怕只是把矩阵打成一个可编辑的表格页面也比让业务人员在GitHub上提Issue强。5.2 可观测性每次触达都留下痕迹可观测性是Agent-Reach进入生产环境的必要条件。我把它拆成三个层次。第一层是调用链追踪。每个请求的全局链路ID、每个Agent调用的父子关系、每个工具调用的耗时都记录下来。用现成的OpenTelemetry或者SkyWalking都能实现不用自己造轮子。关键是要把Agent的语义信息意图类型、Agent名称、工具名作为额外的标签附加到span上这样查询时才能按业务维度聚合而不是只看一堆无意义的ID。第二层是触达成功率的度量。我们在线上的核心指标叫TSRTouch Success Rate触达成功率定义是一个请求从进入到最终完成真正被正确Agent处理且用户得到有效答复的比例。TSR的统计口径容易出错我在设计时把它拆成三段路由成功有Agent接收、执行成功Agent完成工具调用链、答复成功用户侧确认答复有效。任何一段失败都计入TSR分母。这个指标很重要因为它能从整体上反映一个多Agent系统的健康度。只看单个Agent的响应时间看不出整个编排体系的好坏。第三层是失败归因面板。所有失败请求按照失败阶段路由失败、执行失败、权限拦截、环阻断、深度超限自动归类汇总到一张面板上。哪一类失败在增长一眼就能看出来。这个面板做起来不难但价值极高——它让Agent系统的优化从拍脑袋变成了看数据。比如我们曾经在面板上发现权限拦截类失败突然上升排查后才知道是业务侧新增了一个数据域但矩阵表没有同步更新。如果没有失败归因面板这个问题可能等用户投诉了才会被发现。6. 一些零散但重要的经验最后分享几条我在Agent-Reach落地过程中积累的个人体会不一定成体系但每一条都是踩过坑换来的。关于触达矩阵的粒度我的建议是先粗后细不要追求一步到位。最初上线时我们的矩阵只按任务域分一个Agent一整行授权跑了两周后才根据失败归因面板逐步细化到工具级。一步到位的坏处有两个一是配置工作量太大二是业务人员根本不知道怎么填这么细的表反而会乱填或者干脆不填。从粗粒度起步让实际运行数据告诉你哪里需要细化这是最省力的路径。关于是否用大模型来做路由决策我的态度是分场景。意图识别用大模型没问题但这个Agent现在忙不忙这种判断用确定性算法就好不需要模型介入。混合架构是当前多Agent系统最实用的形态需要语义理解的地方用模型需要确定性的地方用代码。不要被全AI驱动的概念绑架系统该稳定的时候就得稳定。关于团队协作我想提醒一点Agent-Reach这类治理框架的落地真正的阻力通常不在技术而在业务边界的确权。你问售后助手能不能改价格业务负责人可能自己也说不清。所以在项目初期一定要花时间拉着业务方做一次权限边界盘点把每个Agent能做什么、不能做什么、什么操作需要复核一项一项确认清楚。技术再强的系统也架不住业务定义本身是模糊的。如果你正在做多Agent系统我的建议是先从一条最痛的链路开始把触达矩阵建起来把路由和权限拦截接上再慢慢加可观测性和环检测。不用一开始就追求大而全把一条链路的秩序做好比铺十个Agent但每个都不可控要强得多。Agent-Reach这个名字我起的时候想的就是让每个请求都能稳稳地触达到该触达的地方不迷路不越界犯错了还找得到回头的路。