多智能体调度工具Agent-Reach：注册中心、路由与可靠投递实战解析

1. 为什么还要自己造一个多智能体调度轮子

先说结论：Agent-Reach 解决的是多智能体系统里最容易被忽略、却又最致命的一环——任务怎么"够得到"正确的 Agent。

做 Agent 开发的人应该都有这种感觉：单 Agent 跑起来很爽，一个 prompt 接一个工具，逻辑自洽，测试也直观。但一旦上了三五个 Agent，事情就开始失控。Agent A 处理完想交给 Agent B，结果不知道 B 到底在哪、是不是活着、能接什么类型的任务；任务发出去之后没人应答，你不知道是丢了、超时了还是对方崩了；高峰期并发上来了，某些 Agent 被压垮，另一些闲得发慌。

市面上已经有不少成熟的 Agent 编排框架，但说实话，对于大部分中小型项目来说，它们有两个问题：一是太重，动不动就是一整套生态，配置复杂到让人怀疑人生；二是过于绑定某个特定的大模型供应商或 Agent 协议，想接入自己内部已有的系统，反而要写一堆胶水代码。

Agent-Reach 就是在这种背景下冒出来的。它的定位非常明确：不重新发明 Agent，只做 Agent 之间的"交通调度"。它不关心你的 Agent 内部怎么实现，也不限定你用的是 LangChain、AutoGen 还是自己手写的逻辑，它只负责一件事——让任务准确、高效、可追溯地到达应该处理它的 Agent 手上，然后拿到结果再可靠地送回来。

这个工具适合的人也很直接：已经在跑多 Agent 项目、但开始被任务分发和通信问题折磨的开发者；想给团队内部多个 LangGraph/自研 Agent 加一层统一调度的人；以及纯粹对多智能体系统设计感兴趣、想找个轻量级参考实现来读源码的同学。接下来我会把它的架构思路、核心机制、完整实操过程和踩坑记录都拆开讲一遍。

2. 整体设计与核心思路

2.1 三个核心模块：注册中心、调度器、消息路由

Agent-Reach 的整体架构非常克制，核心就三个模块，各自只干一件事。

第一个是注册中心（Registry）。每一个要接入的 Agent 在启动时必须向注册中心报到，报告自己的 Agent ID、能力标签、当前负载状态和健康检查接口。注册中心维护一份实时变化的能力清单，相当于整个系统的"通讯录"。

第二个是调度器（Scheduler）。它负责接收外部任务，解析任务需要什么能力，然后结合注册中心里各 Agent 的实时状态做匹配，决定任务发给谁。调度器不关心任务的具体内容怎么处理，只关心"这个任务该由哪类 Agent 干"和"这类 Agent 里哪个当前最合适"。

第三个是消息路由（Router）。调度器做出决策后，消息路由负责把任务请求投递到目标 Agent，并且保证这个投递动作是可靠的——发出去之后要收确认，收不到要重试，重试失败要回退。路由层还负责把 Agent 的执行结果带回来给调用方。

这三个模块的组合逻辑是：注册中心解决"谁在、谁能干嘛"，调度器解决"该找谁"，路由层解决"怎么可靠地把活送过去再把结果带回来"。每个模块之间通过非常薄的内部接口通信，你可以单独替换任何一个模块的实现，比如把默认的 HTTP 调度换成 Redis Stream 版，不影响其他部分。

2.2 选型背后的思考：为什么坚持轻量级

在设计上有一个很关键的取舍值得聊聊：为什么 Agent-Reach 不去做"编排"而只做"调度"？

"编排"这个词现在被用得很泛，很多框架所谓的编排实际上是写死了一套流程：先调 Agent A，再调 Agent B，然后如果某个条件成立调 Agent C。这种方式对小规模、流程固定的场景没问题，但一旦业务流程经常变，你会发现每次调流程都要改代码，而且 Agent 之间通过全局共享状态耦合在一起，排查问题时根本分不清是谁污染了状态。

