多Agent系统路由与协同：Agent-Reach中间件设计与实践

多Agent系统跑起来之后，真正的麻烦才刚刚开始。Agent之间要互相找服务、要动态获取工具列表、要把任务精确投递给当前还“活着”的那一个……这些单机demo里完全不会暴露的问题，会随着Agent数量增长迅速变成团队的日常噩梦。Agent-Reach就是为解决这类问题而设计的一个轻量级路由与协同中间件：它把所有Agent的信息、能力标签、可调用工具和当前健康状态统一注册到一个中心，通过一组明确的API和SDK，让Agent之间松耦合地发现彼此、交换能力，并让任务请求按照策略找到最合适的执行者。

这篇文章想把整套设计思路、实现细节和我在实际部署中踩过的坑完整写出来。适合已经在做多Agent项目、或者正准备从单体Agent走向分布式Agent团队的开发同学。读完你至少能明白三件事：自己搭一套Agent路由体系要拆哪几层；每个核心组件的选型理由是什么；以及生产环境下最容易踩的几个坑，怎么提前规避。

1. 项目背景与要解决的问题

1.1 多Agent系统里的“找得到”和“连得上”

先说一个我自己带团队时的真实场景。我们当时跑着一组偏业务运营的Agent集群，里面有负责数据查询的、有负责生成周报的、还有负责触发工单流程的。单个Agent都写得挺顺，但只要把它们放到一个环境里，问题就来了：A在生成周报时需要调用B的数据能力，代码里只能写死B的服务地址；B一旦扩容或重启，A就全部超时；C想复用B的某个工具，得去翻B的代码文档，然后自己拼HTTP请求。

这本质上就是两个老问题：服务发现与能力触达。放到Agent语境下，比传统微服务还要多两重复杂性：第一，Agent的能力不是固定接口，而是动态的工具列表，工具参数甚至需要按对话上下文生成；第二，Agent的状态不只是进程活着，还包括它当前是否具备执行某类任务的语义条件，比如某个资料库是否已初始化、某个外呼通道是否已授权。只有把这两层都纳入管理，Agent之间的协作才算真正打通。

我做过一个很简单的类比来解释这件事：你有一整层楼的同事，大家办公桌上摆着不同的专业工具，但互相不认识，也不知道谁手头忙不忙。Agent-Reach做的事情，就是给这层楼装了三个东西——前台登记表（注册中心）、楼层指示牌（发现服务）、值班调度员（路由引擎）。前台记着每个人的工位和能力，指示牌告诉你找谁能解决问题，调度员则根据活儿的大小和每个人的忙闲程度派单。

1.2 为什么选择自研而不是直接上K8s/Consul等

很多朋友第一反应肯定是：服务发现这活K8s和Consul不是早就干了吗？确实，传统基础设施层面的服务发现很成熟，但落地到Agent场景，有几个点始终差着一口气。

拿K8s来说，它确实解决了“这个Pod在不在、要不要转发流量”的问题，但它不关心这个Pod里的Agent当前是否具备处理金融类任务的能力。Consul可以注册服务版本和标签，但标签是启动时写死的，ACTIVATED。没有实现真正的标准化——Agent正在并发的可执行工具集合。所以Agent-Reach并没有想替代这些成熟组件，而是跑在它们上层，单独维护一层“Agent语义空间”，把能力发现、工具绑定、智能路由从基础设施中抽象出来。这样即使底层是普通云主机、裸容器，甚至混合部署，这套路由体系依然成立。

2. 整体架构与核心设计思路

2.1 分层架构：注册层、调度层、执行层

Agent-Reach的架构没有搞得太花哨，核心就是三层：注册层、调度层、执行层。每一层只干一件大事，这样出问题时定位非常快。

注册层负责所有Agent的元信息管理，包括Agent身份、能力标签、工具列表、当前运行状态。这一层必须有强一致性的存储支撑，我们用的是Etcd，后面会细说。调度层是整套中间件的大脑，它接收外部任务请求，解析任务要求的技能标签和参数约束，结合每个Agent的实时状态，给出路由决策。执行层则是每个Agent实例身上的轻量SDK运行时。它负责启动时向注册层上报信息，周期性发送心跳，并接收调度层下发的任务，把真实执行结果回传。

三层之间还有一个不可忽视的约定：调度层不允许直接跨过执行层去操作Agent内部业务逻辑。所有任务都必须走标准化的下发协议，Agent可以根据自身状态决定接受或拒绝。这个设计一开始看起来会多一层消息开销，但换来的是执行边界非常清楚——调度层永远不跟Agent业务逻辑耦合。

