大概半年前我手上同时维护着三个AI Agent一个做信息检索一个做代码审查另一个负责把结果拼成文档并发送通知。它们各自跑在完全不同的框架里——一个是LangChain搭出来的一个是用Python脚本直接调模型API还有一个内部状态机写得很随意。麻烦很快来了这三个Agent之间想说上话只能靠我在胶水层里堆if-else从JSON字段映射到Markdown格式再映射到通知模板代码又丑又脆改一处崩三处。后来我认真做了Agent-Reach这个项目定位成一条专门给AI Agent互相发现、互相调用用的互联层。它不替代任何Agent框架也不碰模型推理只解决一件事让不同来源、不同协议的Agent像查电话簿一样找到对方再用统一信封安全地递送任务。如果你也在被多Agent怎么协作折磨这篇值得看完。1. 为什么我需要一个Agent通讯层现场问题比概念更直接1.1 三个Agent联调的第一次崩溃先回顾一下最原始的痛点。当时A、B、C三个Agent是这样分工的A检索Agent负责搜索网页和数据库输出List[Dict]带title、url、summary字段。B审查Agent接收任何文本先校验再输出审查意见内嵌在review标签里。C文档Agent只认特定POST接口要求入参是固定的XML片段。最初让它们协作我在代码里写的是if source agent_a: payload json.dumps({ docs: [{t: d[title], u: d[url], s: d[summary]} for d in a_result] }) # 还要把B看懂的结构拼出来这种写法最大的问题不在代码量而在于每个Agent的接口知识都耦合在上游的字段命名里。只要A把summary改成excerpt我改B的调用B把审查标签改成别的C又要动。更别提后来加了第四个Agent——负责定时的监控Agent整个胶水层直接失控。1.2 现成多Agent框架覆盖不到的盲区当时我也试过把整套协作迁到某个流行的多Agent框架里。但越试越别扭方案优点不适合我的原因单框架内多Agent编排逻辑现成我的Agent是异构的迁移成本高还得绑死它的运行时直接用LLM工具调用简单工具函数是给模型用的不是给Agent之间互相暴露服务用的语义太重自制消息队列解耦我要的不是异步消息是发现能力→确认调用→拿回结果的同步闭环MCP等工具协议解决了工具接入它解决的是模型怎么用工具不是Agent怎么找到另一个Agent并调它这个盲区很真实业界已经有不错的工具协议但没有一个轻量的、与运行时无关的Agent互连层。Agent-Reach的定位就在这儿——它更像一个Agent版DNS消息总线契约登记簿的混合体。1.3 Agent-Reach的核心职责一句话概括负责给Agent提供注册、发现、路由与请求信封的统一层。它把每个Agent抽象成四个可描述的东西这是后面所有机制的基础身份全网唯一的Agent ID例如agent://search/main。能力能干什么用带版本号的能力标签表示例如cap.search.web1.2。契约接受什么输入、返回什么输出用JSON Schema声明。可达地址载体无关的Endpoint可以是HTTP、gRPC也可以是本进程内的回调。有了这四件事Agent之间不需要知道彼此的源码和调用习惯只需要知道谁提供什么能力、长什么样。2. Agent-Reach的骨架注册、心跳、路由三板斧2.1 能力注册表每个Agent是一组能力标签我把注册表设计得特别克制。每个Agent注册时提交的字段就这些{ agent_id: agent://review/code, version: 0.4.2, capabilities: [ {name: cap.review.code, version: 1.0}, {name: cap.report.brief, version: 0.3} ], endpoint: {type: http, url: http://10.0.0.12:8601/review}, contract: { input_schema: https://agents.example/schemas/review-input.json, output_schema: https://agents.example/schemas/review-output.json }, ttl: 45, owner: platform-team }这里有个容易忽略的设计点注册表存的是能力不是意图。我曾经尝试让Agent用自然语言描述自己能干什么结果发现LLM描述能力和机器路由能力完全是两套语言语义匹配必然带误差。后来改成强制的能力标签体系新Agent接入时必须选择已有标签或申请新标签路由时做严格匹配加少量语义兜底可靠多了。存储上我直接用Postgres的JSONB列没有上独立的注册中间件。注册量到几万个Agent之前完全够用索引打在capabilities.name上即可。2.2 心跳与租约注册信息的本质是活没活分布式系统里最朴素的保活手段放在Agent联网场景里依然有效。每个Agent注册后必须周期性续租import threading, time, requests def start_heartbeat(registry_url, agent_id, ttl): def beat(): while not stop_event.is_set(): requests.post(f{registry_url}/agents/{agent_id}/heartbeat, json{ttl: ttl}, timeout5) time.sleep(ttl / 3) t threading.Thread(targetbeat, daemonTrue) t.start()我踩过一次教训TTL设太大Agent进程被OOM杀掉之后注册表里还挂着它的健康状态调用方持续踩空。后来把TTL压到45秒、每15秒一次心跳配合注册表的租赁过期策略检测到最后一次心跳时间超过2个TTL就直接摘除。注册信息不是身份的背书只是活性的凭证这个心态要摆正。2.3 请求信封与契约校验不同框架的Agent也能对话异构Agent能对话靠的不是把协议统一成一种——那在现实中根本做不到。方法是用一套外层信封把每种Agent原本的东西原封不动装进去。信封字段如下字段类型含义request_idstring唯一的调用ID幂等和追踪都靠它trace_idstring链路追踪ID一次业务任务贯穿所有Agentfrom_agentstring调用方Agent IDto_agentsstring[]目标Agent ID或留空交给路由capabilityobject需要的具体能力及版本payloadobject携带的业务数据按目标契约组织timeout_msint调用方期望的最长等待时间metadataobject重试次数、优先级、上下文引用送达之前路由层会先拿注册表里存的目标契约去校验payload。这一步卡住过很多看起来能跑的调用——有时候并不是Agent逻辑出了问题而是字段名、嵌套层级、可选参数没对齐。用JSON Schema做前置校验后大多数契约矛盾在调用前就暴露了而不是在人等了一分钟后才发现对方返回了一堆报错文本。3. 核心链路实操从Agent上线到跨Agent调用的完整代码3.1 接入侧给任何一个Agent挂上Agent-Reach接入动作被压缩到两步注册拉取任务。我在检索Agent的启动函数里加了几行from agent_reach import connect client connect( registryhttp://registry.internal:9080, agent_idagent://search/web, capabilities[cap.search.web1.2], endpoint{type: http, url: http://10.0.0.10:9001/search}, ) client.start() # 注册、心跳、拉取任务都封装在这里client.start()之后注册、心跳和任务入口是同一个进程内循环不需要额外部署SDK。拉取任务我推荐短轮询而不是常驻Webhook——原因很实际Agent进程有各种重启、抢占、依赖初始化问题短轮询天然自带重连能力Webhook一旦断掉要额外维护重推逻辑。3.2 调用侧按能力找Agent而不是按ID找Agent调用方最常用的API是按能力路由而不是直接点名response client.invoke( capabilitycap.search.web, version1.2, payload{query: Agent互联协议对比, top_k: 5}, timeout_ms30000, )路由层拿到这个请求后做的事情按顺序是根据capability匹配注册表中所有存活Agent。如果有多个候选按权重排序——权重可以是历史成功率、平均时延、人工设置的优先级。把信封投递给首选Agent同时记录trace_id。等待Agent的回执信封回执里带着output_schema校验状态和最终结果。这里我特意没做多点广播。早期考虑过让多个Agent同时跑同一个任务、谁先返回用谁后来发现在真实业务里钱和计算资源都是成本广播只适合容错要求极高的场景。默认策略仍是按权重顺序尝试。3.3 多跳编排一次任务穿越三条链路的日志现场多跳编排是Agent-Reach里最花心思的部分。我举个实际的例子用户给文档Agent发任务生成本周技术周报。文档Agent自己并不具备检索能力它需要走这么一条链doc Agent - 调用 review Agent 拿到过去一周被审查过的代码清单 - 调用 search Agent 补充检索与代码关联的项目背景 - 汇总以上所有结果生成周报这条链路里每个环节都发起了独立的invoke又都带着同一个trace_id。我在调用侧暴露了invoke_chain方法result client.invoke_chain( trace_idtrace_id, steps[ {capability: cap.review.list, payload: {since: 7d}}, {capability: cap.search.web, payload: {query: week highlights, context: None}}, ], reducerlambda list_result, search_result: merge_weekly_report(list_result, search_result), )这个方法内部把每一步的结果注入下一步的payload占位并保留trace_id。实测下来多跳编排最值得警惕的不是超时而是中间步骤的部分成功。比如检索调不到数据但返回了兜底空列表审查Agent却以为检索真的失败了又触发重试最后整个链路的重试风暴滚雪球。所以在每个步骤的回执里我都要求Agent带一个status字段明确标记ok、no_data还是errorreducer里根据status做分支而不是看payload内容。4. 把协作做稳超时、重试、幂等与熔断的实战取舍4.1 超时与退避Agent返回慢多半不是网络问题普通RPC超时按秒算Agent调用不能这么干——Agent内部往往要跑一遍完整的LLM推理一个30秒超时可能连思考的时间都不够。我统计过自己项目里的实际延迟分布能力类型P50P95特点缓存/规则类Agent200ms800ms基本不涉及推理单轮LLM检索Agent6s18s受模型和上下文长度影响带多轮推理的审查Agent22s75s容易超时必须有区分度所以Agent-Reach的默认超时分成两档调用方自选timeout_ms路由层设置max_timeout_ms做硬上限超出直接返回失败回执。重试策略也跟延迟分布绑定——固定间隔重试在Agent场景下基本没用我用的是指数退避抖动def next_retry_delay(attempt, base_ms1000, cap_ms30000): exp min(base_ms * (2 ** attempt), cap_ms) return exp random.randint(0, exp // 10)重试次数默认3次。超过后不再自动重试而是把失败回执连同trace_id标记为需人工介入避免同一个坏任务无限烧钱。4.2 幂等与去重LLM的我以为我做了问题Agent场景和数据库写入场景的幂等需求不同——数据库靠唯一主键Agent靠request_id。问题在于LLM Agent拿到重复请求时可能会因为上下文里恰好多了一句话就给出不同结果。为了让重试结果稳定我在Agent侧强制要求同一request_id的执行结果必须缓存在本地再次收到直接返回缓存。cache_key f{request_id}:{payload_hash} if result_cache.get(cache_key): return result_cache[cache_key] result await run_agent_logic(payload) result_cache[cache_key] result这个细节救了两次线上事故。一次是检索Agent的LLM供应商返回了瞬时限流SDK自动重试后同一次检索被跑了两次成本翻倍另一次是文档Agent重复推送了同一份周报到通知群。都靠request_id去重解决了。4.3 熔断器在Agent调用里的使用边界熔断器我用得很克制。传统微服务里连续失败N次就断开的规则到Agent上不太适用——因为一个Agent的失败往往是暂时的模型限流、上下文过长、外部工具掉线且Agent本身有自恢复心跳。武断熔断会误伤一大批本来稍等就能成功的请求。我的做法是慢调用熔断而非失败熔断统计窗口内平均时延超过阈值的比例。当慢调用比例连续5个窗口超过40%时路由层暂时把该Agent的权重降为0。降权持续2分钟期间路由去候选列表里尝试其他同能力Agent。如果没有其他候选则放行该Agent但把超时调大一倍而不是拒掉请求。这套逻辑落地后稳定性明显好转。核心思想是Agent之间宁可慢也不要随意拒绝宁可降权也不要因为一次抖动判死刑。4.4 一个典型的失败场景注册表状态和真实状态脱节下面这个排障过程值得记录下来因为它暴露了Agent-Reach一个深层设计缺陷。某天监控Agent连续告警文档Agent不可达。查看注册表文档Agent心跳正常健康状态是绿的。但实际调用全部超时。排查过程是这样的先查日志发现所有调用都发到了同一台机器其他机器没有流量。查部署记录发现文档Agent刚发过新版本但注册表里version还是旧值。进一步查发现新版本实例启动时把endpoint写成了另一个端口而旧实例还在跑、心跳也在续租——注册表里存的是旧实例的信息新实例注册失败后反复重试旧实例又迟迟不退两者叠加把流量全部导到了旧实例。最后直接在注册表里强制摘除旧实例并修正endpoint问题解除。教训是Agent注册时的version必须和部署流水线的构建号联动实例启动时必须先主动反注册旧身份的租约再注册新身份。我把这两条硬编码进了Agent-Reach的SDK之后类似的幽灵僵尸实例再没出现过。5. Agent-Reach实测数据、仍在折腾的问题与上手建议5.1 一组来自压测和日常的真实数据项目跑了一个多月后我整理过一组数据是在8个Agent实例、注册表单节点Postgres下的表现指标数值说明单节点注册表支撑Agent数约1200个超过后写QPS开始上涨读仍稳定路由决策P993ms注册表查询权重排序端到端调用P95不含Agent内部推理8ms信封封装、契约校验、网络开销心跳处理能力每秒约2500次Postgres更新TTL为主重试命中幂等缓存的比率67%说明重试里大部分是重复请求这个结果表明一个反直觉的事Agent互联层的瓶颈几乎不会在路由本身上而会在Agent的处理时延、契约校验和失败恢复这三处。所以我没有投入资源去做高性能路由而是持续打磨校验和观测。5.2 现在仍让我头疼的几个问题Agent-Reach还远谈不上完美有几个点我一直在折腾语义路由与能力标签之间的矛盾。能力标签足够硬但新Agent进了系统后很难自动知道自己该挂哪个标签需要人工介入。尝试过用embedding做初筛、用标签做复核的半自动流程效果还行但还没稳定到敢默认开启。多跳编排里的上下文体积失控。每跳都往payload里塞上下文链条一长内存和token成本快速增长。下一步想加上下文摘要闸门每跳只保留结构化摘要。观测数据散落在各个Agent内部。路由层能看到信封但看不到Agent内部的LLM调用链。正在把OpenTelemetry的span接入Agent侧SDK让trace_id能贯穿到模型调用层级。5.3 如果你也想搭一套Agent互联机制根据我这一路踩坑的经验给同样在折腾多Agent协作的人三条建议。第一先把信封格式定死再谈其他。不夸张地说Agent-Reach 80%的价值来自那个统一的请求信封。哪怕你不打算造一个完整的互联层只要内部所有Agent都按同一套请求/响应格式通信协作复杂度就已经大幅下降。格式里request_id、trace_id、status三个字段一定要有。第二用模拟Agent先做联调。别急着把所有真实Agent接进来。我先写了一个假检索Agent随机时延、偶尔报错专门用来测超时、重试和熔断逻辑。没有这些故障注入很多边界情况根本不会在联调阶段暴露全留到线上才炸。第三别在设计上贪多。我一开始给Agent-Reach规划了AI驱动的自动路由、编排执行引擎、计费系统后来全砍掉了只留注册、发现、信封、重试四件套。砍掉之后项目才真正跑起来。互联层应该薄薄到可以被产品团队忽略才算是合格的中间层。最后分享一个我一直在用的小习惯每次给Agent-Reach迭代完我会把所有新版本SDK打包进一个docker-compose里带上两个模拟Agent加一个真实文档Agent跑一遍冒烟测试。这套脚本虽然简陋但是比任何文档都可靠——它能确保任何一次改动都不会破坏注册→发现→调用→回执这个最基本闭环。多Agent协作的复杂度已经够高了能守住这个闭环不被自己改崩就是互联层最大的胜利。