多智能体应用这几年被吹得很凶但真正动手做过的人都会遇到同一个坎单个智能体再聪明也架不住业务一复杂就开始力不从心。真正让人头疼的往往不是模型能力本身而是智能体之间的触达问题——谁有权限调用谁、怎么找到对方、调用过去之后上下文怎么传、失败了怎么兜底。Agent-Reach就是我在这个方向上折腾的一套基础设施核心干一件事让智能体能够被另一个智能体可靠地发现、调度和调用。这篇文章会把它的设计思路、落地过程和踩过的坑完整拆出来适合那些正在做Agent平台、多智能体编排或者AI中台的开发者参考。1. Agent-Reach到底在解决什么问题1.1 你的智能体们其实是一座座孤岛先说一个我观察到的普遍现象。大部分团队做AI应用一开始都是单Agent形态一个客服机器人、一个数据分析助手、一个工单处理机器人各自独立部署各自接自己的模型和工具。单看每个Agent效果都还行。但业务流程一旦跨Agent问题就立刻暴露了。举个例子一个用户找客服投诉“物流显示签收但我没收到货”客服Agent查完订单链路发现需要去仓储系统核实而仓储那块功能是另一个团队用独立的Agent做的。这时候没有Agent-Reach这类东西你只能硬编码API调用客服Agent直接HTTP请求仓储Agent的某个接口。听起来简单但实战里你会发现一大堆问题。仓储Agent的接口参数格式不透明响应结构两套团队各写各的调用失败没有统一的补偿机制更别提调用链路上谁出了问题都很难定位。说到底这就是智能体孤岛化。每个Agent都像一个小岛岛上自动化做得很好岛和岛之间却只能靠人肉搭桥。Agent-Reach要做的事情就是在这个岛上架一个统一的“调度总机”让任何Agent都能通过标准化的方式触达另一个Agent而不需要关心对方的内部实现。1.2 为什么不能直接“做个API网关”了事可能有人会想这不就是API网关吗Kong、APISIX都能做路由转发再加个注册中心不就完事了这个想法对了一半。智能体之间的触达底层确实是API调用但上层多了一层非常关键的东西语义路由和上下文感知。传统网关转发的是HTTP请求路径、方法是预先定义好的/api/order/getById这种接口是死的。但Agent之间的调用很多时候请求方自己都不知道该调谁。比如上面那个客服Agent它手头只有一个模糊的诉求“帮我核实这个包裹的去向”它需要先理解这个诉求再去匹配到底是仓储Agent、物流Agent还是订单Agent能解决。这个过程不能靠写死的路由表得靠语义匹配。另外智能体调用的还不仅仅是接口是一段业务上下文加上一个目标。A Agent把用户意图、历史会话、业务数据传给B AgentB Agent执行完还要把结果连同新的上下文回传。这比传统API的“请求-响应”复杂得多它本质上是分布式多轮对话。普通网关模型根本不支持这种语义层面的透传和上下文管理。所以Agent-Reach不是APISIX的替代品它应该理解成APISIX之上的一层智能调度系统专门处理“模糊诉求到具体Agent”的映射、“长上下文在Agent之间的安全传递”以及“调用链路的统一治理”。这个概念定下来之后后面的架构设计就顺了。2. 核心架构Agent-Reach的四层设计2.1 注册层AgentCard是每个智能体的“身份名片”想要让智能体被触达第一步是先让平台知道它存在。传统服务注册用的是服务名IP端口但对智能体来说这远远不够。我参考了开源社区里智能体描述协议的一些思路做了一份AgentCard规范每个Agent接入时必须提供一份结构化描述类似智能体的“身份名片”。这份AgentCard长这样{ agent_id: logistics-warehouse-agent, name: 仓储物流核验智能体, version: 2.1.0, capabilities: [ { name: package_location_check, description: 核验包裹的物流轨迹与实际签收状态返回异常原因, input_schema: { type: object, properties: { tracking_id: {type: string, description: 物流单号}, order_id: {type: string, description: 订单编号} }, required: [tracking_id] }, output_schema: { type: object, properties: { is_abnormal: {type: boolean}, reason: {type: string}, evidence: {type: array, items: {type: string}} } } } ], rank: 0.82, max_concurrency: 10, timeout_ms: 30000, permission_level: internal, cost_per_call: 0.002 }这里最关键的是capabilities它描述了这个Agent能干什么、输入输出长什么样。注意description我建议写详细一些因为后面语义路由要拿它和用户诉求做匹配描述越精确路由准确率越高。permission_level则定义了这Agent能服务的调用方范围是实现权限控制的基础。2.2 路由层把意图解析交给大模型但别全交给它路由层是Agent-Reach最核心也最复杂的部分。请求进来之后路由层需要回答一个问题这个诉求应该交给哪个Agent我试过两种路线踩了个大坑之后才找到平衡。第一种是纯关键词匹配比如用户说“物流”就路由给仓储Agent。但这个方案太脆了用户说“我的货去哪了”就没有“物流”关键词直接匹配失败。第二种是纯靠大模型做意图识别把所有AgentCard一股脑塞给LLM让它选。试过之后发现当注册的Agent超过5个或者Agent能力之间边界模糊时大模型的选型结果就开始飘而且每次调用的Token消耗和延迟都不小。最后我采用的是**“召回-打分-兜底”三级路由**先用自己的轻量Embedding模型把请求文本和所有AgentCard里的capabilities.description做向量余弦相似度计算召回Top 5候选。把Top 5候选的AgentCard关键信息交给大模型让它做最后裁决返回一个带JSON结构的决策结果包含选中的Agent和需要填充的参数。如果大模型返回的Agent不可用比如并发满了或熔断了走兜底策略降级到Top 2候选或者返回“无法处理”并给出可尝试的Agent列表。这三级路由的好处是向量召回兜底了大多数常规请求只有模糊度较高的请求才消耗大模型的推理成本。实测下来这个方案把路由层的大模型调用量降到了总请求量的三成左右单次路由延迟从原来的2到3秒压到了500毫秒以内。2.3 执行层统一协议收敛掉各Agent的“方言”路由只是找到了目标真正要触达的时候还得解决一个实际的问题每个Agent的调用协议不一样。有的Agent内部是REST API有的是gRPC有的是WebSocket长连接有的甚至只提供了一个Python SDK。如果让路由层去适配每一种协议那Agent-Reach就变成了一堆胶水代码的集成品根本维护不下去。我的做法是在Agent侧加一个Agent Adapter。这个Adapter通常作为Agent的一个轻量边车组件暴露一个标准的HTTP接口给Agent-Reach调用然后由Adapter内部做协议转换去调用Agent自己的核心代码。相当于给每个Agent配了一个“翻译官”。执行层的调用流程大致是路由层确定目标Agent后从注册中心拿到它的Adapter地址。Agent-Reach按规范构造执行请求包含request_id、intent、parameters、context_ref。Adapter收到后转换协议调用Agent核心逻辑等待结果返回。Adapter把结果按标准格式封装回传Agent-Reach记录链路的耗时、Token消耗、结果状态。2.4 治理层权限、审计和链路追踪缺一不可多Agent协作最大的隐患是权限边界模糊。一个调用方Agent能调用的其他Agent必须被显式授权。我基于AgentCard里的permission_level再加了一张访问控制表类似这样调用方Agent被调用方Agent允许的能力生效时间customer-servicelogistics-warehousepackage_location_check, return_apply2026-04-01至2026-12-31>def route_request(request: AgentRequest) - RoutingResult: candidates recall_by_vector(request.intent, top_k5) if candidates[0].score 0.75: final_agent llm_decide(request.intent, candidates) else: final_agent candidates[0] if not check_permission(request.caller_agent_id, final_agent.agent_id): return RoutingResult(statusFORBIDDEN) if not check_available(final_agent): return fallback(request, candidates) return RoutingResult(statusOK, target_agentfinal_agent)这一步有个容易忽视的细节权限校验必须放在路由确定之后。有些实现图省事在召回阶段就过滤掉没权限的Agent这个设计会导致调用方Agent从结果里猜出“存在另一个Agent但是不让我调”属于信息泄露。我们在路由确定之后做统一鉴权明确返回被拒而不是让调用方感知到目标Agent的存在。3.3 接入一个新Agent的完整流程如果你在自己的项目里用Agent-Reach接入一个新的Agent只需要四个步骤编写AgentCard JSON描述清楚能力、输入输出和权限级别。开发Agent Adapter把Agent内部能力包装成标准HTTP接口。把AgentCard注册到Agent-Reach的Redis注册中心调用接入接口/agent/register。在访问控制表里配置允许谁调用它然后跑一条测试调用验证链路。这些东西加起来一个新手工程师大概两三个小时能完成接入。相比之前“两个团队撕API文档格式、约联调时间”的痛苦效率提升是肉眼可见的。4. 真实踩坑记录与排查思路4.1 超时问题LLM天生慢不能用传统接口的期望上线第一周遇到最多的问题是超时。客服Agent调用仓储Agent路由很快但仓储Agent内部对接了大模型做单据推理一次推理要8到10秒。而Agent-Reach默认同步调用的HTTP超时我设成了5秒结果大量请求直接失败。这个问题的本质是智能体调用不是普通API调用它内部的LLM推理时间是天然开销不能用传统微服务“几百毫秒返回”的预期去设计。我的解法是把同步调用改成异步化Agent-Reach执行层收到请求后先落库生成request_id返回“已受理”然后通过RabbitMQ把任务投递给目标Agent的AdapterAdapter执行完成后再回调结果接口。路由层、执行层都彻底异步化之后超时问题消了系统吞吐也上来了。4.2 上下文爆炸把内容传给Agent是愚蠢的做法另一个血泪教训是上下文传递。早期我让A Agent把完整对话历史一股脑传给B Agent结果B Agent内部又要调大模型Token直接爆炸一个请求烧掉十几万Token成本瞬间失控。后来我做了两个改动。第一Agent-Reach引入上下文仓库Agent之间传递的不是对话内容本身而是一个context_ref也就是上下文的引用地址被调用方按需从仓库里拉取。第二给每次调用设置token限额超过限额就截断或要求调用方精简上下文。这个设计和分布式系统里的消息引用替代消息复制是同一个道理省下的成本和延迟非常可观。4.3 死循环调用必须有护栏第三坑是死循环。测试环境里出现了一次诡异的现象客服Agent调了数据分析Agent数据分析Agent为了补充数据又调了客服Agent的某个报表功能两个Agent互相调用停不下来最后把下游系统打挂了。这个问题的根源是Agent-Reach完全信任了路由结果没有任何护栏。我现在给每个调用请求都加上两个保护参数max_depth和call_chain。call_chain是携带的调用链路径数组每次调用前检查目标AgentID是否已经在链路上出现过出现了直接拒绝并报“循环调用”。max_depth是全局最大嵌套深度超过限制同样拒绝。自打这两个护栏上线循环问题再也没出现过。4.4 常见问题速查表最后把几个高频问题整理成一张表方便你快速定位现象可能原因排查思路路由结果不稳定同样的诉求走到不同Agent向量召回的Top K候选质量不高检查AgentCard的description是否写清楚了边界词必要时人工添加同义词或场景示例调用成功率不高但路由层日志正常目标Agent的执行层超时或资源不足看RabbitMQ队列积压情况、目标Agent的并发池配置权限被误拦截访问控制表配置错误或AgentID不匹配核对caller_agent_id和表里的agent_id是否完全一致注意大小写审计日志丢失日志写入PostgreSQL失败缓存队列满了检查数据库连接池配置起一个独立的审计落盘进程Agent批量注册后路由变慢召回阶段在每次请求时都全量计算AgentCard相似度把向量预计算出来放Redis缓存定时刷新我的几点体会做了几个月Agent-Reach之后我最大的感触是这个项目本质上解决的不是技术问题而是协作问题。技术上实现一个路由、一个注册中心、一层协议封装都算不上难真正难的是让所有接入的Agent团队愿意遵循同一套规范来描述自己的能力和边界。我的做法是不搞强制统一而是先接入两三个核心Agent做出样板用事实告诉其他团队“接入Agent-Reach之后别人能找到你的Agent了你的Agent也能找到别人的了互相调用的效能提升肉眼可见”。当一个平台能让参与方都获利的时候规范就不再是负担而是基础设施。如果你也在做多智能体架构建议别急着上复杂的大平台先按Agent-Reach的思路搭一个最小可用版本把注册描述、语义路由、执行异步化这三件事做好剩下的事情会顺很多。后面的扩展方向我还在试动态伸缩Agent实例、基于反馈的路由策略优化、跨组织间的Agent联邦触达有机会再单独写一篇。