Agent-Reach：多Agent协作中的智能路由与调度层

这两年AI Agent做多了，你会发现一个特别拧巴的问题：单个Agent的能力越来越强，可一旦涉及多个Agent配合，怎么让请求“找对人、办对事”，反而成了最头疼的事。Agent-Reach这类项目，本质上就是在这个夹缝里长出来的东西——它不负责具体业务逻辑，也不做模型微调，而是把“让请求精准触达正确Agent”这件事做成了平台能力。你把它看成Agent世界里的路由层、调度层、连接层，都行，核心就一句话：解决Agent之间“找不到、连不上、串了线”的问题。

这东西适合谁？两类人最需要。一类是正在从单体Agent往多Agent架构迁移的团队，手里已经有几个Agent了，开始发现互相调用全靠硬编码、if-else，改一处崩一片；另一类是做Agent平台产品的开发者，不想每次对接新Agent都重写一遍路由和会话逻辑。这篇文章我结合自己实际搭建和跑通Agent-Reach的经验，从设计思路、核心机制、落地配置讲到排查技巧，尽量让没接触过的人照着也能把项目跑起来。

1. Agent-Reach 在解决什么问题

1.1 一个请求要穿越多远才能触达正确的Agent

先从一个最常见的场景说起。假设你的系统里有三个Agent：一个负责客服话术生成，一个负责售后工单分类，一个负责知识库检索。用户来了一句“我的订单三天了没发货，你们到底怎么回事”，这句话里其实同时踩了三个Agent的能力域——客服要生成安抚话术，工单系统要判断这是“物流投诉”还是“催发货”，知识库要去查这个订单对应仓库的物流状态。

在一个没有连接层的架构里，你要么用一个“总Agent”把这句话先理解一遍，然后自己写一堆if-else去挨个调三个子Agent；要么让三个Agent都收到这同一句话，各干各的，再拼接结果。前者的问题是“总Agent”很快变成一个大泥球，所有的路由逻辑、参数转换、异常处理全堆在一层里；后者的问题更严重——三个Agent会同时消费同一份上下文，互相干扰，可能工单这边还没分完类，客服那边已经生成了一句不合时宜的道歉话。

Agent-Reach管的就是这一段路：从请求进来，到目标Agent执行完，再到结果返回。它像一个智能网关，站在请求和Agent之间，负责判断这句话该走哪条路、带什么上下文过去、等多久、失败了怎么处理。你不再需要在业务代码里写死“如果用户提到了发货就调订单Agent”，而是把这种路由规则下沉到Agent-Reach这层，用能力描述和策略配置去表达。

1.2 传统点对点串联的三大死穴

在没有Agent-Reach这类层的多Agent系统里，最常见的病根有三个，我一个个说。

第一个是路由语义硬化。意思是Agent之间的调用关系写死在代码里，A调用B是因为A的代码里写了一行“调用B的接口”。一旦Agent数量上来，这种点对点关系会以平方级增长，十个Agent理论上就有九十条调用关系要维护。每次新增一个Agent，你都要回头去改老Agent的代码，这个改动的连锁反应非常可怕。我见过一个团队，二十几个Agent的调用关系最后还是靠一个Excel表在维护，新同学入职第一天就是对着那张表发懵。

第二个是上下文搬运失真。点对点调用时，请求方通常把自己的全部上下文一股脑丢给目标Agent，结果就是目标Agent收到一大堆无关信息，生成质量被严重干扰。举个具体的例子，客服话术Agent需要的是用户情绪、购买商品、订单状态这几个字段，但串联模式下它可能收到的是完整的对话历史、日志片段、甚至其他Agent的内部中间结果。这就像你让人帮你递句话，结果你把整本聊天记录都塞给他，他反而不知道该挑哪句说了。

第三个是失败处理缺失。点对点调用里最常见的超时设置就是“读个秒就重试”，但谁该重试、重试时上下文要不要带上一次的结果、同一个请求重试时会不会被另外两个Agent重复消费，这些问题几乎没有几个团队认真考虑过。最后的表现就是线上偶发地丢工单、重复发通知、或者一个请求被同一个Agent跑了三遍，还互相覆盖结果。