Agent-Reach 走的是另一条路：把流程控制权交还给业务方，Agent-Reach 只保证"点到点"的可靠投递。站在业务方的视角，它向调度器提交一个任务，声明"我需要回译能力 + 摘要能力"，然后拿到一个任务 ID，之后可以轮询结果也可以等回调。至于这个任务内部是先回译再摘要还是并行执行，由业务方自己的流程代码决定。

这种设计的直接好处是解耦。Agent 可以独立部署、独立扩缩容，新增一个 Agent 只需要注册，业务侧代码零改动。而且故障边界非常清晰——任务卡住了、超时了，问题只会出现在调度环节或者 Agent 本身，不会出现"流程状态全乱了，不知道谁干的"这种玄学。

2.3 数据模型设计

Agent-Reach 的数据模型很精简，核心就三类对象。

Agent 注册信息包含：agent_id（全局唯一）、name、abilities（字符串数组）、endpoint（调用地址）、priority（这个 Agent 的权重，调度时用于打破平局）、max_concurrency（最大并发数）、heartbeat_ttl（心跳过期阈值）。

任务对象包含：task_id、ability_required（任务需要的能力，可以传多个并按顺序匹配）、payload（任意可序列化的业务数据）、timeout_ms、priority、callback_url（可选，结果会异步回调）、status。

任务结果包含：task_id、status（成功/失败/超时/被回退）、output、elapsed_ms、retry_count、agent_id（实际执行者）。

整个数据流是这样的闭环：

1. 外部调用方 POST 一个任务到调度器
2. 调度器先查注册中心，筛选出具备目标能力且当前并发未满的 Agent 列表
3. 如果列表为空，任务直接进入等待队列
4. 如果有多候选，按权重和当前负载做排序打分
5. 路由层把任务投递到选中的 Agent
6. Agent 执行完 POST 结果回来，路由层标记任务完成并触发回调

这套模型的巧妙之处在于，任务和执行者之间永远不直接绑定。调用方只跟调度器打交道，调度器只跟路由层打交道，路由层才真正接触 Agent。你可以在不通知调用方的情况下把 Agent B 换成 Agent C，只要能力标签一致就行。

3. 核心机制拆解

3.1 Heartbeat 心跳机制与"假死"检测

多 Agent 系统里最让人头疼的问题之一就是 Agent 的"假死"——进程还活着，但已经不能正常处理任务了。比如依赖的外部 API 密钥过期、内存泄漏导致 GC 频繁、网络连接池耗尽。如果调度器只靠"进程是否在跑"来判断 Agent 是否可用，一定会把任务发给这种半死不活的实例，然后白白消耗一次超时窗口。

Agent-Reach 的心跳机制做了两层检测。第一层是常规的心跳上报：每个 Agent 默认每 10 秒 POST 一次心跳到注册中心，心跳体里带三个字段：当前处理中的任务数、最近一次任务完成时间、最近一次健康自检结果。注册中心如果连续 3 个心跳周期没收到某个 Agent 的消息，就把它标记为 unreachable，调度器直接跳过它。

第二层是主动探活。针对那些心跳正常、但任务响应异常变慢的 Agent，调度器会定期向它的 /healthz 端点发探活请求，并且测量响应延迟。这个探活不是简单请求通没通，而是校验 Agent 返回的 JSON 里的status: ready标志。我见过太多 Agent 进程能响应 HTTP 请求但实际上已经卡死的情况，加了这一层之后，假死 Agent 被识别的准确率高了很多。实测下来，探活间隔设为 30 秒、超时设为 5 秒是性价比最高的配置，太频繁会白白消耗 Agent 资源，太稀疏又会在故障期间多发不少无效任务。

3.2 任务队列与优先级调度逻辑

调度器内部维护一个多级优先级队列，分高、中、低三档。每档队列是 FIFO，但调度时永远先耗尽高优先级队列再往下走。这里有一个容易被忽略的细节：高优先级队列不能彻底饿死低优先级任务。Agent-Reach 的实现是给低优先级任务设置一个 aging 机制——任务在低优先级队列里等待超过 30 秒后，自动提升一档。否则一旦系统进入持续高负载，低优先级任务可能永远轮不到执行，这在真实业务里是不可接受的。