如果我们画一条请求链路，大概是这样的：外部请求进来，先打到调度层的入口网关；网关把请求头里的能力标签提取出来，到注册层拉取候选Agent列表和健康状态；调度层跑一遍路由策略，选中一个目标Agent实例；然后通过消息通道把任务投递给该实例上的执行层SDK；执行层反馈ack和结果，调度层做回执记录和重试。每一步都有日志，后面排障会非常方便。

2.2 核心数据模型：AgentProfile 与 ToolBinding

要让注册层和调度层不吵架，数据模型必须先定义清楚。Agent-Reach里最重要的两个模型是AgentProfile和ToolBinding。

AgentProfile是Agent的“户口本”，描述我是谁、有什么本事、现在状态如何。一个典型的AgentProfile长这样：

agent_id:>{ "tool_name": "search_finance_report", "description": "按季度查询企业财务报告摘要", "parameters": { "type": "object", "properties": { "company": {"type": "string", "description": "企业名称"}, "quarter": {"type": "string", "enum": ["Q1", "Q2", "Q3", "Q4"]} }, "required": ["company", "quarter"] }, "binding_agent": "data-svc-01" }

把工具描述标准化之后，一个很大的收益是所有Agent的工具列表都可以被同一个组件消费。也就是说，当一个Agent想要知道自己可以调用哪些外部能力时，不再是找某个具体的人问，而是统一从注册层订阅一份“全量工具菜单”，这个设计在后端接入LLM场景中极其好用。

2.3 为什么选用 gRPC + REST 双通道

Agent-Reach同时提供gRPC和REST两套接口，并不是为了炫技，而是因为使用对象完全不同。

Agent与Agent之间、调度层与注册层之间，讲究低延迟和高吞吐，我们用gRPC。它基于HTTP/2，支持双向流、流式推送，心跳和状态同步都能做成一个长连接，不用频繁握手。尤其是我们要做状态订阅推送时，服务端可以直接把Agent上下线事件推给感兴趣的调度节点，这个能力用REST实现要废很多劲。

REST接口则主要服务三类场景：外部系统对接、前端控制台查看、以及LLM环境。LLM调用工具时最习惯的方式就是给它一个HTTP接口，返回JSON格式的工具描述和调用结果。我们曾经尝试让LLM直接走gRPC，结果提示词工程复杂了不止一个量级，模型经常漏填元数据。后来统一让LLM调度层用REST，内部再自己转成gRPC调用，整个过程稳定得多。

双通道的代价是需要多维护一套协议转换和参数校验逻辑，但对Agent协作这种对接口兼容性要求极高的场景来说，这个成本非常值得。

3. 核心模块设计与实操要点

3.1 注册中心：基于 Etcd 的租约机制

注册层是整个系统的基础，一旦它不稳定，上面的调度全是盲人摸象。我们选Etcd做底层存储，理由很简单：它原生支持租约（Lease）和Watch机制，非常适合做临时节点注册。

每个Agent实例启动后，会先申请一个Etcd租约，周期比如10秒，然后把自己的AgentProfile写入以租约关联的key里。之后每5秒续约一次。如果Agent宕机，租约到期，对应的key自动消失。这就解决了“进程死了但注册表里还留着僵尸节点”的问题。

这里有几个核心参数需要把握好：租约TTL、续约间隔、首次注册超时。我们的经验值如下：

代码层面，用Etcd客户端做注册的核心逻辑并不复杂：

import etcd3 def register_agent(profile: AgentProfile, ttl: int = 10): client = etcd3.client(host="localhost", port=2379) lease = client.lease(ttl) key = f"/agent-reach/agents/{profile.agent_id}" value = profile.to_json() client.put(key, value, lease=lease) return lease def heartbeat(lease): lease.refresh()

别看这段代码短，真正生产化时会遇到很多细节。比如客户端缓存了旧版本状态、Etcd集群节点变更导致连接重建后又丢了租约、多个Agent进程共用同一个agent_id导致互相覆盖。这些问题我都会在第五章一起讲。

3.2 健康检查与可达性探测：主动探测+被动上报

健康检查是路由可靠性的生命线。Agent-Reach用了两种模式互补：被动上报和主动探测。