这三个问题叠加起来，多Agent系统的规模效应完全出不来——Agent越多，系统越脆，而不是越强。Agent-Reach的思路就是把这三种杂活全部收编到一层统一处理。

1.3 Agent-Reach 是什么：定位与边界

既然叫Reach，它的核心就不再是“调度”这个略显被动的词，而是“触达”这个更带目标的动作。调度告诉你怎么走，触达告诉你一定要走到、而且要走到对的地方。所以Agent-Reach的定位我总结成三句话：

• 它是一个路由层：请求进来，经过语义解析，命中一个或多个Agent的能力域，把请求送过去。
• 它是一个上下文编排层：决定什么信息可以带过去，什么信息必须留下，避免上下文污染。
• 它是一个可靠性保障层：超时、重试、降级、结果聚合，这些脏活累活它全包。

但要注意它的边界。Agent-Reach不应该是Agent的业务逻辑容器——它不应该替Agent做决定，也不应该缓存Agent的业务数据，更不应该变成Agent之间传大文件的通道。它的职责是“帮请求找到人”，而不是“替人干活”。这个边界想清楚，部署出来才不会变味。

2. 核心设计与关键词解读

2.1 Agent 注册与能力描述：让Agent“自己说会什么”

Agent-Reach的第一个关键机制，是让每个Agent在上线的时候，主动提交一份“能力描述”。这个设计的思路很像微服务里的注册中心——服务启动时向注册表登记自己的IP和端口，调用方不再写死地址，而是在注册表里按名字查找。但Agent-Reach更进一步，它要求Agent登记的不仅是地址，还有一个机器可读的能力边界。

我落地时用的是类似OpenAPI Schema的格式，但做了一些扩展。每个Agent在接入时提供四个部分：agent_id（全局唯一标识）、endpoint（调用地址）、capabilities（能做什么的自然语言描述）、input_schema（需要什么参数、参数类型、约束条件）。举个例子，代码审查Agent的能力描述大概是：

agent_id: code-reviewer-v2 endpoint: http://agent-code-review.internal:9001 capabilities: | 针对前端JavaScript/TypeScript代码进行安全性审查，检查XSS注入、依赖漏洞、过度权限申请， 输出按严重级别分组的问题清单，每项附带代码位置和修复建议。 input_schema: repo_url: type: string required: true max_len: 512 branch: type: string required: false default: main commit_range: type: string required: false

这里谁都别小看“capabilities”这一段自然语言描述，Agent-Reach的路由匹配很大程度就靠它。这也是我踩坑最多的地方——写得太泛，比如“审查代码”，会导致什么请求都往这里送；写得太窄，比如只写了“XSS检查”，用户问一句“这个依赖版本有没有已知漏洞”，就匹配不到它。最终我用的方法是：写能力描述时默认问自己一句“用户可能用哪几种不同的说法来请求这个能力”，然后把这些说法作为锚点写进去。

2.2 路由匹配的两层机制：语义和规则

Agent-Reach的路由不是单一策略，而是两层协作。第一层是语义匹配，说白了就是让大模型当“路由大脑”——把用户请求变成向量，跟所有Agent的能力描述算相似度，挑出最像的Top-K。这一层的好处是覆盖面广，用户怎么说都能大致找到方向，缺点是相似度不代表真的可用，经常出现“意思像但实际做不了”的情况。

所以第二层是规则校准。在语义选中的候选列表上，再用声明式的规则做一层过滤和加权。比如你可以配置：

• priority_groups：某些Agent在特定关键词出现时直接提升优先级；
• capability_filters：请求里带明确参数时，排除掉input_schema里不满足的Agent；
• cost_weights：多个Agent都满足时，优先选单位成本更低的。

我自己的经验是，语义定方向，规则定胜负。一开始我只用语义匹配，结果路由准确率大概只有七成，总是把“帮我写个Python脚本”这种请求送到“代码解释器Agent”而不是“代码生成Agent”。后来加了一条规则：如果请求里包含动词“写/生成/创建”，优先选capabilities里带“生成”字样的Agent，准确率一下到了九成以上。规则不需要多，但每一条都要能打中要害。