调度器每次给 Agent 分配任务前，会检查该 Agent 的max_concurrency。这个并发限制非常重要，原因是大多数 Agent 内部其实是单线程在处理 LLM 调用或者本地模型推理，你强行塞并发任务进去只会导致排队和超时。Agent-Reach 采用"预占用"策略：任务投递前先在该 Agent 的当前负载计数上加 1，收到执行完成通知后再减 1。如果投递后没收到任何响应直到超时，计数也会在超时处理时一并释放，决不让计数泄漏。

任务超时时间建议按 Agent 实际处理耗时的大约 3 倍来设置。比如你测试一个摘要 Agent 处理 5000 字文档平均要 20 秒，那 timeout 至少给 60 秒。给的时间过短的后果是：Agent 明明还在正常工作，但因为一次慢请求就被调度器标记为过载，后续任务被甩到别的实例上，反而造成不必要的迁移。

3.3 能力标签路由：不硬编码 Agent 身份

Agent-Reach 最值得称道的设计之一是基于能力标签的路由，而不是基于 Agent ID 的路由。提交任务的时候你写的是：

{ "task_id": "task-20241112-001", "ability_required": ["text_summarize", "zh_to_en"], "payload": { "content": "..." } }

而不是"把任务发给 agent-01"。调度器收到这个任务后，在注册中心里找同时具备text_summarize和zh_to_en两个能力的 Agent。如果系统里有三个这样的 Agent，就根据当前的负载、历史成功率、权重打分，选出一个最优的。

这种设计带来的直接好处是弹性。我之前的项目里就有这样的经历：初版只有一个合并的 Agent 同时干摘要和翻译的活，后来拆成了两个专职 Agent 并行处理。因为业务侧只声明能力不指名道姓 Agent，拆完以后业务代码一行都不用改，调度器自动把对应任务路由到新 Agent 上。

实现能力匹配的时候要注意一个细节：能力标签最好用统一的命名规范，别出现一个 Agent 注册summarize、另一个注册text_summary这种乌龙。可以做一个简单的词表归一化，或者在注册中心提供一个能力盘点接口，把当前系统里所有能力标签列出来，开发时先查再写。这个看起来是小事，但在 Agent 数量多起来之后，能力标签混乱会直接导致调度器找不到可用 Agent，而排查这个问题又非常费时间。

3.4 重试、回退与结果确认的三重保障

路由层是保证可靠性的关键。Agent-Reach 在消息投递上做了三重保障。

第一重是投递确认。路由层向 Agent 发送任务请求时，如果 Agent 在 5 秒内没有返回一个{"received": true}的确认，路由层就认为投递失败，进入重试逻辑。这个确认跟任务执行完成是两回事：接收确认只代表"我收到了你的任务"，不代表"我已经做完了"。把这两个概念分开非常重要，否则你无法区分"任务根本没送达"和"任务送达了但还没执行完"。

第二重是有限重试。重试策略采取指数退避加抖动：第 1 次重试等 1 秒，第 2 次等 2 秒，第 3 次等 4 秒，最多重试 3 次，每次之间加上 0 到 200 毫秒的随机抖动。抖动的原因很简单：如果一批任务同时失败并同时重试，可能会在同一个时间点集体冲击同一个 Agent，造成所谓的惊群效应。加了随机抖动可以让重试请求在时间轴上散开。

第三重是回退机制。如果 3 次重试全部失败，路由层不会把任务直接标记为失败完事，而是回到调度器重新做一次路由决策。这次决策会额外加一个负向条件：刚才失败的 Agent 在接下来 60 秒内不会被再次选中。如果第二次路由又失败了，任务才最终标记为 failure。实测下来这个"快速失败 + 换人重试"的组合能覆盖大部分临时故障场景，而不会把任务过早地丢给业务方报错。