被动上报依赖每个Agent的心跳和业务探针。SDK除了发送基础心跳之外，还可以由Agent自身主动上报一些语义健康指标。例如：数据库连接池水位是否超过80%、外部授权token距离过期时间是否少于30分钟。这些指标会写入AgentProfile.status，调度层在路由时能直接排除那些“进程活着但实际没法干活”的Agent。

主动探测则是由调度层定期对注册列表里的Agent实例发起探测请求。探测分两种，轻量探测只检查HTTP/gRPC端点是否响应；深度探测则会请求Agent返回一份能力自检报告，里面包含当前加载的工具列表和关键依赖状态。深度探测不能太频繁，我们设置每5分钟一次，同时要求Agent端把自检报告缓存在本地，避免每次探测都触发全量检查造成性能抖动。

主动探测和被动上报之间存在一个优先级设计需要考虑：如果被动上报说Agent正常，但主动探测超时，该Agent会被标记为“怀疑状态”。系统不会立刻摘除它，而是先让它进入隔离观察期，期间不再接收新任务，但允许其完成已签收的任务。这个机制很重要，它能避开生产环境中最常见的“探测端口通、业务逻辑却坏了”的误判。

3.3 路由引擎：标签、负载、粘性的三级匹配

路由引擎是调度层的核心，它决定每个任务请求会被哪个Agent执行。我们实现的是三级匹配策略，简单来说就是：先通过标签缩小范围，再用负载把压力摊开，最后用粘性规则保证链路连贯。

第一级是硬性过滤。请求必须携带能力标签，比如“data.query”。调度层从注册中心拉取全量AgentProfile，过滤出包含该标签、且健康状态为ok的候选集合。如果候选集合为空，直接返回“暂无能执行此任务的Agent”，并附上当前同类或相近标签的Agent列表供调用方选择。

第二级是负载分，每个Agent实例都会周期上报两项指标：当前任务队列深度和CPU/内存占用率。负载分 = 队列深度 * 0.6 + 资源压力 * 0.4，分数越低越优先。这组权重不是写死的，可以通过配置中心动态调整。如果你的Agent全是I/O密集，可以把资源分权重调低，避免频繁切换目标。

第三级是粘性路由。我们维护了一个路由上下文表，key是业务侧传来的会话ID。同一个会话的任务会优先投递给上一次执行成功的Agent，除非它已离线。这样设计是为了充分利用Agent本地缓存的热数据，避免重复初始化上下文。粘性规则在Agent宕机时自动失效，任务会落到其他候选节点。

三级策略的代码逻辑并不复杂，但需要对每个级别的决策都打日志，这是排查“为什么这个任务派给A而不是B”的唯一线索。

3.4 任务下发与回执确认：防止Agent“假死”

任务下发的可靠性，直接决定了多Agent系统的可用性。我们最初的设计是调度层直接调用目标Agent的gRPC接口，简单是简单，但问题也很明显：进程之间网络抖动、Agent内部处理长任务时回调超时、任务已执行完但回执丢失。一旦没收到回执，调度层也无法确定任务到底成功还是失败，只能超时重试，这很容易造成重复执行。

后来我们引入了消息中间件作为任务下发通道，核心流程变成“投递→签收→回执→确认”。具体来说：调度层把任务封装成标准消息发布到目标Agent的主题队列；Agent的SDK消费到消息后，立即返回签收ack，接收确认马上入库；任务执行完成后，再发送包含结果的回执消息；调度层收到回执后写入执行流水表。一旦签收后长时间未收到执行回执，调度层会触发超时查询，主动向Agent询问任务当前状态。

这个设计虽然增加了一份消息开销，但换来的是极强的可观测性。我们甚至能做到任务在任何时刻的三种状态：已投递未签收、已签收执行中、已执行未确认。这套语义在业务出现投诉时，能帮我们非常准确地定位问题环节。

4. 部署与配置实战

4.1 最小可用部署：docker-compose 快速起端到端

纸上谈兵没什么意思，直接上一套最小可用的部署方案。Agent-Reach依赖两套基础设施：Etcd做注册存储，Redis Stream做任务消息通道。如果你想跑最简单的演示环境，docker-compose就能解决：

version: "3" services: etcd: image: quay.io/coreos/etcd:v3.5.12 command: > etcd --advertise-client-urls http://etcd:2379 --listen-client-urls http://0.0.0.0:2379 ports: - "2379:2379" volumes: - etcd-data:/etcd-data redis: image: redis:7.2-alpine ports: - "6379:6379" agent-reach-scheduler: image: agent-reach/scheduler:0.9.2 environment: ETCD_ENDPOINTS: "etcd:2379" REDIS_ADDRS: "redis:6379" ROUTE_WARMUP_SECONDS: "30" ports: - "8080:8080" - "9090:9090"