2.3 上下文编排：既要给够，又不能乱塞

多Agent系统里最阴间的Bug往往不是逻辑错了，而是上下文给错了。A Agent生成了一个中间结果B，B在执行时又把A的完整输出拿去用，结果B一边正常工作一遍被A的观点污染，最后生成的东西带着一股“缝合感”。Agent-Reach对上下文做的是按需抽取和分域隔离。

落地时一个很好用的配置是context_policy，让每个Agent声明自己需要哪些上下文字段。请求到达时，Agent-Reach会在全局上下文中按照目标Agent的input_schema去取所需要字段，重组为一份“干净上下文”再转发。比如客服话术Agent只声明需要user_profile、order_status、product_info，它收到的上下文就是这几块，不会看到系统日志和中间过程。

这个设计解决了一个很实际的业务问题。之前我们接教育行业的客户，一个业务链路里要过五个Agent，前两个Agent会产生一些学生成绩相关的中间数据。如果上下文不做隔离，这几个字段会在链路里一路传递，到最后一个Agent还在用，这在合规上非常致命。用Agent-Reach之后，每个Agent的输入输出边界被显式约束，审计的时候也不用靠人肉查链路日志了——直接看context_policy的声明就是合规证据。

2.4 结果聚合策略：单Agent和多Agent返回如何重组

不是所有请求都只命中一个Agent。用户问“我的订单没到，顺便帮我看下这个商品的入库批次”，这条请求至少涉及订单查询Agent和库存批次Agent。Agent-Reach支持把一条请求拆成多个子请求，分别路由到不同Agent，再把结果聚合成一条统一回复。

聚合策略我试过两种：一种是parallel_merge，启用并行执行，适合子任务之间无依赖的场景，速度最快；另一种是sequential_merge，后一个Agent的输入依赖前一个Agent的输出，适合有先后依赖链的任务。配置上就是给请求打一个execution_plan标签，比如：

{ "query_id": "q_20240801_001", "plan": [ {"agent_id": "order-query", "mode": "parallel"}, {"agent_id": "inventory-batch", "mode": "parallel", "depends_on_input_fields": ["order.product_id"]} ], "merge": { "strategy": "llm_merge", "max_tokens": 2048 } }

值得提醒的是，llm_merge这种用模型来合并多Agent结果的策略，效果上限取决于合并模型的水平，但也会带来额外延迟和成本。我建议优先把聚合规则做成模板化的，比如“先放订单信息，再放库存信息，最后给一句判定”，只有模板无法覆盖的自由格式请求才走llm_merge。毕竟Agent-Reach做的不是锦上添花，而是把可靠性抠出来的脏活。

3. 实操落地：从配置到跑通一次完整调用

3.1 最小部署拓扑与前置条件

我不建议一上来就上K8s全家桶，先本地跑一个最小部署把链路打通，比什么都强。Agent-Reach依赖三个部分：核心服务（路由+编排）、一个元信息存储（注册表）、以及你已有的Agent服务。元信息存储用Redis或者PostgreSQL都行，我只用了PostgreSQL，因为还要用它的表结构存路由日志，后面排查问题方便。

前置条件有四样：

• 有至少两个能调通的Agent服务，哪怕是一个返回“hello”的mock都行；
• Agent-Reach核心服务能访问到这两个Agent的endpoint；
• 一个PostgreSQL实例，建好数据库和表结构（项目自带schema迁移脚本）；
• 如果要跑语义匹配，还得准备一个embedding模型接口，我当时接的是项目默认配置的本地小模型，效果够用且不花钱。

这套拓扑跑通后，再考虑往里加注册中心、配置中心、观测系统那些周边设施。很多人第一步就跑偏了，上来先折腾部署脚本和云上权限，结果核心的路由流程一次都没验证过。先把小而全的路径跑通，这是最重要的经验。

3.2 给Agent做“户口登记”

