Agent-Reach：让多Agent协作不再“够不着”的调度中枢与网关

我之前在带一个多Agent协作项目的时候最大的感受不是模型不够聪明而是Agent之间根本“够不着”。团队里每个Agent都能完成自己的子任务但真正要把它们串成一条完整业务链路时到处都在碰壁。有的Agent没有对外服务接口有的Agent能力描述写得模棱两可调用方根本不知道它到底能干什么还有的Agent在高峰期直接超时整个流程跟着雪崩。后来我把这套触达和路由机制单独抽出来做成了一个独立的运行时组件取名叫Agent-Reach。这个项目做的事情并不复杂把所有Agent的能力注册成一个可检索的目录上层调用方只发自然语言请求由Agent-Reach负责意图识别、能力匹配、路由转发和结果回传。相当于给整个Agent体系装了一个“调度中枢服务网关”。我现在把完整的方案、实现思路和踩过的坑整理出来希望对正在搞Agent工程化的朋友有帮助尤其是卡在“多个Agent不知道怎么连起来”这个阶段的团队。1. Agent-Reach是什么先解决“够不着”的问题要理解Agent-Reach得先看看Agent落地时普遍存在的三个痛点。不是说模型能力不行而是工程侧的基础设施完全没跟上。1.1 Agent落地时最让人头疼的三件事第一个痛点是能力孤岛。每个Agent都是独立开发的有的用FastAPI起了HTTP服务有的接的是消息队列还有的干脆是脚本定时跑。对外暴露的接口风格千奇百怪有的接受JSON有的要form-data有的甚至要传复杂的嵌套结构。调用方每对接一个Agent就要读一遍它的文档写一套定制化调用逻辑。这个成本在小规模试点时还能忍一旦Agent数量超过五个基本就是维护噩梦。第二个痛点是能力描述缺失。大多数Agent没有标准化的“能力说明”你不知道它擅长什么、不擅长什么、期望什么输入、返回什么结构。这导致上层在编排任务时只能靠硬编码写死“这个需求找天气Agent那个需求找订单Agent”一旦Agent接口变了或者新增了一个Agent所有编排逻辑都要跟着改。第三个痛点是运行状态不可见。调用方发了一个请求过去Agent到底收到没有是还在处理还是已经挂了为什么这个Agent响应要3秒那个只要300毫秒全链路没有任何观测手段。出了问题只能一个一个Agent日志翻效率极低。这三个痛点单拎出来每个都好解决但放到一起就成了系统工程。Agent-Reach正是冲着这三个问题去的。1.2 Reach不是Connect从设计理念看项目定位项目取名“Reach”不是随手起的。Connect强调建立连接而Reach强调的是“触达”这个结果——你要调用一个Agent最终的目标不是把请求发出去而是让对方真正处理并拿到结果。这中间涉及三层语义找得到目录发现、到得了路由可用、有反馈结果回传与状态感知。很多团队在这一步会走偏一上来就做复杂的多Agent协商框架让Agent之间互相讨论、互相传递消息。这个方向当然是终极形态但在实际生产环境里大部分业务根本不需要Agent之间有太多自主对话它们只需要被可靠地调度和触达。Agent-Reach的定位是反过来的先保证每一次触达都是确定性的、可控的、可观测的再谈智能协作。这个定位直接决定了技术架构目录服务、路由匹配和调用网关就是三个最核心的模块本质是一个面向Agent场景的“服务注册中心API网关”只不过它的服务描述变成了Agent能力描述路由规则从配置表变成了大模型语义匹配。2. 整体架构与核心设计四层搞定Agent触达2.1 分层架构目录、路由、调用、观测各司其职Agent-Reach的整体架构分四层每一层只做一件事层与层之间通过标准数据模型交互这样任何一个层都能独立替换和扩展。第一层是Agent目录层。这一层负责所有Agent的能力注册和发现。每个Agent上线时必须向目录服务提交一份能力描述文档说明自己叫什么、有哪些能力、每个能力接受什么参数、返回什么结构、有什么标签。目录层会把这份描述存起来并提供检索接口。第二层是路由匹配层。这一层接收用户的自然语言请求先做意图识别再把意图和目录里的能力描述做匹配找到最合适的Agent。这里不是简单查表而是结合了规则过滤和语义匹配保证准确率的同时留了兜底策略。第三层是调用网关层。这一层负责真实的请求转发。匹配到Agent之后网关把用户的请求转换成目标Agent期望的协议格式发起调用处理超时、重试、熔断最后把结果标准化回传给上层。第四层是观测审计层。这一层记录每一次触达的全过程请求内容、匹配过程、选中了哪个Agent、耗时多少、成功还是失败。方便后续做质量分析和问题排查。四层设计算是参考了微服务领域成熟的服务网格方案Agent本质上是一种更智能的微服务与其从零发明一套理论不如把已经被验证过的架构模式平移过来。2.2 能力注册机制Agent怎么被“看见”能力注册是整个系统的数据底座没有一份好用的注册表匹配和调用都无从谈起。我管理的Agent-Reach项目里能力注册表最终落成了一个JSON文档结构每个Agent提交自己的一套能力描述系统校验格式后写入目录。注册的核心字段包括agent_id、name、version、description、capabilities数组、endpoint、state、tags。capabilities数组是关键它拆分了这个Agent能做的每一件事而不是笼统地描述整个Agent。比如一个客服Agent它会注册“查询订单状态”“修改收货地址”“申请售后”三个独立能力每个能力有自己的描述、参数结构和返回结构。这样拆的好处是意图匹配的粒度更细。用户说“帮我看看快递到哪了”匹配引擎可以在所有Agent的所有能力里精确找到“查询物流状态”这个能力而不是只能粗粒度定位到物流Agent然后把请求扔过去。注册表还额外设计了一个健康字段Agent可以上报自己当前的状态——healthy忙碌、draining下线维护。网关路由时会把状态纳入考量不会往一个正在重启的Agent上发流量。2.3 元数据驱动的能力描述光有名字远远不够项目里最花时间的不是写代码而是设计能力描述文档的标准。字段定得太粗下游匹配和参数转换就没法做定得太细Agent方又不愿意填。最终版本我写了以下核心元数据字段字段用途示例name能力短名称query_order_statusdescription自然语言描述供语义匹配根据订单号查询订单的实时状态tags标签用于规则过滤[order, query, user]parameters参数Schema描述期望输入{order_id: string}returns返回Schema{status: string, eta: datetime}endpoint实际调用地址/agents/order-agent/invoke参数这套Schema值得展开讲讲。刚开始我只是用自然语言描述参数后来发现网关做参数转换时根本没法解析于是改成JSON Schema格式字段名、类型、是否必须、默认值都写清楚这样网关可以直接做校验和格式转换。虽然Agent方填写的门槛变高了但换来的是后续全链路自动化这步投入非常值得。3. 核心机制实现从注册到触达的全链路3.1 环境准备与工程结构Agent-Reach核心逻辑我用的Python 3.11实现FastAPI做网关HTTP服务SQLite做目录存储。选这套组合主要是图省事Python生态做语义匹配方便FastAPI写异步接口利落SQLite零部署成本适合项目初期demo。工程结构上我拆成五个模块models数据模型、registry目录服务、matcher路由匹配、gateway调用网关、observer观测模块。目录服务存储能力描述路由匹配器读取目录做意图匹配网关负责真实调用观测模块记录调用日志。这个结构约定好了就算后面要把SQLite换MySQL、把本地匹配换成远程向量库改一个模块就行不会牵一发动全身。3.2 能力注册与Agent目录服务实现目录服务我提供了一个/register接口Agent上线后调用这个接口提交能力描述。服务端拿到描述后先做格式校验然后生成能力索引最后返回一个agent_id和secret后续Agent上报状态、下线、更新都要带上身份凭证。这个注册接口的实现比我预想的简单核心逻辑就是存储和校验没有什么高深算法。关键在于数据模型设计得合理JSON Schema里我把capability定义成嵌套对象这样一次注册就把Agent的所有能力全部提交上来。校验用了jsonschema库这个库在Python生态里已经很成熟直接拿过来用不需要自己写轮子。注册之后还有一个心跳机制Agent每30秒上报一次状态。这个设计参考了分布式系统里的节点健康检查一开始我偷懒没做结果一个Agent已经因为内存泄漏半死不活请求依然被路由过去所有任务全部超时。后来加了心跳和状态上报路由前先检查状态问题直接消掉了一多半。3.3 意图识别与路由匹配实现路由匹配是Agent-Reach最核心的智能环节。系统收到用户的自然语言请求后先对请求做意图抽取再把抽取的结果和目录里的能力描述逐一比对选出最合适的候选。匹配分三步走。第一步是规则硬过滤用请求文本里出现的keyword匹配能力描述里的tags。比如用户消息里出现了“订单”“物流”就优先在带有这些tags的能力里找。这一步能快速缩小候选集而且结果确定不会出现离谱的匹配。第二步是语义匹配把请求文本和剩余候选能力的description用向量模型做相似度计算按得分排序。这一步我用的一个轻量文本embedding模型把两段文本映射成向量计算余弦距离。相似度超过阈值的进入下一轮全部低于阈值就直接打回告诉用户“暂时没有能处理这个需求的能力”。第三步是可用性检查检查候选Agent是否在healthy状态、当前QPS是否打满、是否处于资源保护期。过滤掉不可用的Agent后最终返回得分最高的目标能力。这套匹配链路用下来准确率明显比单一方法高。纯规则匹配遇到没有完全对应的词就抓瞎纯语义词匹配容易在相近描述之间漂移规则语义状态三层配合既稳又准。3.4 调用网关与可靠性机制实现匹配完成后请求进入调用网关。网关做得比较重因为它要处理真实生产环境里的各种意外。首先是协议转换。能力描述里有parameters的JSON Schema网关根据这个Schema把用户请求转成目标Agent期望的格式。用户传的是一个宽松的自然语言请求Agent期望的是一个结构化的JSON转换规则基于Schema定义的可选必选字段来做。这一步解决了调用方和Agent之间的协议对齐问题也让Agent方可以不关心上游传过来的原始格式长什么样。然后是超时控制。网关为每一次调用设置超时阈值默认2秒超时就中断等待并标记一次失败。同时做了一个熔断器设计统计每个Agent过去一分钟内连续失败的次数超过阈值就开启熔断之后的请求不再转发到这个Agent并直接快速失败返回。熔断状态持续一段时间后会进入半开状态放一部分探测流量验证Agent是否恢复恢复就关熔断还是不行就继续断。最后是结果标准化。Agent返回的原始结果被包装成统一的消息结构里面包含调用状态、业务数据、Agent信息、耗时信息。上层业务不需要关心目标Agent的返回格式直接处理标准结构就行这大大降低了调用方的接入成本。3.5 完整调用链路演示用一个实例把整条链路串起来。假设系统里注册了三个Agent一个客服Agent、一个物流Agent、一个外呼Agent。我作为调用方向Agent-Reach发了一个请求“查一下订单号20240901的包裹到哪了”。请求先进入路由匹配层规则匹配确认“包裹”的tag和物流Agent的能力描述撞上语义匹配计算“查询物流”“包裹位置”和物流能力描述的相似度得分最高可用性检查确认物流Agent健康最终路由到物流Agent。网关按物流Agent的能力Schema解析出order_id20240901发起调用。物流Agent返回结果网关包装成标准结构回传给我。我拿到的不只是一个冷冰冰的包裹状态还有这次调用链路信息Agent身份、路由匹配分数、响应耗时这些对调试优化都很有价值。这个链路保证了上层业务只和Agent-Reach打交道不直接关心底层Agent的变化。4. 踩过的坑与后续改造方向真正把Agent-Reach跑进真实项目之后踩的坑比想象中多。有些坑靠仔细想想就能避开有些只有压力测试才能暴露出来。4.1 语义匹配会“漂”必须加兜底策略第一次上线的时候语义匹配单独挑大梁结果经常出现一个用户请求被匹配到多个Agent的情况。比如“帮我修改地址”这个请求客服Agent的能力里有“修改收货地址”订单Agent的能力里有“修改配送地址”语义上的边界本来就模糊向量相似度差距极小模型偶尔会选错。后来加了硬规则过滤和权重打分把Agent状态和实时负载也纳入权重这个问题才算稳定下来。另一个经验是匹配阈值不能拍脑袋。阈值太高用户请求经常匹配不到任何Agent全被拒了阈值太低牛头不对马嘴的能力被匹配上下游处理全错。我的做法是用历史调用数据看成功率选了让整体成功率最高的那个临界值然后用兜底策略应对低于阈值的情况。4.2 Agent状态不一致导致的级联奔溃这是压测时暴露的单个Agent响应变慢网关层面的重试机制疯狂触发重试请求占满了Agent的线程池Agent处理能力进一步下降形成恶性循环。重试本是用来提高成功率的反而成了雪崩的放大器。后来给重试做了一套明确规则只在超时错误和网络错误时重试业务逻辑错误不重试。最多允许重试一次且重试必须在第一个请求发出后的600毫秒后启动。同时熔断器参数也做了调整让它可以更早介入中断故障Agent的后续流量。4.3 调用链观测要前置设计别事后补项目初期观测模块只做了请求日志等出问题排查时发现自己傻眼了日志散落在各个服务里没有一个统一的trace_id把一次调用的全链路串起来。后来我在网关层做了标准化处理请求进来就生成一个trace_id从入口到匹配到调用到结果返回全程携带并使用它记录日志。暂时用的本地文件存储生产环境可以换ES或ClickHouse做检索。4.4 Agent-Reach的三个扩展方向项目稳定运行之后我开始琢磨还能往哪些方向延展。最想做的是多租户隔离目前目录和路由是所有Agent共享的一旦接入的Agent数量变多权限控制和安全审计就必须跟上每个租户只能看到和调用自己有权限的Agent能力。另外还计划加一个效率优先模式路由匹配时更倾向于选择历史响应更快、成功率更高的Agent避免冷门Agent一直被冷落、热门Agent长时间繁忙。我还发现了一个有意思的扩展点把Agent-Reach从“触达”升级成“编排”网关层不止转发单个请求还能把一个复杂需求拆成多个子任务、路由给多个Agent、最后聚合结果。但是这条路线我不会轻率做编排的失败处理比单纯触达复杂得多先把触达这层做扎实再说。5. 这套方案的设计复盘与心得写到这里回头看看Agent-Reach这个项目的完整历程我最想留下的不是代码而是一套思考方式做多Agent系统时触达层是整个体系的地基这个地基不牢靠上层任何花哨的智能都会崩塌。老老实实把注册表、匹配策略、调用链路这“老三样”打磨好比追新鲜概念重要得多。从数据上看引入了Agent-Reach之后整个Agent体系的集成时间从原来的两三天缩短到一个小时左右新接入一个Agent只需要通过注册接口提交描述并部署好服务。调用成功率从原来的87%提升到了96.8%。这个提升主要来自三个地方超时重试策略改对了、熔断机制挡住了故障扩散、路由匹配的置信度阈值调到了合理区间。另外从个人的实操经验来看一个很容易忽视但后期回报极高的决策是我在项目启动的第一天就把指标埋点写在了代码里而不是等到快要上线才想起来。每个模块的关键路径上都有start_time和end_time的记录最终审计回溯时省了无数翻旧账的时间。如果你准备复刻这套方案我建议你也从第一天就做好观测设施否则后面补的概率通常很低。最后再分享一个小技巧能力描述文档一定要写实不要为了让自己开发的Agent显得全能而堆一堆做不到的描述。描述越具体匹配越准下游Agent处理越顺利整体链路容错性就会越好。保持诚实Agent-Reach这样的路由系统才能发挥出应有的效果。