执行docker compose up -d之后，Etcd和Redis起来，调度器就可以连上基础设施。接着你需要在Agent侧部署SDK。SDK启动时会自动注册到Etcd，所以你会看到调度器的控制台上陆续出现Agent节点。

这套最小环境跑通之后，我建议从经验上别急着上生产配置，先把一个模拟Agent和一个模拟调用方的demo跑通。确认能力标签匹配、任务签收回执、Agent下线摘除这三个核心流程符合预期后，再考虑加真实业务Agent。

4.2 关键参数调优清单

很多问题不是架构错了，而是参数没调对。我把Agent-Reach在生产环境里需要重点关注的配置参数整理成一个清单，每一项都有推荐值和原因。

特别提醒一下，routing_cache_ttl这个参数是最容易引发“看起来路由错了”的元凶。它的作用是让调度层不用每次请求都去查Etcd，缓存30秒内的Agent列表。但你更新了AgentProfile后，调度层最长可能要30秒后才感知。排查路由问题时，永远先把缓存因素排除。

4.3 Agent 接入 SDK 的集成步骤

Agent接入SDK的流程我已经简化到了四步，内部团队的新手通常十分钟内能跑通第一个用例。

第一步，安装SDK依赖：

pip install agent-reach-sdk

第二步，初始化SDK并传入Agent身份信息。这里最关键的是把自己的能力标签写准，宁可少写也不要乱写。写多了会被路由到不擅长的工作，写少了只是失去部分任务机会：

from agent_reach_sdk import AgentRuntime runtime = AgentRuntime( agent_id="data-svc-01", agent_name="数据查询助理", capabilities=[ {"tag": "data.query", "weight": 90}, {"tag": "data.explain", "weight": 60}, ], etcd_endpoints="localhost:2379", ) runtime.connect()

第三步，注册工具函数。工具函数就是Agent对外暴露的业务方法，需要按照ToolBinding的标准格式声明。SDK会自动把函数转换成工具描述，并同步到注册中心：

@runtime.tool( name="search_finance_report", description="按季度查询企业财务报告摘要", parameters_json="""{ "type": "object", "properties": { "company": {"type": "string"}, "quarter": {"type": "string"} }, "required": ["company", "quarter"] }""" ) def search_finance_report(company: str, quarter: str): # 内部逻辑 return fetch_report(company, quarter)

第四步，启动任务监听循环。这个循环会消费队列中的任务消息，执行后回传结果。我们建议监听循环在独立线程中运行，避免阻塞Agent自身的主流程：

runtime.start_listener()

集成完成之后，建议做一个注册状态自查。检查Etcd对应key是否存在、工具列表是否已同步、通过调度层API能否检索到该Agent。这四步做完，你的Agent就正式进入Agent-Reach体系，可以被其他Agent或外部系统发现了。

5. 常见问题与排查技巧

5.1 路由到已下线节点：缓存与租约不同步

生产环境里我们收到最多的反馈就是“任务被路由到了一个已经不存在的Agent”。第一反应往往是调度层出了bug，但实际排查下来，一半以上的情况都是缓存与租约状态不同步造成的。

具体原因有两种。一种是路由缓存TTL还没过期，调度层拿着旧列表直接投递任务，而目标Agent已经主动摘除了注册信息；另一种是Etcd的Watch事件推送存在延迟，甚至因为网络分区导致调度层没有收到节点下线事件。解决办法分两步：首先把路由缓存的TTL从30秒降到10秒，牺牲一点Etcd查询压力来换更快的失效感知；然后调度层在投递任务前增加一个“投递前验证”步骤，如果目标节点的租约已不存在，马上从候选列表剔除并重新路由，这个验证可以作为兜底逻辑保留。

5.2 高并发下注册风暴：批量刷新与指数退避

有一段时间我们的Agent集群规模过千，每次发版重启都会出现Etcd写入失败的状况。后来登录到Etcd节点看监控，发现同一时刻所有Agent都在重新注册，相当于把注册中心当成热点打。这就是典型的注册风暴，越失败越重试，越重试越拥堵。