接入Agent-Reach的第一步，是让Agent“报户口”。我仍然沿用配置化注册的方式，在项目里的agent-registry/目录下放置Agent描述文件。一个描述文件对应一个Agent，文件名就是agent_id。比如我要接入一个日志分析Agent，就新建一个log-analyzer.yaml：

agent_id: log-analyzer endpoint: http://127.0.0.1:9010/analyze description: 分析应用日志，识别异常堆栈、错误频率、耗时高峰，输出摘要和趋势判断。 input_schema: log_type: type: string required: true enum: [nginx, java, gateway] time_range: type: string required: false default: 30m capabilities: 日志分析, 异常定位, 错误趋势, 堆栈摘要

这里有个细节：input_schema里的字段最好和Agent实际接口的参数一一对应。有些团队图省事，描述文件写一套，Agent接口收另一套参数，结果第一次联调就404。Agent-Reach本身不做参数透传的强校验（至少在早期版本默认不校验），它按input_schema抽取完上下文后，会把能对齐的字段拼进请求体，不能对齐的字段直接丢弃。所以如果两套对不上，你的Agent会收到一堆莫名其妙的字段，或者干脆收不到该收的字段。

写完描述文件后，通过管理接口或直接重启时导入注册表。我会看注册日志里每个Agent有没有标记为active状态，这一步确认不了，后面所有路由都是空的。

3.3 路由策略和上下文策略的配置

注册完Agent，接下来配路由策略。我用的配置中心是YAML文件热加载方式，改完配置不用重启，Agent-Reach内部会定期刷新。以下是实际跑通过的一份配置节选：

routing: match_top_k: 3 threshold: 0.62 rules: - name: "日志优先归日志Agent" condition: "request_text contains '日志' or request_text contains '异常堆栈'" force_select: log-analyzer - name: "代码生成词优先归生成Agent" condition: "request_text matches '(写|生成|实现|创建) *代码|用.*写.*脚本'" force_select: code-generator - name: "带仓库地址的代码问题优先归审查Agent" condition: "request_text has_url and request_text contains '仓库|repo|PR'" force_select: code-reviewer

注意threshold这个值，它控制语义匹配的准入线，设太高容易空路由，设太低容易乱路由。我一开始设0.75，结果很多请求都“没匹配上”，后来改成0.62才稳定。这个值跟你的embedding模型强相关，没有统一标准，建议上线前拿一两个月真实请求样本先回放一遍，找到召回率和精确率的平衡点。

上下文策略在这份配置里是分开管理的：

context_policies: log-analyzer: allowed_fields: [log_type, time_range, app_name] strip_system_prompt: true code-reviewer: allowed_fields: [repo_url, branch, commit_range] max_context_chars: 4000

max_context_chars这个参数容易被忽略，但很重要。有些Agent接口本身对请求体大小有限制，比如我接的一个自建代码审查服务，单次请求体超过4K字符就直接返回413。Agent-Reach在打包上下时会按这个值截断，可以避免这类问题。截断策略是保留前端字段、优先保开头，因为很多Agent对上下文的“开头部分”最敏感。

3.4 发起一次带路有的请求

一切配好之后，调用就非常简单了。对外的HTTP接口是POST /reach/query，传用户原始请求即可，Agent-Reach替你做路由、拆解和聚合。我用curl模拟一次请求：

curl -X POST http://127.0.0.1:8080/reach/query \ -H "Content-Type: application/json" \ -d '{ "request_text": "帮我看一下nginx日志里最近的异常堆栈", "trace_id": "demo-001" }'

返回结构大概是：

{ "trace_id": "demo-001", "plan": [ {"agent_id": "log-analyzer", "status": "success", "latency_ms": 982} ], "final_result": "最近30分钟nginx日志中发现3处异常堆栈，其中...", "cost_estimate": {"total_tokens": 4120} }

如果命中了多个Agent，返回里会多一个merge_group字段。第一次跑通时，我刻意用了一条会同时命中日志分析和工单分类的请求去测聚合，比如“日志里的报错帮我开一个运维工单”，这时候Agent-Reach会并行调两个Agent，再走一遍模板拼装逻辑。结果串起来之后效果确实像一个人干了两件事，这个感觉还真有点不一样——当然，前提是你表格里写的合并模板得够细，否则也容易露怯。

