“Agent”这个词这两年快被说烂了。从AutoGPT到各类MCP、工作流编排框架大家都在谈智能体但真落到业务里你会发现一个特别容易翻车的环节你的智能体跑起来了但你怎么知道它现在活着、在哪儿、能不能被调用、负载怎么样你用OpenAI的API不会操心这个问题但自建Agent集群时这套“服务发现健康检查路由调度”的东西基本上得从头造一遍。我最近在内部把这套基础设施做完了项目代号就叫Agent-Reach。名字很直白意思就是“让每一个Agent都能被准确触达”。这篇文章把我这几周的踩坑、设计取舍和落地实录整理出来不聊虚的直接讲怎么把一个Agent集群做成“有服务注册、有健康探活、有智能路由”的生产级接入层。如果你正准备把Agent能力接入业务系统或者想给自己的多Agent项目加一层可靠调度这篇内容对你会很有用。不用懂太深的后端知识我会尽量把每一层的设计逻辑和实现细节都讲清楚。1. 项目初衷与整体设计思路Agent-Reach不是一个业务Agent它不负责对话、写代码、做规划。它是一层基础设施我们内部叫它“触点管理服务”。简单说它解决三个问题Agent注册、Agent发现、Agent路由。1.1 为什么需要专门的Reach层如果你只有一两个Agent用配置文件写死地址就够了。但一旦Agent数量上到几十个或者Agent分散在多台服务器、多个K8s节点上问题马上变麻烦。部署了新版本的话旧地址失效某台机器负载过高某类任务必须由特定Agent处理Agent崩溃后流量还是往它那边打。这些问题单靠配置管理和负载均衡器是挡不住的因为Agent有状态、有类型、有容量差异不是普通的HTTP服务。我当时走访了一圈团队需求总结下来就是需要一个中间层让上层应用不必感知具体Agent实例的IP和状态只按“能力名字”去调用剩下的寻址和调度全部交给这一层。这也是Agent-Reach最核心的设计目标。1.2 三层架构的取舍我最初参考了微服务里注册中心的成熟套路但Agent和微服务有一个关键差异微服务实例相对稳定Agent的启停要频繁得多而且Agent对上下文和数据隔离的要求也更高。所以我没有直接照搬Eureka或者Nacos而是做了一个偏轻量的三层模型接入层负责接收Agent上报的状态信息包括心跳、能力说明、当前并发数、上下文长度调度层根据业务请求携带的能力标签、优先级、数据亲和性在可用Agent列表里选一个最合适的实例缓存层把Agent状态数据同步到本地内存和Redis避免调度层每次做远程调用使得请求路径尽量短。这个设计的核心取舍是“以Agent自身状态为中心”。调度器不主动刻板地轮询一切选择都以Agent最近一次上报的信息为准。上报的间隔越短调度越精准代价是Agent端压力增大。我后来把默认心跳设成了5秒既不会漏判导致大规模误剔除也不会因为上报太频繁占满Agent进程的资源。1.3 核心模块拆解整体代码可以分为四个模块。注册模块负责接收Agent第一次上线的注册请求写入唯一实例ID、能力名、标签和附加元数据探活模块负责跟踪每个Agent的续约超过租约时间就标记为失联路由模块负责按策略筛选可用实例并返回目标地址控制台模块提供一个极简界面能实时看到各Agent的在线状态和请求分布。注册信息我用的是MySQL持久化但实时调度不查库只在Agent状态变更时才写库。这样设计的好处是调度路径上完全无SQL操作性能瓶颈基本就剩下网络开销了。实际压测下来单机调度层QPS能到1.2万左右对于内部工具来说非常够用。2. 核心机制注册、保活与可达性判定Agent-Reach的关键在于“可达性判定”。这是所有调度逻辑的地基一旦误判下游所有策略都会出问题。我把它细分成注册协议、心跳租约、状态摘除三个子环节。2.1 Agent注册协议设计Agent首次启动时调用Reach的注册接口上报自己的实例名、Agent类型、可以处理的技能标签、限制信息最大并发数、单次任务最长执行时间、支持的大模型类型等。注册完成之后Reach会返回一个instanceId和一个临时token后续的心跳和上下线都带这个token防止伪造上报。注册信息里有一项我觉得特别重要preferred_regions。这是Agent所在的物理或逻辑区域标识。比如我的Agent分布在两个内网网段一部分在GPU区一部分在通用计算区。当业务请求带有数据本地性要求时调度器能根据这个字段避开跨网段传输省掉大量数据搬迁开销。注册接口本身幂等性很好做因为instanceId由Agent自己生成一般是hostname进程ID随机数Reach侧按这个ID做upsert。第一次上线是insert后续重复注册就是update元数据。实测中重复注册主要发生在Agent崩溃重启或网络闪断后重连幂等设计省了前端很多事。2.2 心跳与租约机制心跳接口我设计得比较简Agent每隔5秒打一次BeaconBody里只带instanceId、当前状态BUSY或IDLE、当前并发任务数、最近一次任务耗时。Reach收到心跳后刷新这条Agent的最后更新时间并同步更新内存里的状态快照。租约机制参考了分布式系统里常见的TTL思路。Reach指定一个leaseDuration默认是15秒。如果15秒内没有收到某实例的心跳就判定该实例失联将其从可用池子摘除。同时摘除动作只是把status置为OFFLINE记录摘除原因和时间并不删除注册记录这样网络抖动恢复后Agent重新上报心跳就能自动回池不需要再次全量注册。这个设计有个细节值得注意心跳不能一过期就杀。瞬断很常见Agent可能只是暂停了3秒的GC或一次长任务阻塞。所以我把状态切换做成三级HEALTHY、SUSPECT、OFFLINE。超过15秒没心跳进SUSPECT转发时标记“降级权重”但还能接收轻量请求超过30秒还没心跳才真正摘除。这个缓冲让系统在波动时稳定很多尤其能扛住Agent JVM导致的偶发停顿。2.3 状态摘除与优雅下线除了被动摘除Agent还可能主动下线比如发布新版本时需要排空流量。我预留了一个下线路由Agent调用/offline接口声明“我要离线了”Reach把这个实例从可用列表里立刻摘掉但保留已有请求执行完。这就避免新流量进入正在重启的进程。这里踩过一个坑Agent进程在卸载钩子里调用offline但进程退出太快HTTP调用还没发出去就断了。后来我把下线动作做了两级保障——先标记本进程为“停止接收新任务”再发离线请求同时本地维持10秒的grace period确保离线请求在进程真正退出前送达。对于极端场景比如机器断电那就只能等心跳过期被动摘除了这类情况没办法完全避免。3. 路由策略与调度实现Agent-Reach真正花时间的是路由模块。它不能随便挑一个健康实例就算完事而要支持多维度约束。我把调度拆成“过滤打分选择”三段每一段都有背后逻辑。3.1 过滤阶段先排除不可用实例过滤规则按优先级执行第一层过滤是不可用状态包括OFFLINE和SUSPECT第二层过滤是能力匹配业务请求里的capability字段必须与Agent支持的技能标签交集非空第三层过滤是数据亲和性如果请求指定了data_region就只保留该区域的Agent最后一层是并发水位过滤Agent当前并发数和最大并发比例超过0.85就临时不参与调度。实际使用下来并发水位过滤是最影响结果质量的。以前没加这项时某个Agent可能已经被压满调度器还是往里扔任务导致响应时长一下子拉胯。加了之后系统会自动把热点Agent留一口气处理已有任务新任务分散到其他实例上。代价是小部分请求会跑到较远的区域但相比整体延迟劣化这个代价完全值得。3.2 打分阶段量化每个候选Agent的适配度过滤只剩健康实例后进入打分环节。打分函数我用的加权综合公式Score 0.35 * ConcurrencyScore 0.30 * AffinityScore 0.20 * LatencyScore 0.15 * StabilityScoreConcurrencyScore是剩余并发容量的归一化值AffinityScore看的是候选Agent的历史调用记录如果有过去5分钟内成功处理过同一类请求就加分LatencyScore取最近100次任务的P50执行耗时耗时越低分越高StabilityScore看的是近一小时GC暂停次数、内存增长趋势、注意这里是Agent运行时统计上来的指标不是Reach自己猜的。这个公式不是一开始就定死的。最初我把稳定性的权重设为0结果某个Agent因为内存泄漏导致频繁FullGC调度器毫不知情照样把任务给它直到请求超时才发现。后来加入了稳定性指标并在控制台打了一个“GC风暴”告警这类问题才被提前拦下。3.3 选择阶段随机加权与亲和保持得分算完后自然是用加权随机选择而不是直接选最高分。原因很简单如果始终选最高分实例所有流量会在瞬间集中到同一批Agent上很快就把它们打热然后又被并发过滤防住导致“热点漂移”。加权随机让高分实例有更高概率被选中但低分实例也有少量机会整体分布更平滑。这里还有一个“亲和保持”的细节如果请求的traceId之前已经固定到了一个Agent实例且该实例仍然健康我会把它直接返回不加额外计算。这保证同一用户会话尽量在一个Agent上完成避免上下文反复搬运。亲和保持出过一次问题agent实例因网络瞬断进入SUSPECT状态但亲和策略还把它返回给调用方导致一批请求全部失败。修复方法是在亲和命中后增加一个快速状态校验SUSPECT直接跳过亲和。这个逻辑是给调度器加了一行判断但实际收益很明显故障恢复速度从分钟级降到了秒级。4. 实操落地从零搭建Agent-Reach理论讲完了分享点直接能上手的操作。我用Go写了Reach服务端Agent端SDK用了Python因为现在大部分Agent框架的胶水层还是Python多点。下面把关键环节列一下照着做基本能跑通。4.1 服务端核心代码骨架Reach的服务端入口我用了Gin框架数据库用MySQL缓存用了Redis和内存混合。核心调度逻辑不依赖RedisRedis只用于跨节点同步和审计日志。代码结构比较清晰核心就两个接口注册和心跳。// 注册Agent r.POST(/api/agent/register, func(c *gin.Context) { var req RegisterRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } id : registry.Register(req) c.JSON(200, gin.H{instance_id: id, token: registry.GenToken(id)}) }) // 心跳上报 r.POST(/api/agent/beacon, func(c *gin.Context) { var req BeaconRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } registry.Heartbeat(req.InstanceID, req.Status) c.JSON(200, gin.H{ok: true}) })心跳接口没有做复杂的鉴权只校验了token前缀的合法性因为Agent端和Reach端都在内网且中间有防火墙规则依赖内网信任可以降低不少通信开销。调度查询接口是另一个重点。上层应用传入的调用ID其实是capabilityNameReach根据它选好Agent后返回完整的调用地址和参数模板。# 伪代码简化突出调度流程 def schedule_request(capability: str, context: dict) - AgentTarget: pool registry.get_candidates(capability) if not pool: raise NoAvailableAgentError(capability) filtered filter_by_health(pool) filtered filter_by_capacity(filtered) pool_with_score [(agent, compute_score(agent, context)) for agent in filtered] return weighted_choose(pool_with_score)4.2 Agent端SDK接入要点Agent端SDK封装了注册、心跳、状态上报三个动作。我建议把SDK设计成启动时自动异步注册不阻塞Agent主流程。试用的时候发现如果注册失败直接抛异常很多Agent启动逻辑会被卡住所以我改成“注册失败进入重试队列不影响本地执行”的模式。心跳逻辑用后台线程实现每次打心跳时顺带传最近一次任务执行耗时。这里要强调任务耗时的统计口径必须准我遇到过Agent端把排队时间也算进执行耗时导致Reach端的LatencyScore完全失真。后来规范了字段task_duration_ms只算真正执行时间排队和网络传输时间都单独上报。class AgentReachSDK: def start(self): threading.Thread(targetself._beacon_loop, daemonTrue).start() self.register() def _beacon_loop(self): while True: self.report_state() time.sleep(5)这里还有一个经验值心跳线程的网络超时时间不要设置太长建议2秒以内。如果Reach端整个宕机Agent不该无限等网络响应而是降级成本地模式保留Agent独立工作的能力。毕竟Reach挂了业务Agent还能干活等到Reach恢复再做补偿注册就行。4.3 控制台与可观测性Reach控制台有一个实时视图能看到所有Agent实例的列表每行带状态、最近心跳时间、当前并发、24小时成功率。这个视图对运维特别有用基本能替代一大部分调试工作。另外我加了一个事件流页面所有Agent的注册、失联、恢复、路由变更都在页面上滚动显示。排查问题的时候按时间轴看事件流比看日志快很多。比如某个时刻调度变慢往上查一下往往能看到某台机器因为GC发生SUSPECT再结合日志确认就是那次事件引起的连锁反应。5. 常见问题与排查经验速查这几周实际跑下来遇到的问题比预想的多。我挑了些有代表性的做成表格方便速查。现象可能原因排查手段Agent列表全部脱机Reach服务端与数据库连接断开检查MySQL连接池心跳写库失败导致判定全部失联偶发请求打到已下线的Agent亲和保持跳过了SUSPECT校验确认亲和命中后的状态二次检查逻辑是否生效调度结果总集中到同一实例打分函数内缓存被人为删掉检查Redis缓存失效策略确认实例分数未过期心跳正常但请求超时Agent实例已阻塞但心跳线程仍能执行查看实例执行池线程消耗增加单独的执行状态上报注册接口偶发503注册并发量过大数据库写冲突注册写库改为异步批量同步注册接口改为最终一致除了表格里这些还有一个非常值得说的坑Agent上线时如果注册得太快下一条心跳还没跟上Reach端可能会把它认成“新实例但从未活跃”然后被租约机制误判剔除。我的解决办法是在注册接口返回后代理端以此为起点立刻打一条带initialtrue的心跳。这条心跳不参与正常租约计算只用于确认“我确实活了”。还有一个和Agent调度强相关的问题——线程池阻塞。曾有一个Agent实例的心跳一直正常但它内部处理请求的线程池全部阻塞新请求进入后排队耗时指数级增长。Reach的P50耗时指标很快捕捉到了异常但由于阈值设置过宽没有触发自动摘除。后来我把LatencyScore的异常阈值收紧并加了一条“连续5次P99延迟超过3秒就强制摘除”的规则这类故障现在基本几秒内就能自动隔离。还有个细节Agent端时间不同步会导致心跳时间错乱。Reach校准时间是以自己的服务器时钟为准Agent上报的时间仅作参考不参与租约计算。如果环节里有人直接用了Agent端的系统时间做过期判断很容易出现误杀或漏杀。后来我统一了所有服务的NTP同步租约计算只用Reach本地时间戳。6. 后续可以怎么扩展Agent-Reach现在对我这边的多Agent平台来说够用了但有几块我还在筹划升级。第一是加上容器化环境下的自动注册K8s的Pod重建很快如果Reach没有及时感知到新Pod注册的实例流量会短暂丢失。我把这个做成一个单独的控制器监听Pod的Ready状态之后自动调用注册接口。第二是路由策略加上语义标签目前capability匹配是对标签做集合运算下一步想接入向量相似度让Agent能力描述更自然不再依赖人工打标。还有一个方向是给Agent做调用配额管理。目前Reach只管调度不管“谁来调”。如果某个调用方写了个死循环疯狂请求会把整个Agent池打爆。我计划增加一个配额层按调用方身份限流类似网关里的Rate Limit避免单个调用方把基础设施拖垮。不过这些都是迭代计划当前的Agent-Reach已经解决了最重要的问题Agent不再是一个个孤岛而是能被统一发现、统一调度、统一治理的集群能力。如果你正好也在做类似的多Agent调度层建议先别急着堆功能把注册协议、心跳租约、路由打分这三件事想透后面再加什么都顺手。最后分享一个我自己的体会。做Agent基础设施最忌讳的就是“把Agent当普通服务”来管理。Agent有状态、有偏好、有性能差异单纯用负载均衡的思路去路由短期能跑规模一大必然出问题。我这次把“Agent自身状态上报”放到了调度决策的中心收到的效果比预想好得多。如果你也卡在Agent集群管理这块可以试试从“让Agent主动说自己的情况”这个思路入手很多调度难题会一下变得简单很多。