解决方案不复杂，核心是给注册流程加上随机扰动和指数退避。每个Agent实例在启动注册前先等待一个随机时间，范围0到5秒，把瞬时并发错开。注册失败后的重试策略使用指数退避：第一次1秒，第二次2秒，第三次4秒，最多不超过30秒。另外我们在SDK内部做了批量上报优化——同进程内多个Agent实例可以共用一条连接发送批量心跳，这条优化在容器环境中能显著降低Etcd的连接压力。

5.3 工具调用超时但Agent正常：执行链路与探测链路混用

有一次用户反馈某个工具调用经常超时，但我们去看Agent的健康状态一直是ok，负载分也很低，怎么看都不像有问题。后来追踪单个任务日志，才发现这个Agent注册的gRPC地址暴露在业务内网，而任务消息走的是Redis Stream通道。gRPC通道和Redis通道刚好处于两条不同的网络链路上，Redis侧运行正常不代表gRPC侧也通畅。

这个坑的本质是健康探测结果被误用到了其他链路上。Agent-Reach的健康检查只代表探测端点所在网络路径的健康程度。如果把“Agent健康”等同于“所有链路健康”，就必然会出现误判。解决办法是在AgentProfile里补充链路隔离标记：哪个地址走内部集群、哪个地址走公网、哪个地址走消息通道，调度层在路由时优先选择与调用方网络路径一致的Agent节点。

5.4 日志排障三板斧：追踪ID、状态快照、路由决策日志

多Agent系统的排障要是不靠日志，基本只能靠瞎猜。我把我们沉淀下来的排障三板斧分享出来，每一条都是真金白银换来的经验。

第一板斧是链路追踪ID。所有从外部进入的任务请求，在调度层入口就生成一个全局唯一的trace_id，附带在整个调用链路上。每个Agent在执行任务时，必须在业务日志里输出这个trace_id。没有它，跨Agent排查就是一场灾难。

第二板斧是注册状态快照。我们开发了一个管理API，可以随时导出一份当前所有Agent的注册快照，包括状态、健康度、最后心跳时间、工具列表版本。出问题的时候先拉快照，再对比当前实际进程状态，能快速区分“是注册层的问题还是路由层的问题”。

第三板斧是路由决策日志。调度层每次做完三级匹配，都输出一条结构化日志，里面包含原始请求标签、候选集合、每项负载分、最终选择及原因。这条日志是回答“为什么派给它”的最直接凭据。我曾经因为没记路由原因，和业务方对线了两小时，后来补上这个日志，同类问题三分钟解决。

6. 扩展方向与个人实践体会

6.1 后续演进可能性

Agent-Reach目前的版本已经能满足大多数多Agent协作的日常需求，但关于下一步的演进，我心里有几个方向。

第一个是把语义路由做得更智能。目前的标签匹配还是偏人工式管理，谁有什么能力需要人工打标签，人工维护权重。如果能把Agent能力描述嵌入向量，让路由请求也用自然语言表达，就能实现真正的语义匹配。这个方向我们已经开始做了，底层接入向量数据库，路由策略从“找到最匹配标签”升级成“找到语义最相近的能力描述”。

第二个是支持多环境隔离与灰度发布。Agent集群往往同时存在开发、测试、生产多个环境，Agent-Reach需要更完整的环境隔离机制。比如允许同一个agent_id在多个环境各有一个实例，调度层按请求头里的环境标识决定路由目标，而不是让不同环境互相抢注册权。

第三个是增强可解释性。调用方可能不仅需要知道“任务被路由到了哪里”，还需要知道“为什么被路由到那里”。我们计划在路由结果中附带完整的决策依据链表，包括候选过滤原因、负载分计算明细、粘性命中情况，让整个路由过程对业务人员同样透明。

6.2 实际操作中的个人体会

最后说说我自己的体会。做Agent-Reach这一年，给我最大的启发是：多Agent协同难的不是某个Agent多聪明，而是它们之间能不能可靠地找到对方、合理地分配工作、诚实地报告状态。

踩过的最大的坑，其实就是我之前提到的“Agent健康并不等于链路健康”。很多同学包括我，一开始都希望用一套布尔状态做完所有判断，后来发现分布式系统里根本没有那么简单的“健康”。和这个类似的坑还有很多，但如果只挑一句话总结，我会说：把Agent之间每一次交互都当成可能失败的分布式调用去设计，而不是让步于单机思维。

如果你也正在做多Agent体系，希望这篇分享能帮你把服务发现、工具路由和健康检查这几张网提前织好。毕竟等到Agent数量真的上来了，再去回头补课，成本就完全不是同一个量级了。