3.5 链路观测和性能检查

Agent-Reach自带一个轻量的请求日志表，每一条请求的路由命中结果、各Agent延迟、聚合耗时都会落库。我从实际排查效率的角度建议，至少关注三个指标：路由命中率（多少请求有至少一个Agent被选中）、平均路由延迟（大模型语义匹配的那一跳尤其关键）、各Agent的P95延迟。

如果路由命中率低于85%，优先查threshold和capabilities描述写得够不够具体。如果平均路由延迟超过300ms，优先检查embedding模型接口的响应速度，我遇到过本地模型一次推理要1.5秒的尴尬场景，后来换量化版本把延迟压到了200ms以内。

性能调优还有一个冷门但特别经验向的思路：Agent-Reach会给常用请求做结果缓存的选项，但如果你的Agent本身返回结果时效性很强，缓存反而会成为业务杀器。而如果你真的需要缓存，缓存键一定是请求原文+命中Agent列表+字段子集，而不是只按用户问的原话做键——否则一模一样的字，上次路由到A Agent，这次路由到B Agent，你还在傻傻地吃旧缓存。

4. 真实运行中的问题与排查经验

4.1 路由命中了但不是你想要的那个Agent

这是所有Agent-Reach用户第一个遇到的玄学问题。我拿真实的例子说：用户问“帮我总结一下这周的日志错误趋势”，系统没有选中日志分析Agent，反而选中了一个文本摘要Agent。语义匹配一看还挺合理——“总结”和抽象摘要确实相近，但文本摘要Agent根本拿不到日志数据，返回的结果就只有“本周有错误发生，请注意”这种废话。

排查思路分三步。先看Agent-Reach的match_detail日志，里面有每个候选Agent的相似度打分。再检查capabilities描述——我的问题就出在日志分析Agent的能力描述里写了“输出摘要”这几个字，但没写“能拿日志”，导致和请求里的“总结”高度撞车。最后用规则校准，加一条“请求text包含日志或异常时，强制优先选择log-analyzer”，这个问题就再没出现过。

通用的解法叫“规则护城河”——拿一个月线上请求列表，找出所有语义匹配和人工预期不一致的case，每个case提炼一条规则。规则数量不用多，十条左右就能覆盖绝大多数高频错误。核心思路是让语义模型干它擅长的宽泛召回，让规则干它擅长的精确钉死。

4.2 上下文串味和任务冲突

多Agent并行执行时，另一个高发问题是“串味”。两个Agent可能被并行调用，但Agent-Reach内部的上下文池是共享的，如果没隔离好，一个Agent写入的字段可能会被另一个Agent在同一个请求周期内读到。表面现象是：你问“这个代码仓库的PR有什么风险”，代码审查Agent给出的结论里出现了另一个完全不相关Agent对日志的评论。

这道题的根子在context_policy没写严。allowed_fields只写了你允许这个Agent看什么，但没写它不允许写什么。实践上我加了一条自己的约定：所有Agent的output都写入独立命名空间，比如outputs.log_analyzer.raw、outputs.code_reviewer.findings。然后跨Agent引用一律显式声明depends_on_input_fields，比如工单Agent要读日志Agent的输出，必须声明“我的输入来自outputs.log_analyzer.raw”，不能给它全局上下文。

如果你已经出现了串味，不要只靠改代码，先确认是哪个调用链的哪个字段漏了隔离。最有效的做法是把一条出问题的trace_id拿出来，回放Agent-Reach的日志，找到上下文池里那个不该出现的字段，然后顺着它反查到上一个Agent的写入逻辑。这类问题本质上是设计问题，不是性能问题，只能靠明确的边界约束去根治。

4.3 超时、重试与补偿的坑

超时参数是另一个重灾区。Agent服务被大模型调用时，P99延迟很容易到10秒甚至更久，而Agent-Reach默认超时是5秒。如果把超时设成5秒，实际已经有一半请求会超时，Agent-Reach会执行重试，结果一个请求被同一个Agent跑两遍，用户看到的是重复处理、重复扣费。