结果确认方面，Agent 执行完任务后要把结果 POST 回路由层的 /result 接口。这里有一个非常容易踩的坑：Agent 侧的回传地址必须用绝对 URL，不能用相对路径，因为 Agent 和路由层通常不在同一个进程里。我见过好几个团队在自建 Agent 的时候写了fetch('/result')，结果请求直接打到了 Agent 自己的端口上，路由层一直收不到结果，任务全部超时。这种问题查日志的时候特别迷惑，因为你看到的表象是"任务超时"，但实际原因根本不是执行慢。

4. 实操过程与关键实现

4.1 快速部署：先跑通最小闭环

Agent-Reach 的部署非常轻，不需要数据库，也不需要消息中间件，默认实现基于 SQLite 加进程内队列。这决定了它的使用门槛很低：你可以在自己笔记本上几分钟把整套系统跑起来。

前置依赖就两个：Python 3.10 以上，以及一个 HTTP 框架。它内部用的是 FastAPI，所以拉起来非常快。

pip install agent-reach

然后直接启动调度端：

agent-reach scheduler --port 8000

再启动一个自带测试 Agent：

agent-reach test-agent --name demo-agent --abilities text_summarize --port 9000

向调度器提交一个测试任务：

curl -X POST http://localhost:8000/tasks \ -H "Content-Type: application/json" \ -d '{ "ability_required": ["text_summarize"], "payload": {"content": "这里放一段需要摘要的文本"} }'

上面这个任务会返回一个 task_id，然后可以通过GET /tasks/{task_id}轮询结果，或者直接看两个终端里 Agent 侧打印的接收和完成日志。整个跑通的过程不会超过 5 分钟。

回到生产环境，Agent-Reach 也支持把注册中心的状态和数据持久化到 PostgreSQL，把任务队列切换到 Redis Stream。这一层的替换是设计时预留好的，配置里指定storage=postgres和queue=redis即可，核心代码不变。

4.2 核心代码实现：调度器与路由层

下面这段是调度器核心的简化实现，保留了最关键的路由决策逻辑。完整代码在项目源码里，这里只展开思路：

import asyncio import random from typing import Any class Scheduler: def __init__(self, registry, router): self.registry = registry self.router = router async def dispatch(self, task: dict) -> dict: ability = task["ability_required"] candidates = self.registry.find_available(ability) if not candidates: # 进入等待队列，等注册中心有合适的 Agent 上线后再调度 await self.queues.enqueue(task) return {"task_id": task["task_id"], "status": "queued"} target = self.score_and_choose(candidates, task) result = await self.router.deliver( agent=target, task=task, max_retries=3, ) return result def score_and_choose(self, candidates, task): best = None best_score = float("-inf") for agent in candidates: score = ( agent["priority"] * 10 - agent["current_load"] * 5 - agent["recent_failure_count"] * 20 ) # 加一点随机性，避免多个任务同时选中同一个 Agent score += random.uniform(0, 1) if score > best_score: best_score = score best = agent return best

打分公式是我实际调过的：priority * 10保证权重高的 Agent 在稳态下会先被选中；current_load * 5让负载高的 Agent 分数下降，起到自然的负载均衡作用；recent_failure_count * 20的惩罚权重最大，这样最近频繁失败的 Agent 会靠后排。最后一个 0 到 1 的随机项很关键，没有它的话，两个负载完全一样的 Agent 会出现"任务全被第一个选走"的倾斜。

路由层的核心是投递确认加超时控制：

import aiohttp class Router: def __init__(self, confirm_timeout=5, total_timeout=60): self.confirm_timeout = confirm_timeout self.total_timeout = total_timeout async def deliver(self, agent, task, max_retries=3): url = agent["endpoint"] + "/tasks" for attempt in range(max_retries + 1): try: async with aiohttp.ClientSession() as session: # 等待接收确认，超时设置为 5 秒 async with session.post(url, json=task, timeout=aiohttp.ClientTimeout(total=self.confirm_timeout)) as resp: if resp.status == 202: # 已确认接收，等待 Agent 异步回调结果 return await self.wait_result(task["task_id"], timeout=self.total_timeout) except asyncio.TimeoutError: pass # 没收到确认，走重试 except aiohttp.ClientError: pass # 网络异常，同样走重试 # 指数退避加抖动 backoff = (2 ** attempt) + random.uniform(0, 0.2) await asyncio.sleep(backoff) return {"task_id": task["task_id"], "status": "failed", "reason": "max_retries_exceeded"}

