最近我一直在搞多 Agent 协作单 Agent 跑起来很顺一旦超过三个问题就全冒出来了A 不知道 B 能干什么B 忙得半死 C 却闲着消息传来传去最后卡在谁那里都说不清。后来我把整个调度层换成了 Agent-Reach 的思路整套系统的协作方式才算理顺。这篇东西就从 Agent-Reach 这个项目聊起讲讲它到底解决了什么问题、我是怎么落地使用的以及在这个过程里踩过的那些坑。如果你也在用 AutoGen、MetaGPT 这类编排框架或者正准备自研一套 Agent 平台这篇文章应该会有用。先说结论Agent-Reach 本质上是给多智能体系统加一层“触达层”。在单个 Agent 内部模型能力是核心一旦上升到多个 Agent 协作核心就变成了“谁能处理这件事”“怎么找到它”“消息用什么样的方式交给它”。Agent-Reach 要解决的正是这一层它把写死的调用关系改造成动态的能力发现与路由触达让新 Agent 进来不用改旧代码旧 Agent 下线也不会把整个链路拖垮。1. 先拆清楚Agent-Reach 到底解决什么问题1.1 多 Agent 协作里最坑的不是模型能力我最早做多 Agent 时用的是最朴素的方案给每个 Agent 起个名字然后在代码里写死“Agent A 调 Agent B”。比如 A 负责理解需求B 负责写代码C 负责测试那我就写 A 完成后调用 BB 完成后再调用 C。这套东西跑 demo 完全没问题但一旦加入第四个 Agent或者想把某个 Agent 换成更强的新模型代码就得改一圈。更麻烦的是容错。B 一旦忙着处理长任务A 根本不知道消息直接发过去就超时了C 想接过一部分活但调用链已经写死在 A - B - C 里插都插不进去。这种情况特别像一个小团队里每个人都只认识固定的同事完全不管团队里其他人当前忙不忙、有没有新增人手。你让 C 顶上去C 根本没被引荐给团队其他人不知道 C 的存在自然也就不会去找它。Agent-Reach 这批方案的核心思路就是把“调用写死”变成“能力注册”。每个 Agent 启动时把自己的能力、当前状态、负载情况上报到一个注册中心任何需要协作的 Agent 只需要说“我需要一个能生成代码的角色”由框架去决定找谁、怎么发消息。这样 A 就不再依赖具体的 B 或 C只依赖一个能力池。1.2 Agent-Reach 的定位把“调用写死”变成“能力触达”我给 Agent-Reach 的定位是三层结构注册、匹配、触达。注册层负责收集所有 Agent 的能力描述和运行时状态。匹配层接收调用方的意图从注册表里挑出能处理这个意图的候选 Agent。触达层负责把请求按规则发出去并同步等待结果或把任务放进队列异步消化。也就是说调用方不需要知道“谁”来做只需要告诉框架“做什么”。这个转变看着简单实际影响非常大。以前我在代码里写await agent_b.handle(task)相当于我指定了执行者。后来改成result await reach.invoke(intentprepare_code, payloadtask)执行者在每次调用时动态选择。当 C 的负载明显更低时路由层会自动把任务分给 C而不是继续往 B 上压。这套机制在 Agent 数量超过五个之后优势会越来越明显。有人会说这不就是服务发现加负载均衡吗微服务里的注册中心早就有了。对思路确实是借的但 Agent 场景有个显著区别微服务的接口是严格定义好的一个订单服务就是处理订单Agent 的能力是模糊的、语义化的同一个请求可能对应好几个 Agent匹配质量直接影响任务的成败。所以 Agent-Reach 真正的难点不在注册和传输而在“意图匹配”和“能力描述”。1.3 为什么不能直接用消息队列凑合我身边有人问过直接用 RabbitMQ 或者 Kafka 不就行了吗生产者发消息消费者接收天然就是解耦。消息队列解决的是“消息可靠地从 A 传到 B”它不关心 B 到底能不能处理这条消息。Agent 场景里你发了一条“帮我生成测试用例”的请求如果队列里有写代码的 Agent、有做数据分析的 Agent、有翻译文档的 Agent队列自己不知道应该把消息给谁。还需要一个脑子来做匹配这个脑子就是 Agent-Reach 路由层。所以我实际落地时并没有用 Agent-Reach 去替代 RabbitMQ而是让 Agent-Reach 的 Router 作为“语义路由大脑”底层消息传输依然用 Redis Stream必要时也可以换其他消息中间件。框架的价值永远在决策层不在管道层。2. 核心架构拆解注册、路由、触达三层2.1 整体拓扑与模块职责我实现的 Agent-Reach 拓扑由四个部分组成。注册中心Registry负责维护 Agent 列表保存每个 Agent 的能力描述、当前状态、心跳时间。我这里用 Redis 做存储每个 Agent 注册时写入一个 HashKey 是 Agent IDField 包含能力描述和状态。选 Redis 而不是 etcd是因为多数团队已经部署了 Redis不需要额外引入一套组件对 Agent 协作这种秒级一致性的场景Redis 完全够用。路由大脑Router是核心它接收“意图触达请求”按照我预定义的匹配流程选出候选 Agent。Router 保持无状态可以横向扩展多个 Router 实例共用同一个注册中心。消息总线Transport负责实际传递消息。我这里用的 Redis Stream每个 Agent 有一个独立的 StreamRouter 往目标 Agent 的 Stream 里推消息Agent 侧用消费者组消费。网关 SDK 是每个 Agent 进程里嵌入的客户端。Agent 通过 SDK 完成注册、心跳、消费消息、回传结果。SDK 还负责暴露出本 Agent 的“能力上下文”让注册信息不是一张死的静态表。这一套结构里最容易设计过重的是 Router。我一开始还给 Router 加了状态持久化、任务追踪后台、重试死信队列结果第一版跑下来发现全是负担。Agent 协作场景里大部分消息时效性很强过了几十秒重试价值就不大了真正需要死信队列的任务极少。第二版我砍掉了死信队列只保留“重试 超时失败回传错误”两条路径系统一下子清爽很多。2.2 能力声明触达协议里的第一等公民Agent-Reach 里最值得花时间打磨的是能力声明。我见过很多团队在这个环节偷懒注册信息里就写一行“可以处理代码任务”结果路由层完全分不清该发给谁。我自己设计能力声明时坚持几个原则能力名称必须是一个动作短语描述必须包含输入、输出、边界每个能力要配上具体的调用示例。以我搭的三个 Agent 为例agent-researcher负责搜集信息、整理资料能力描述写成“根据给定的研究主题检索并整合公开信息输出带来源链接的摘要报告”。agent-coder负责生成代码描述写成“根据自然语言需求生成可运行的 Python 或 TypeScript 代码模块输出包含完整函数定义、依赖列表和单元测试”。agent-reviewer负责代码审查描述写成“对传入的代码段进行静态审查指出潜在 bug、安全隐患和风格问题按严重程度输出分级建议”。注意描述里的每一个短语都是在给路由层“画靶子”。“可运行的”“带来源链接”“按严重程度分级”这些限定词会在后面做语义匹配时大幅提高准确率。如果只写“擅长写代码”那 researcher 和 reviewer 都可能被误召因为它们也在“处理代码相关内容”。能力声明还应该包含一个默认的拒绝条件就是“什么情况下不要选我”。我在注册 Schema 里加了一个exclude字段比如 coder 的排除条件是“仅需要搜索结果而非代码实现”这条规则帮我挡住了大量错误路由。2.3 路由策略相似度匹配只是第一关规则兜底才是关键Router 收到一条意图请求后我做了两层筛选。第一层是召回。我用本地向量库存了全部能力声明的 Embedding用户请求进入后也转成向量算余弦相似度召回 Top 10 候选。这一步负责“广撒网”避免后面规则把实际合适的 Agent 挡在外面。第二层是过滤。这是我自己加的一套规则引擎也是我认为 Agent-Reach 项目里最有价值的部分。过滤规则包括能力类型校验请求里声明了capabilitygenerate_code那就只保留下游能力池里名称匹配的 Agent。负载过滤当前pending_count超过上限的 Agent 直接剔除。冷却过滤刚刚处理过失败任务的 Agent 进入 30 秒冷却期不让它立刻被再次调度。上下文过滤多轮会话中如果上一轮已经指定了某个 Agent 并在会话上下文里记录了“preferred_agent”这一轮优先沿用避免同一个会话来回切换执行者导致人格分裂。我多次提到“为什么要规则兜底”因为 Embedding 相似度是个概率结果它可能达到 0.95 也可能只有 0.6而 Agent 协作场景对确定性有要求。比如一个意图“把这段代码重构一下”和“把这个接口的 bug 修一下”语义上相近实际需要完全不同的 Agent。单纯靠向量匹配大概率翻车规则里就得加关键词约束和 Schema 校验。这一层跑完之后如果候选只剩一个直接触达如果多个按加权负载分配零个就直接回给调用方一个友好错误“当前没有 Agent 能处理该意图请检查能力声明或调整请求描述”而不是让调用方干等超时。2.4 超时、重试与降级策略Agent 协作里的超时设置直接决定用户体感。我把一次触达的全流程分成三段调度耗时、队列等待耗时、执行耗时。调度通常发生在几十毫秒内队列等待取决于目标 Agent 的当前负载执行耗时完全是模型推理和工具调用的时间这最不可控。在实际项目里我设置的全局超时是 60 秒内部再细分调度 1 秒队列等待 10 秒执行 60 秒。为什么执行给 60 秒因为我用的代码生成模型经常要执行工具脚本一次完整操作耗时经常会到 30 秒以上如果只给 20 秒超时稳定失败。重试策略我压得很保守。第一版我写了三次重试结果遇到 Agent 集体变慢的时候重试请求把队列彻底堵死。后来改成最多重试一次且只允许在“调度失败、没找到 Agent”时重试一旦消息已经进入执行环节就不再重试直接超时上报。执行中的重试意义不大模型状态很难回滚重复执行反而浪费成本。降级策略是最后一道保险。如果意图触达失败调用方可以选择降级到“预设兜底 Agent”也就是在配置里显式指定的备用服务。我在测试阶段遇到过 coder 挂掉的情况这时候请求会转向一个能力弱一点但仍在维护的旧版代码 Agent保证链路不断。降级 Agent 必须有明确标记不能默认开启否则它会悄悄接收大量不擅长的工作把质量拖垮。3. 实操实录三个 Agent 通过 Agent-Reach 互相协作3.1 环境准备与项目初始化我建议从头实践 Agent-Reach 时环境不用太复杂。我本地用的是 Python 3.10、Redis 7Agent-Reach 运行时本身依赖比较少核心就两个redis客户端库和sentence-transformers模型库。项目目录结构我按角色分agent-reach-lab/ ├── router/ # 路由大脑服务 │ ├── main.py │ └── routes.py ├── agents/ │ ├── researcher/ │ ├── coder/ │ └── reviewer/ ├── sdk/ # 本地 SDK 封装 │ ├── client.py │ └── schema.py └── configs/ ├── agent_reach.yaml └── routing_rules.yaml很多第一次接触这类框架的人会把全部逻辑堆在一个目录里一锅乱炖。我建议从一开始就把 Router 和 Agent 分开放因为它们的生命周期完全不同Agent 会频繁替换升级Router 则要保持稳定。安装依赖我直接写进了requirements.txtredis5.0.0 sentence-transformers2.2.0 pyyaml6.0 pydantic2.0这些都是基础依赖不用额外装重型框架。如果后续需要复杂观测再引入其它工具也来得及。3.2 注册与能力声明配置每个 Agent 启动时需要读一份自己的配置文件。我以 coder 为例配置文件长这样agent: id: agent-coder-01 name: code-executor transport: type: redis_stream address: redis://127.0.0.1:6379/0 stream: stream:coder group: reach_runtime heartbeat: interval: 15 ttl: 60 limits: max_pending: 3 cooldown_after_error: 30 capabilities: - name: generate_code description: 根据自然语言需求生成可运行的 Python 或 TypeScript 代码模块输出包含完整函数定义、依赖列表和单元测试 input_schema: task_description: type: string required: true output_schema: code: type: string dependencies: type: array tests: type: string - name: refactor_code description: 对已有代码进行结构优化和可读性改进不改变外部接口行为 exclude: - 仅需要定位 bug 并修复的场景我特别想强调max_pending: 3这个参数它是一个 Agent 能承受的最大并发任务数超过之后新任务不会直接推给这个 Agent而是排队或在 Router 侧选择其它候选。第一次实践时我把它设成了 10结果单个 Agent 同时处理十个模型调用卡到谁的消息都处理不了。后来压到 3 才正常。注册动作在 SDK 里是这样触发的from agent_reach_sdk import ReachClient config_path configs/agent_reach.yaml client ReachClient(config_path) client.register() client.start_heartbeat(interval15)注册成功之后Router 端就能在注册表里查到这条记录了。心跳是关键Agent 进程如果非正常退出注册中心要靠过期时间把僵尸记录清掉。我设置了 15 秒一次心跳、60 秒过期也就是容忍 Agent 约 45 秒的瞬时失联。3.3 意图触达的完整链路与核心实现三个 Agent 都注册完毕之后调用方就可以发一个意图请求。比如我想让研究员 Agent 先搜资料然后把资料交给写代码 Agent。调用方的代码from agent_reach_sdk import ReachClient client ReachClient(config_pathconfigs/agent_reach.yaml) result await client.invoke( intent根据主题整理一份带来源链接的摘要报告, payload{topic: 大规模语言模型评测方法, max_sources: 8}, timeout60 )这行代码背后是完整链路SDK 把意图发送到 Router 的 HTTP 接口Router 查注册表、算语义相似度、套过滤规则选中了 researcher然后把请求写入stream:researcher同时给调用方一个待完成的request_id。researcher 那边的消费者取到消息、调用模型、生成报告把结果写回stream:resultSDK 再把结果返回给调用方。如果这里只用 HTTP 同步调用更简单但并发量一上来长任务阻塞就非常难受。Redis Stream 的好处是 Consumer 可以按组消费同一时刻多个 Agent 实例可以一起处理消息天然支持横向扩容。Router 里匹配部分的简化代码def route_intent(intent: str, payload: dict, context: dict): # 第一步向量召回候选 candidates vector_store.search(intent, top_k10) # 第二步规则过滤 matched [c for c in candidates if rule_filter(c, payload, context)] if not matched: raise NoCapabilityError(no agent can handle this intent) # 第三步负载排序选最空闲的 matched.sort(keylambda c: c[pending_count]) target matched[0] # 第四步触达 return transport.dispatch(target[id], intent, payload)实际生产版本的代码会更多比如记录每次调度的request_id、日志结构、失败计数器但核心就是这四步。第三步的负载排序我建议用pending_count优先而不是“最近最少使用”。Agent 场景里一个 Agent 的空闲程度和任务耗时关系很大用最简单的队列长度指标就能达到不错的效果。3.4 容量与超时参数的估算思路调参这件事最容易玄学化我分享一套自己觉得还算靠谱的估算流程。假设一个代码 Agent 平均处理一个任务耗时 8 秒我的目标吞吐是每分钟 5 个请求。那在理想情况下至少需要5 * 8 / 60 ≈ 0.67个并发消费者向上取整就是 1 个并发能稳住但模型推理耗时有波动我一般再乘 2 到 3 的冗余系数所以生产环境我用 3 个并发。对应到配置里就是给这个 Agent 的 Stream 消费者组启动 3 个 Worker。max_pending可以粗略设成并发数 × 允许排队任务数比如并发 3允许每个 Worker 排队 1 个任务那max_pending就设为 3。超时时间反过来算。容忍等待上限是 30 秒那么超时 ≥ 队列等待 执行耗时 调度损耗队列等待正常情况下很低但如果任务积压可能到几十秒。所以我直接设 60 秒全局超时给足余量。重试不建议超过 2 次因为每一次重试都在把任务重新丢进队列会让积压雪上加霜。数据层面我还用 Prometheus 风格计数器记录了一个关键指标队列平均排队时长。这个值一旦稳定超过 5 秒就该扩容 Agent Worker 或调整路由负载权重了不用等到用户报障。4. 实际踩过的坑与排查实录4.1 症状Agent 互相找不到注册信息变成了“僵尸”第一次联调时coder 一直报错说“目标 Agent 不可达”。我去 Router 的注册表里查发现记录还在状态却已经失效。后来看了注册中心的 TTL问题出在 Agent 进程执行模型推理任务时阻塞了 90 秒心跳线程也被模型调用阻塞导致心跳 15 秒发不出去Redis 里的记录自动过期了。这个坑非常典型。修复方式有两个一是心跳必须放在独立的守护线程或进程里不能和业务执行抢线程二是 TTL 要大于单次任务的最大耗时我后来把 TTL 从 60 秒调到了 120 秒才算稳下来。排查时最快的办法是敲一行命令看注册表redis-cli HGETALL reach:registry:agent-coder-01如果last_heartbeat字段的更新时间和当前时间差了很多说明心跳链路已经断了。4.2 症状触达超时结果发现是队列在排队有一次压测时reviewer 的触达请求大面积超时。我一开始怀疑是 Router 卡了查了一圈发现 Router 毫秒级返回任务已经入队但stream:reviewer的 pending 数在持续增长消费者没来得及消费。原因是 review 任务特别耗时平均一次要 30 秒而我只给 reviewer 开了 2 个消费 Worker。消息入队速度超过了消费速度队列越积越长触达超时当然随之而来。解决思路分两步先临时扩容到 6 个 Worker 把积压消化掉再把max_pending、Worker 数量和预期耗时写入配置形成一个动态监控项。我在运维面板里盯的就是queue_length和pending一旦持续超过 5 就意味着容量规划落后了。4.3 症状路由把任务发给了错误的 Agent这个坑最有教育意义。我一开始把能力描述写得很宽泛比如 coder 的refactor_code写成“对代码进行优化”结果路由层经常把一个“修复内存泄漏 bug”的任务发给 researcher因为“优化”和“修复”在语义空间里距离很近而 researcher 的描述里有“整理信息”向量匹配时产生了误判。后来我给能力描述加了强约束refactor_code的输出必须是一个代码变更 diffexclude里写明“仅涉及 bug 定位而不涉及代码重构的任务不要选我”。加完规则后误路由率立刻下降。这个案例说明向量模型的召回能力再强也扛不住“能力边界不清晰”的注册声明。Agent 的能力声明应该像写接口文档一样严谨边界比能力本身更重要。4.4 症状多轮协作时上下文被“洗掉”了三个 Agent 协作时还出现过严重的上下文丢失。第一轮 researcher 生成了报告第二轮 coder 接到任务时对报告内容一无所知只能重新问调用方要一遍资料。一开始我以为消息传输把 body 丢了查了日志发现传输完整纯粹是调用方没有把上一轮结果带进下一轮。解决办法是在触达请求里增加一个context结构包含conversation_id和summarysummary 是上一轮结果的浓缩摘要。Router 调度时会把context一并写入目标 Stream目标 Agent 消费时自行决定要不要使用摘要。这个方案比直接传完整历史记录轻量很多也避免了 Token 开销失控的问题。我在多轮场景里的经验是不要试图传全部历史每轮结束生成一个摘要下一轮只带摘要Agent 协作质量和响应速度都能兼顾。4.5 排查速查表症状常见原因排查入口解决建议Agent 互相找不到心跳过期、注册记录失效Redis 注册表 HGETALL心跳独立线程、延长 TTL触达超时消费 Worker 不足、队列积压Stream 队列长度和 pending 数扩容 Worker、压测前先估算容量路由分错能力声明边界模糊、向量误判查看 Router 日志中被排除的候选收紧描述、加 exclude 规则上下文丢失调用方未传 summary检查下游消费的消息 body增加 context 摘要机制重试风暴失败任务反复重试监控重试次数和消息重复率限制重试次数执行环节失败不重试这张表是我实际排查时反复对照的清单每次出现新问题就补一行。Agent 系统的故障排查和传统分布式系统非常像关键是把链路每一段的日志和指标埋好否则出了问题只能靠猜。5. 关于 Agent-Reach 的几点补充心得跑通整套 Agent-Reach 之后我最大的体会是多 Agent 系统的复杂度其实是提前埋进去的。很多人一上来就堆十个 Agent、几十个 Prompt、复杂的工具调用结果调度和通信一团糟。先把“触达”做扎实注册、路由、超时、降级这些基础能力稳住了再加业务能力反而走得最快。在 Agent-Reach 的落地过程中比起模型选型我更建议大家把时间花在写能力声明和设计路由规则上。能力写得模糊后面所有 Agent 都会跟着倒霉路由规则做得糙向量匹配再准也会被误判。我甚至觉得Agent 领域的“接口文档”就是从能力声明开始的谁把这层文档写得好谁的系统协作质量就差不了。如果你现在正准备开始做多 Agent 项目或者已经被现有编排框架的各种消息机制搞到头疼建议先别急着换框架试着在自己的代码里加一个轻量触达层。用 Redis Stream 做传输用 Embedding 加规则做路由几百行代码就能搭出 Agent-Reach 的核心体验。跑通第一个三 Agent 协作场景后再回头优化细节你会对整套系统有一个完全不同的理解。