我的经验是两个方向都要调。第一，把超时时间调到真实场景的P99以上，我用的是15秒，宁可排队等着也不要频繁误判超时。第二，重试策略上必须要配置idempotency_key——Agent-Reach会在重试时带上一个相同的请求指纹，让Agent端自己去判断这个请求是不是之前已经处理过了。如果你的Agent接口没有做幂等处理，至少要在Agent-Reach层面限制同一请求的最大执行次数，我一般设2次，超过就直接降级返回“系统繁忙”，而不是无限重试。

补偿机制更要谨慎设计。我的实践是：如果一个请求里同时路由了A和B两个Agent，A成功、B失败，不要让Agent-Reach自动把A的结果回滚，也不要把A的结果当最终结果返回，而是走一个“部分成功”标记，让上层业务决定是提示用户重试还是展示部分结果。自动回滚听着很安全，但如果你不知道B为什么失败，回滚A其实是在掩盖真正的问题。

4.4 版本演进与兼容性

Agent-Reach上线一段时间后你很快会面临新老Agent共存的局面。比如日志分析Agent从V1升级到V2，接口参数变了，但老请求的编排链路还是按旧参数生成的。我的做法是在注册表里给每个Agent描述文件加一个api_version字段，路由规则里按版本过滤；同时保留旧Agent在线上运行一个过渡期，等所有调用方都切到V2后，再把旧版本下架。

更隐蔽的兼容问题在能力描述升级之后。你优化了一个Agent的capabilities描述，顺带改了input_schema，但Agent-Reach的旧流量还在按老字段拼请求，结果新字段老是空。这个问题的排查方式是周期性比对Agent描述文件变更和线上请求日志，如果发现某些字段名在请求日志里大量为null，优先怀疑schema更新没跟上。

还有一个建议：所有Agent描述文件的变更都要走版本控制，不要直接在生产环境改YAML。项目里应该有一个git仓库，每个Agent的注册文件列一条历史版本，改动就带PR。不是流程繁琐逼死人，而是Agent-Reach的路由行为完全由描述文件驱动，改文件就等于改线上行为，不留痕等于自埋雷。

4.5 避坑清单速查

我把自己总结的坑整理成一张表，查问题的时候先对一遍：

这张表我打印出来贴工位了，每当线上出问题，先对症状后查配置，基本十分钟内能定位方向。

5. 我的体会和一些建议

做Agent-Reach这个项目到今天，我最深的体会是：多Agent系统真正的复杂度和瓶颈，不在单个Agent的质量，而在Agent之间的连接质量。单个模型能力再强，如果找不到正确的队友、传递不了干净的上下文、处理不好链路失败，整体效果就是稀碎。

实际动手前，不要急着把全部Agent一下子接入Agent-Reach。先挑两三个链路最痛的Agent做试点，跑通后再逐步扩大范围。我踩过最烦的坑就是把几十个Agent一次性迁徙到这个平台上，结果所有描述文件都写得迷迷糊糊，路由一塌糊涂，排查的时候连问题出在哪个Agent身上都分不清。小步快跑，先把一条链路彻底做干净，再复制这个模式到其它链路，反而更快。

还有一个建议给准备上生产的朋友：Agent能力描述和路由规则不是写一次就完事的资产，它需要你按真实请求反馈不断迭代。我差不多每周会花半天看一遍路由日志，挑出命中结果不合理的case，要么加规则，要么改描述。坚持一个月之后，路由准确率会明显上一个台阶。这套“运营”动作才是Agent-Reach这类连接层能不能发挥效力的关键。

最后分享一个小技巧：如果你想快速验证Agent-Reach在你场景里的效果，不用等所有Agent都接好，先注册一个mock Agent和一个真实Agent做对照测试。mock Agent固定返回一个预置结果，真实Agent正常执行，然后同时发一批请求，对比两边的路由准确性和结果质量差异。这个五毛钱成本的实验，能帮你判断连接层本身是否可靠，还是问题出在某一个具体Agent的能力上。别一上来就修Agent，先确认路走对了，再修车。