注意这里确认码用 202 而不是 200，这是一个很容易被忽略但很重要的约定。202 代表"已接收，处理中"，跟 200 的"已完成"区分开，这样路由层看到 202 就知道要继续等结果回调，而不是傻傻地把 202 当成最终结果返回。如果你让 Agent 返回 200 并且同时在回调里送结果，那又回到了上一个问题：无法区分投递确认和执行完成。

4.3 Agent 侧的接入方式：SDK 还是裸 HTTP 都行

Agent-Reach 对 Agent 侧的接入要求几乎为零，只需要 Agent 提供两个 HTTP 接口：

• POST /tasks：接收任务，返回 202 确认，然后异步处理
• POST /results：处理完成后，把结果回传路由层

官方推荐用 SDK 接入，好处是心跳、并发计数、探活这些逻辑都不用自己写：

from agent_reach.sdk import AgentRuntime my_agent = AgentRuntime( agent_id="summary-agent-01", abilities=["text_summarize", "zh_to_en"], handler=my_summarize_func, # 你自己的业务函数 scheduler_url="http://localhost:8000", ) my_agent.start()

这里的my_summarize_func是一个普通 async 函数，接收 payload 字典，返回一个 JSON 可序列化的结果。SDK 会自动帮你处理心跳上报、接收确认、并发计数、结果回调这些脏活。

如果你的 Agent 不是 Python 写的，或者你已经有一套现成的服务不想改，直接用裸 HTTP 实现那两个接口就行。我在生产环境里就接入过一个用 Go 写的内部服务，只需要写两个 handler，再把注册信息发到调度器的 /register 接口。SDK 不是必需品，协议才是。

4.4 关键配置参数与调参心得

配置项里最值得花时间调的是下面这几个，给出我的实测推荐值和使用场景：

调这些参数的时候要记住一个原则：参数之间是有联动关系的，别只看单个值。比如你把 confirm_timeout 从 5 秒调到 8 秒，那么路由层整体的重试节奏也会变，一个任务从投递到最终失败的时间窗口会被拉长。我踩过的一个具体坑是：一开始把 total_timeout 调大到 180 秒，但没有同步调整健康探活的超时和注册中心下线判定时间，结果出现了一个已经卡死的 Agent 仍然在注册中心里"存活"了将近 5 分钟，期间不断有任务被调度过去然后超时。后来我把三者的时间刻度对齐了：探活 5 秒超时、心跳 10 秒上报、连续 3 次心跳丢失判定下线、total_timeout 120 秒。这样的组合在大多数场景下是自洽的。

5. 常见问题与排查技巧实录

5.1 任务全部超时，但 Agent 日志显示执行正常

这是我在使用过程中遇到的最诡异的问题，日志看起来一切正常：Agent 明明收到了任务、处理完了、也调用了回传接口，但调度器侧一直显示任务处于 running 状态直到超时。

排查过程逐层剥开以后，问题出在回传 URL 配错了。Agent 处理完后调用的是http://127.0.0.1:8000/results，把结果发回给了调度器自己的端口——但调度器的 /results 接口是给 Agent 用的，它的逻辑是验证任务 ID 和 Agent ID 的对应关系。这里的问题不是端口，而是 Agent 侧把回传地址写成了http://localhost:8000但调度器服务实际绑定在http://0.0.0.0:8100，结果回传请求打到了完全不同的服务上，被那个服务的 404 逻辑优雅地吞掉了，Agent 还误以为发送成功。

排查这类问题的核心技巧是：在路由器入口处加一条调试日志，记录每次收到的回传请求的 source IP 和 path。当怀疑回传出问题时，不用猜，直接看这个日志有没有对应的请求进来。如果请求根本没到，问题一定在 Agent 侧的调用链路上；如果请求到了但校验失败，问题在任务 ID 的传递上——常见场景是 Agent 把任务 ID 存在了局部变量里，但处理是异步的，函数返回后局部变量被回收，导致回传时带的是空 ID。

5.2 心跳正常但任务经常被分配给一个高负载 Agent

这个问题的表象是：调度器评分的时候明明有负载更低的 Agent，但任务还是大量涌向某一个实例。看注册中心的状态数据，发现所有 Agent 的心跳都是健康的，也没有报错。

仔细查才发现问题不在评分函数，而在并发计数没有及时释放。Agent 在执行任务时，如果业务代码里出现了异常且没有被正确捕获，Agent 的current_load只会进不会出——因为预占用计数是在"接收确认"时加一的，释放却依赖"结果回调"。一旦异常路径没有走结果回调，计数就永久泄漏了。

当时的修复方案是两层：一是 Agent 侧 SDK 里把业务 handler 包了一层try/except/finally，finally 里无论如何都调用一次 load 释放接口，保证计数收敛；二是调度器侧加了超时强制释放——一个 Agent 的占用记录如果超过了 total_timeout 且还没收到结果，调度器会强制把该 Agent 的 current_load 减一，并记录一次forced_release内部事件。这个事件最好也做成可观测指标，因为如果频繁触发，说明 Agent 代码里有比较大的异常分支没兜住。

5.3 批量提交任务时出现惊群，Agent 被打挂

批量场景下最容易出的问题是：一次提交 200 个任务，调度器并行决策，结果前 50 个任务全部选中了同一个 Agent。因为批量任务刚进来时，每个任务做路由决策互不可见，即使评分函数里带了随机项，第一个任务选中负载最低的 Agent 后，第二个任务看到的负载数据还没来得及更新（计数更新有短暂延迟），于是又选了同一个。

Agent-Reach 的解决方案是给调度器加了一个路由决策锁：并发的路由决策在更新 Agent 负载计数时串行化。同时对批量接口做了一层限制，规定批量提交的任务数量最多 100 个，超过的部分先入队，按批次调度。实测下来这个锁的开销非常小，大概每个决策多 0.5 毫秒，但能完美避免团队群测时的惊群事故。

如果你用的是自定义的批量提交脚本，还有一个配合技巧：提交前先随机打散任务顺序，或者连续拿到多个同样能力标签的任务时手动加一点延迟。这样即使调度器侧少了一层保护，也能显著降低瞬时冲击。

5.4 结果数据太大导致回传超时

Agent 产生的执行结果里如果有大段文本，比如把整篇文章翻译完再回传，结果体可能轻松超过几十 MB。HTTP 回传这种大包体验非常差：序列化时间长、网络传输慢、容易被各种网关卡超时。

我的建议是给 Agent-Reach 加一个结果数据侧通道：结果体超过 1 MB 时，Agent 先把结果写入共享存储（或者一个 MinIO bucket），然后只把存储对象的引用 URL 通过回传接口发给路由层。调用方拿到 URL 后自己去取数据。这个模式做了一次改造之后，再也没有出现过大结果超时的问题。关键是结果对象要有生命周期管理，定时清理，否则共享存储会越堆越满。

6. 多角色使用视角：不同角色怎么用好 Agent-Reach

写到这里有必要分角色说一下 Agent-Reach 在不同场景下怎么被"玩"起来，因为不同的人拿它做的事完全不一样。

架构师视角看重的是它的可替换性。注册中心、调度器、路由层各自是独立的模块，接口薄，任何一层都可以替换成更适合自己基础设施的实现。我见过一个团队把默认的 HTTP 路由换成了基于 gRPC 的双向流，因为他们跨机房部署，需要长连接来控制连接开销。只改了路由层一个模块，注册中心和调度器完全不动。

后端开发视角看重的是接入成本。如果你的公司内部已经有自研 Agent 服务，接入 Agent-Reach 不需要改 Agent 内部逻辑，只要多暴露两个 HTTP 接口、多一个注册调用。我之前把一个已经跑了半年的问答 Agent 接入 Agent-Reach，前后只用了两个小时，其中大部分时间是在读它的接口文档。这个 Agent 原本是散落在业务代码里被各处直接调用的，接入之后所有调用统一走调度器，调用方和 Agent 之间彻底解耦。

数据工程师视角会关心它的可观测性。Agent-Reach 每处理一个任务都会产出结构化日志：任务 ID、起始时间、路由决策结果、目标 Agent、耗时、重试次数、最终状态。把这些日志接入现有的日志平台，做一个简单的看板，就能实时看到系统里哪个 Agent 是瓶颈、哪个能力标签的任务成功率在下降、哪个 Agent 最近在频繁超时。这些数据对容量规划太重要了。我第一次做完这个看板就发现某个摘要 Agent 每周五下午成功率特别低，后来排查出是因为那个时段共享数据库在做全量备份，抢占了大量 I/O，Agent 处理速度骤降。没有可观测性，这种周期性故障可能要过很久才能被偶然发现。

7. 踩坑心得：关于 Agent-Reach 的几个"不建议"

使用 Agent-Reach 这几个月，有一些经验是反直觉的，专门列出来提醒大家。

不建议用 Agent-Reach 去调度模型层面的调用。如果你只是想在一个 Agent 内部做多模型的路由，比如失败时切换供应商，那应该用模型网关，而不是 Agent 调度器。Agent-Reach 的粒度是"一个能独立完成任务的服务单元"，不是"一次模型推理请求"。用错粒度会让你付出不必要的网络开销和复杂度。

不建议让 Agent 之间直接互相调用。Agent-Reach 的设计理念是星型拓扑，Agent 之间不通信，所有任务和结果都通过调度器流转。我看到有人用它的时候在 Agent 内部硬编码了另一个 Agent 的地址，直接调过去了。这个绕过了调度器的能力匹配和负载均衡，实际上等于把系统退化成了点对点硬编码。如果确实需要 Agent 链式调用，正确做法是把链式调用逻辑放到业务方的流程代码里，用调度器依次提交任务。这样链路中的每一步都有可靠的投递保障，也方便追踪问题。

不建议在小规模场景（比如三个 Agent 以内）过早引入调度器。如果你的系统只有两三个 Agent 且调用关系固定，直接写业务代码调用是最简单可靠的。Agent-Reach 的价值在于规模化和动态化，规模没到位的时候，它解决不了你还没遇到的问题，反而多了一层复杂度。这个工具适合的是"已经开始疼"的团队，不是"未雨绸缪"的团队。

不建议关闭路由层的重试机制。我理解有些人担心重试会导致重复执行——比如 Agent 超时的请求其实已经处理完了，只是结果回传超时，重试会造成同一个任务被执行两次。这个问题真实存在，如果你要处理的任务有天然幂等性（纯查询、只读操作），重试很安全；但如果任务有副作用，建议在 Agent 侧实现一个简单的幂等表，按 task_id 去重。但别因此就关掉重试，没有重试的调度系统在真实的网络环境里根本不可用。幂等可以在 Agent 侧解决，丢消息的问题在调度侧无法自行恢复。

根据我的实际使用经验，Agent-Reach 在多 Agent 调度这个方向上确实提供了一个非常务实、克制且好落地的参考方案。它没有野心去覆盖 Agent 的构建、编排、记忆、工具调用这些领域，而是专注把"任务可靠地送到正确的 Agent"这一件事做到极致。对于一个正在被多 Agent 通信问题困扰的团队来说，花一两个小时把它接进现有系统跑一遍，大概率就能判断出这套思路适不适合你。即便最终你没有采用它作为生产方案，它的注册中心加能力标签路由加可靠投递这套设计思路本身，也值得在设计自己的多 Agent 系统时借鉴。