Agent-Reach：智能体网关架构设计与多Agent编排实践

从去年开始，我一直在做一个非常具体的系统——Agent-Reach。起因其实很朴素：团队里Agent越建越多，但彼此之间几乎靠“人肉集成”，谁要调用谁，得先翻文档、再拉群、再对参数，一个Agent想复用另一个Agent的能力，链路长得让人崩溃。后来我把这套东西做成了一个独立的智能体服务接入与编排网关，让Agent像微服务一样被注册、被发现、被路由、被编排调用。今天这篇就把整个项目的核心思路、架构设计、落地过程中的坑和实践经验完整写出来，希望对正在搞多智能体协作或者企业级Agent平台的同学有实际参考价值。

Agent-Reach到底是做什么的？你可以先记忆成一句话：它是智能体世界的API网关。微服务时代，我们靠注册中心和服务网关解决服务发现、负载均衡、路由和鉴权；Agent时代，同样的问题出现了——Agent能力如何统一暴露？请求进来后如何路由到正确的Agent？多个Agent如何编排起来完成复杂任务？Agent-Reach就是回答这几个问题的。你不需要关心Agent是跑在本地进程里、云函数上还是别人的OpenAI兼容接口上，Agent-Reach统一把它们纳入一个可寻址、可调度、可观测的体系里。这套思路尤其适合：企业内部已有多个独立Agent、正在做Agent平台化、或者想把多Agent协作从demo搬到生产环境的团队。

1. 为什么需要Agent-Reach：多智能体协作的“触达”困境

在拆架构之前，得先把我当时面临的问题摊开。如果只是写两个Agent互相调用玩，那根本不需要这套东西，写死接口就行。但一旦Agent数量超过五个、调用链超过两层，问题就完全是另一回事了。

首先，Agent的接入协议五花八门。同一家公司里，有的Agent是基于LangChain写的Python服务，暴露的是FastAPI的JSON接口；有的是用扣子（Coze）搭的，只能通过平台的开放API调用；还有的是外包团队交付的，跑在K8s里，连文档都不全。你想让它们互相调用，等于要写N个适配器，每个适配器都要处理独立的鉴权方式、参数命名风格、错误码约定。这跟当年微服务前期乱接HTTP接口是一模一样的痛。

其次，Agent的“能力发现”是空白的。微服务有注册中心，Agent没有——想要某个能力，你得先问一圈同事“谁知道哪个Agent能查库存”，然后在聊天记录里翻半天。而且Agent的语义能力跟服务接口不同，你说“帮我查一下最近的订单”，它可能对应查询接口、分析接口、预测接口三个不同Agent的职责。没有一层语义路由，调用方就得自己做意图判断，耦合度直线升高。

更致命的是，Agent之间的调用往往不是单跳的。一个“生成销售周报”的任务，可能需要先调数据Agent拿报表，再调分析Agent总结变化，最后调写作Agent生成自然语言周报。中间任何一步超时、失败、参数不匹配，整条链子就断了，而且你根本不知道断在哪一环——因为你没有全链路的追踪ID，每个Agent日志各写各的，排查一次问题至少要半天起步。

我当时意识到，这不是靠加几个HTTP客户端能解决的，而是缺了一层“Agent间的基础设施”。Agent-Reach的定位由此确定：它不生产智能，只负责让智能“找得到、接得上、串得起来”。说得更直白点，就是给Agent们一个统一的地址簿、一根标准插线板、一套调度总机。

2. 核心架构拆解：一个网关如何管住一群Agent

Agent-Reach的架构其实并不复杂，关键在于分层清晰。整套系统跑起来后，从入口到Agent大致经过五层：接入层、注册层、路由层、执行层、治理层。下面我把每一层的关键设计和选型理由讲清楚，这些也是整个项目最核心的技术骨架。

2.1 接入层：用统一协议抹平Agent之间的“方言”

接入层解决的是前面说的协议百花齐放问题。Agent-Reach不要求所有Agent改造成同一套语言，而是提供适配器机制，由网关侧主动兼容各种协议。我做的第一版支持三种接入方式：OpenAPI JSON、MCP（Model Context Protocol）流式接口、以及自研的Agent-Reach Agent SDK。前两种面向已有系统，第三种面向新开发的Agent。

对这种统一接入的价值，可以做一个直观对比：

关键点是这个内部的“标准Schema”。我给每个被纳管的Agent定义了一套统一的Request-Response模型，这个模型既是协议也是契约。比如调用任何一个Agent，入参都统一为{ task: string, context: object, config?: object }，出参统一为{ status, data, meta }。原始服务的入参格式差异，全部在适配器里完成映射。这样做的好处是，上层编排逻辑可以完全不关心具体Agent的参数细节，只操作标准Schema，整个编排层写起来就像在填表格，而不是在拼接五花八门的JSON。

为了降低新Agent的接入成本，我写了几个开源适配器模板。最省事的路径是改动最小的HTTP转发型适配器——你只要在Agent-Reach注册接口地址、请求方法、参数映射规则，网关就能把标准请求翻译成目标Agent能理解的样子。实测下来，一个只有“查询接口”的普通Agent，半小时内就能完成接入。

2.2 注册层：Agent注册中心与元数据管理

注册层是Agent-Reach的“通讯录”。每个Agent进来要做实名登记，登记的信息不只是名字和地址，而是一整套描述能力、资源、状态的元数据。

我给Agent设计的注册字段包括：

• agent_id：全局唯一标识，建议按业务域命名，比如agent.finance.report；
• agent名称与描述：人类可读的说明，用于后续的语义路由和文档生成；
• 协议类型与接入端点：适配器对应类型，HTTP地址或内部RPC名称；
• 能力清单（skills）：这个Agent能做什么，每个能力对应一个能力名称和参数Schema。比如数据Agent的能力清单里有query_sales_data、query_inventory_data；
• 限流配额与优先级：该Agent每秒能承受的请求量、调度时的权重；
• 健康状态：由网关定期探活，分healthy/degraded/unhealthy三档。

最初这一层我做得比较轻，就一张注册表。但很快发现问题：Agent的能力会演进，同一个能力在不同时间可能有不同参数量级。比如分析Agent的总结能力，在数据量小的时候和大的时候行为差很多。后来我在注册表里加入了版本字段，每次Agent发布新版本，不是覆盖注册，而是新增一个版本记录，路由层默认路由到最新稳定版，同时支持灰度路由到历史版本。这个设计在后续上线新Agent时帮了大忙，我可以把流量按比例切到新版本，观察一段时间再完全切换，而不影响线上主链路。

注册层还有一个容易被忽略的点：注销与健康检查的联动。最初我把“探活失败”和“剔除注册”做成强一致关系，结果Agent某个方法因业务逻辑卡死时，整个Agent被误判为死亡，路由层直接把它下线，引发了一轮生产事故。后来改成“探活失败只标记degraded，流量摘除但不删除注册，恢复后直接重新纳管”，这才符合实际运维场景。

2.3 路由层：从“找服务”到“找能力”的语义路由

路由层是Agent-Reach最核心，也最考验细节的部分。微服务路由基于服务名和负载均衡，但Agent-Reach必须多做一层：语义路由。因为调用方很多时候并不知道该找哪个Agent，它只知道“我要做什么”，由网关来决定这个“任务”应该由哪个Agent来承接。

语义路由我采用的是“关键词召回+向量相似度+规则过滤”三级流水线，按成本从低到高排列：

1. 规则硬匹配：如果请求里的task字段完全匹配某个Agent能力名（比如query_sales_data），直接命中，不走后续逻辑。这是成本最低也最准确的一档。

2. 关键词召回：如果硬匹配没中，就把task做分词处理，跟注册表里的能力名和描述做BM25召回，取Top5候选Agent。

3. 向量重排：用Embedding把task和召回候选的Agent描述各转成向量，算余弦相似度，取最高分且超过阈值的Agent。

这套三级设计背后的考量很简单：不能一上来就用向量库，因为大模型Embedding有延迟，每次请求都做向量检索，网关压力太大，也不够稳定。先用规则和关键词把绝大部分请求在低延迟区间内消化掉，向量重排只处理那些无法确定归属的长尾模糊请求。实测下来，80%以上的请求在第一级就能准确命中，这大大降低了路由层的平均响应延迟。

但路由层还有个更微妙的点：同一个任务，可能多个Agent都能做，但质量差异很大。比如“写一段会议纪要”，会议Agent、写作Agent、综合助手Agent可能都具备这个能力。这时候只靠语义相关度是不够的，我还加了上下文偏好字段。调用方可以在请求里带一个preferred_agents列表，路由层优先选择列表内的Agent；也可以带required_skills，路由层只从具有这些技能的Agent里挑。这相当于给了调用方“软指定”和“硬约束”的两种干预手段，既保留路由的智能性，又确保关键业务不受语义判断的不确定性影响。

还有一类请求在路由时要特殊处理——多Agent组合任务。路由层识别到task涉及多个能力域时，不会只返回一个Agent，而是返回一组Agent及它们之间的调用顺序建议。比如“分析这周销售数据并生成英文汇报邮件”，路由层会返回数据Agent→分析Agent→写作Agent的链路，这个链路会交给执行层去真正编排执行。这一步让我后期在做复杂任务组合时省了很多事，因为路由层的“建议拓扑”实际上相当于提前做了一版编排规划。

2.4 执行层：一次任务在多个Agent之间的编排与穿梭

执行层是真正干活的地方。当一个请求被路由到单个Agent，执行层的工作很简单：调用适配器、等待结果、返回。但如果是多Agent编排，执行层就要负责任务的拆分、上下文传递、结果聚合和失败恢复。

我采用的编排模型是基于“有向无环图（DAG）”的，每个节点是一个Agent调用，每条边是数据依赖。这个模型的好处是：可以并行执行无依赖的节点，可以用前驱节点的输出作为后继节点的输入模板填充，而且天然支持拓扑排序检测死循环。为了让读者直观理解，用一个具体的实际配置举例：

workflow: id: wf.sales_report_daily nodes: - id: fetch_data agent: agent.data.query input: table: sales_daily date: ${request.date} - id: analyze_trend agent: agent.analyst.trend input: data: ${fetch_data.output} - id: generate_report agent: agent.writer.report input: analysis: ${analyze_trend.output} format: markdown edges: - from: fetch_data to: analyze_trend - from: analyze_trend to: generate_report

这段配置展示了一个最典型的链式流程：数据查询Agent拿到原始数据，传给分析Agent生成趋势摘要，再由写作Agent写成报告。配置里的${fetch_data.output}就是节点间数据传递的关键——执行层会解析出执行图谱，等fetch_data节点返回后，把它的输出填入analyze_trend的入参，再触发执行。

实际执行链路里，我加了三个我认为非常重要的机制：

第一，超时熔断。每个节点都有独立的超时时间，如果某个Agent持续超时，执行层会标记该Agent不健康并触发熔断，后续编排默认跳过这个Agent或走降级分支。没有这层保护，一个慢Agent会把整条链路拖死。

第二，上下文窗口管理。Agent之间传递的数据可能非常大——查询Agent可能拉出一张几十万行的表，如果原样传给分析Agent，直接打爆上下文。我的做法是节点输出支持定义“透传区域”和“摘要区域”，默认情况下只把摘要和Schema信息传给下一个Agent，全量数据持久化到对象存储，由下一个Agent按需引用。这是从实际教训里总结出来的，第一版就是把大数据直接往下一个Agent丢，迟滞和费用都让人肉疼。

第三，失败补偿。编排执行中某个节点失败，并不一定整个流程就失败。我给每个节点配了重试次数和降级策略，降级策略可以是“跳过此节点、把报错信息作为该节点输出传给下游”，也可以是“由备用Agent执行同一任务”。最开始时我觉得降级策略要越多越好，后来发现过度降级会掩盖真实业务问题。现在我的原则是：只有确定性错误（如格式转换失败、临时缓存未命中）才自动重试或降级，业务逻辑错误一律直接上报，不掩盖。

执行层还要考虑人类介入的“断点续跑”场景。在Agent-Reach中，我内置了人工审批节点的概念，编排执行到该节点时暂停，等待审批结果再决定继续或终止。企业内部很多Agent任务涉及权限操作或对外发送动作，如果没有这层人工干预，自动化反而会带来风险。

3. 语义路由的进阶：意图消解、候选排序与故障转移

前面讲了路由的基本结构，这部分单独拎出来写，因为它值得更多笔墨。Agent-Reach上线后，我花最多时间调优的就是路由准确率和极端场景下的兜底行为。泛泛的“比语义相似度”在demo里没问题，但要扛住复杂真实的业务流量，需要处理三类更深的问题。

3.1 意图消解：同义表达与复合意图的归一化

用户或上游系统发出的task描述通常是口语化的、不规范的。比如“我要这个月卖了多少手机的数据”“本月手机销量”，两者表达不同，但意图都是要销量数据。路由层在做匹配前，先做一次意图消解，将口语化描述归一化成标准能力名加参数列表。

以“帮我看看华南区上个月的订单额，跟同行对比一下”为例，Agent-Reach的消解逻辑需要做两件事：一是把“华南区”和“上月”解析成结构化参数（region=华南，date_range=上月），二是识别出“订单额”和“跟同行对比”两个子任务，这个请求实际要路由到两个不同的能力：query_order_amount和compare_industry_benchmark。这个拆分结果会传给执行层，让它按DAG编排这两个Agent。

做意图消解，我强烈建议先积累一个“同义短语词表”，用线上日志反向生成。最开始我用大模型做消解，效果好但延迟高、费用高。后来发现，高频请求集中在几十个业务意图上，把这些高频意图的同义说法沉淀成词表，直接命中率能到75%以上，只有完全陌生的表达才丢给大模型兜底。这就回到了成本控制的老话题——大模型很强大，但生产系统的每一层都要思考“是不是每个请求都值得动用大模型”。

3.2 候选排序：引入上下文感知的动态权重

当路由候选有多个Agent时，单一的语义相似度往往不够。比如两个Agent都能生成报表，一个面向管理层、一个面向运营团队，同一个请求给不同身份的人，应该路由给不同的Agent。为此，我在路由层加入了“上下文因子”，对整个候选排序做加权修正。

这些因子包括：

• 调用方身份：调用方Token中带有业务线标识，路由到对应域的Agent时加权；
• 最近成功率：统计过去10分钟各Agent的成功率和平均延迟，质量差的降权；
• 数据可用性：某Agent依赖的底表数据今天未更新，则降权；
• 人工偏好：调用方显式携带preferred_agents，直接加权最高。

加权不是拍脑袋，每个因子通过配置控制参与与否和权重值。在Agent-Reach的管理界面里，我可以对不同业务域设置不同的权重组合。比如对数据分析域，“数据可用性”的权重远高于“调用方身份”；对内容生成域则反过来。这套机制让我在调整路由策略时不用改代码，改配置再发布热更新即可，对运维方来说非常省心。

3.3 故障转移：Agent失联后的兜底路径

路由选出来一个Agent，结果它挂了，怎么办？最坏的情况是直接把错误抛给调用方。Agent-Reach提供两层故障转移机制。

第一层是“同组替换”——注册表里可以为Agent配置agent_group，同一组的Agent被认定为功能等价。路由优先选组内的健康实例，如果首选不健康，自动切到组内其他实例，对调用方完全透明。这类似微服务里的服务实例健康检查，只不过粒度从实例提升到了“具备同类能力的Agent实体”。

第二层是“上级替代”——如果整组Agent都不健康，看注册表里是否配置了fallback_agent。比如企业内自研的销售数据查询Agent挂了，可以配置兜底到供应商提供的通用数据查询Agent，虽然可能少一些定制字段，但至少保住了核心流程。这种兜底必须显式配置，不允许自动寻找——原因很简单，自动找一个不相关的Agent去顶替，很容易产生错误数据，还不如直接失败来得安全。

在生产上，我把故障转移和前面说的注册健康检查联动起来。每个Agent被探活标记为unhealthy后，不是立即从注册表摘除，而是先进入“隔离观察期”，期间流量不导入但探活继续，连续三次探活成功后自动恢复。这个机制避免了Agent因瞬时抖动被冷酷摘除后又频繁注册来回抖动的问题。

4. 生产落地与可观测性：没有追踪和多维度的运维，网关就是黑盒

再漂亮的架构，上了生产不解决可观测性都是灾难。Agent-Reach从第一天上生产起，我就把链路追踪和运行指标当成一等公民来设计。这里的经验非常值得分享，因为多Agent编排的排障复杂度，相比单服务调用高了一个数量级。

4.1 全链路追踪：一个Trace串起所有Agent调用

多Agent编排中，一次用户请求会经历网关、路由、执行层、多个Agent适配器、Agent内部任务处理。任何一个环节出错，如果没有链路追踪，排查问题就像在黑屋子里找一根断掉的线。

Agent-Reach为每个进来的请求生成一个全局Trace ID，从接入层开始透传到所有下游Agent。调用的标准Schema里永远带两个保留字段：trace_id和span_id。每个Agent在处理完任务后，必须在返回的meta里包含这两个字段。这样，我可以把“用户请求”和“Agent内部实际执行”关联起来，即使Agent内部日志是独立系统，只要它打印了trace_id，我就能通过日志平台做关联查询。

Span则按执行模型记录：路由阶段一个span、每个Agent调用一个span、编排等待一个span。每个span记录开始时间、结束时间、输入输出摘要、错误信息。将采集到的Span写入ClickHouse这类分析型数据库，日常排查直接在Dashboards上按Trace ID搜索整条链路的耗时瀑布图。谁慢、谁失败、谁被重试，一目了然。

在调优一次“生成周报超时”问题时，靠Trace很快定位到问题不在写作Agent本身，而是数据Agent在一个特定参数组合下会跑一个未索引的SQL查询，耗时从平均300ms飙升到30秒。这如果在没有Trace追踪的多Agent环境里，光靠各系统自己排查，半天时间都不一定能锁定。

4.2 核心运行指标：五个数字判断网格健康度

除了链路追踪，我定义了一套极简的设备指标，不求多但求有用。运维大屏上固定展示五类指标：

• 请求量：按Agent分维度的请求量和环比变化，用于看流量倾斜；
• 命中率：语义路由各层命中率（规则命中、关键词命中、向量命中、未命中），用于评估能力目录的有效性；
• 成功率：按Agent和按工作流两个维度的成功率，失败时能看到具体错误类型分布；
• 时延：P50/P95/P99分位时延，区分单Agent调用和完整工作流两个粒度；
• 费用：按Agent维度统计的Token消耗和调用金额估算，这个数字直接影响成本优化决策。

这些指标都在Agent-Reach内部聚合后，暴露为Prometheus格式的/metrics接口，由Grafana统一展示。我尤其关注“费用”这个看似非技术性的指标——多Agent协作时，一次复杂任务可能触发十几个Agent调用，每个调用背后都是Token消耗，如果没有费用观测，成本失控是不可控的。曾经某个工作流在高并发下一天烧掉之前一周的预算，就是因为少写了一个缓存节点，而费用指标的缺口让我隔了一天才发现。

4.3 可观测的隐性收益：反向驱动路由和编排策略调整

可观测性不只是为了“出事能排查”，它更深远的价值是反向指导策略调整。我举一个真实例子：上线一段时间后，我注意到某个工作流的成功率只有88%，但每个Agent单独看成功率都在98%以上。结合Trace才发现，问题出在节点间的数据大小上——数据Agent传给分析Agent的数据经常超过分析Agent的接口负载上限，导致调用失败。定位后我调整了节点输出的摘要策略和触发阈值，工作流成功率直接从88%升到99%。这类优化，没有全链路Trace是根本不可能发现的，因为每个组件本身都在正常工作。

这给我的启发是：Agent网关的可观测性设计，不该只盯服务和实例的可用性，而要围绕“任务完成质量”和“Agent间配合质量”展开。服务都活着不代表任务能顺利完成，数据格式不匹配、上下文超限、参数隐式约定失效，这些才是多Agent协作的高频故障源。把观测视野提升到“任务级”而不是“调用级”，问题才更容易浮出水面。

5. 踩过的坑与调优实践：从原型到稳定运行的距离比想象中长

写这篇博文时，我回顾了整个项目从原型到生产稳定运行的过程，最大的感触是：网关本身的骨架一次就搭好了，但细节之处的坑一个接一个。挑几个影响最大、最典型的分享出来，希望能帮后来者少走弯路。

5.1 Agent并发可达性假设的陷阱

第一个坑来自对Agent并发能力的错误假设。微服务网关后面挂着无状态的K8s Pod，副本数可以随便横向扩张；但Agent可能完全不是这样。有些Agent只部署了单个实例，有些Agent对外部API有严格的并发配额，有些Agent的推理后端每次只能处理有限个并发请求。一开始我默认所有Agent都能扛住网关层并发下来的流量，结果线上来了个突发流量，数据Agent直接被压垮，连带整个工作流超时。

解决方式是两层配合：注册表的元数据里显式添加max_concurrency和queue_timeout字段，执行层在编排时做并发预算控制——一个工作流里所有并行节点加起来的并发量不能超过一个预置阈值，超出部分的节点自动串行化执行。同时在每个Agent适配器前加一层轻量级信号量限流，实测把这套加上后，突发流量下各Agent的稳定性显著提升。这个坑的本质是：不要把Agent当无状态服务，它的资源约束和并发能力必须进入调度决策。

5.2 超时与重试的“重试风暴”

第二个坑是重试逻辑的级联放大。最初我给每个节点配置了重试机制，工作流里多个节点失败都会重试。有一天某个底层数据库故障，导致两个上游Agent同时超时，它们的重试请求叠加，把已经故障的数据库又压了几个量级，形成“重试风暴”。

后来我做了三个调整：一是全局重试预算，每个工作流实例只允许执行一次全链路重试，重试后仍失败就不再叠加；二是重试退避必须带随机抖动，防止多个请求在同一时间点重试；三是只有幂等操作允许自动重试——Agent调用如果产生副作用（比如发通知、建订单），一律不自动重试，改为转入人工处理队列。这些调整在任何分布式系统里都是经典经验，但放在Agent场景里尤其重要，因为Agent的调用链更长、节点更多、故障面更广。

5.3 认证与授权：Agent级Token与最小权限

一开始我把Agent的调用凭证统一成一个网关Token，所有下游Agent信任这个Token。后来发现一个严重的权限问题：任何成功通过网关的请求，无论它来自哪个调用方，都能访问全部Agent，这意味着低权限的业务线可以间接通过网关调用高权限Agent。这是很危险的越权路径。

我把认证改造为两层：第一层是调用方认证，网关用API Key或OAuth验证调用方身份；第二层是Agent授权，每个Agent注册时声明允许访问的业务线白名单。调用方Token解析出的业务线信息会写进请求上下文里，Agent适配器在转发请求时校验业务线是否在白名单内，不在则拒绝。做完这个改造后我才敢把Agent-Reach真正开放给公司内部更多业务线使用。权限这个东西，在Agent协作的场景里比传统API网关更复杂，因为Agent的能力边界通常比服务接口更宽泛，等出了事再补救就晚了。

5.4 Schema兼容性：Agent升级导致的隐性破坏

还有一个很隐蔽的坑：Agent发布新版本时，能力参数Schema发生了变化——比如添加了必填字段、改变了响应结构。由于Agent内部处理逻辑是由LLM驱动的，很多变化甚至没有经过严格的接口评审就上线了，导致依赖它的工作流莫名开始返回错误数据或直接失败。

我补充了两道防线：一是注册中心强制要求每个Agent版本关联一份OpenAPI Schema，网关对该Schema做兼容性校验，如果新版本相对旧版本存在破坏性变更（比如删除字段、修改必填项），注册会被拦截，必须显式确认并升级调用方依赖后才允许通过；二是执行层在节点输入填充时做Schema校验，数据在传给Agent前就检查是否满足该Agent申明的入参要求，不满足则快速失败而不是白白把请求发出去等待一个必然的错误。这两道防线让Agent升级带来的破坏从“事后的未知故障”变成了“事前的可控提示”。

6. 从内部工具到通用平台：Agent-Reach的扩展边界与参考实现

项目走到这一步，Agent-Reach已经不只是我手里的内部工具了。它沉淀出了一些可以产品化和平台化的能力边界，这里展开聊聊它的可扩展性，以及如果你也想做一个类似系统，可以从哪里着手。

6.1 模块边界与扩展机制

Agent-Reach的代码结构上，我刻意保持了模块边界的清晰：注册中心、路由引擎、执行引擎、适配器工厂、观测模块互相独立，通过消息和配置解耦。这样做的直接好处是，替换任何一个模块都不会牵连其他模块。比如路由引擎，我做了一版纯规则路由，后来又加了一版语义路由，两者通过策略配置切换，以后如果要做支持用户自定义策略的路由，只需要再实现一个新路由插件即可。

适配器工厂是扩展性最强的部分。目前支持HTTP JSON和MCP协议，但架构上每接入一种新协议，只需要实现一个统一的AgentAdapter接口，在这个接口里完成“标准Schema ↔ 目标协议”的映射。代码示意如下：

class AgentAdapter: def convert_request(self, std_request) -> target_request: raise NotImplementedError def invoke(self, target_request) -> target_response: raise NotImplementedError def convert_response(self, target_response) -> std_response: raise NotImplementedError

新协议适配器的工程量通常两到三天能完成。我把AgentSDK也开放出来了，新Agent直接导入SDK，通过装饰器就能把自己的业务函数注册成标准Agent能力，网关可以直接调度，几乎不用写适配代码。

6.2 多租户与资源隔离

从一个团队的工具走向公司级平台，多租户一定是绕不开的。我做了基础版的多租户支持：租户之间在注册表上逻辑隔离，每个租户只能看到和调度自己命名空间下的Agent；路由策略、限流配额、审计日志也都按租户隔离。资源隔离上没有用完全的物理隔离，因为Agent多数是共享的，但每个租户对共享Agent的调用量有独立配额，避免一个租户的突发流量挤占另一个租户的额度。如果未来租户规模继续增长，可以考虑把注册表和路由层拆成多实例部署，数据再按租户分片。

6.3 与现有RAG/知识库系统的衔接

顺便说一下Agent-Reach跟RAG系统的关系。很多人问我有RAG为什么还需要Agent网关。我的体会是：RAG解决的是“让Agent拥有外部知识”，Agent网关解决的是“让Agent能被安全地识别和调度”。两者根本不冲突——RAG通常作为一个知识型Agent注册到Agent-Reach里，或者是某个Agent内部的检索模块。你在Agent-Reach注册表里看到的可能是agent.knowledge.retriever，它的实现内部走了一套RAG流程。网关不关心Agent里是RAG还是普通的规则代码，只关心它能提供什么能力、是否健康、是否在授权范围内。在大型AI应用架构里，这层抽象是必要的，否则每个Agent团队都要自己解决整个调用链的问题。

6.4 如果从零开始，精简版参考路径

如果读完这篇文章，你也想搭一个轻量的Agent接入与编排层，我建议按这个顺序动手：

1. 先做注册表和简单的HTTP适配器，用配置文件定义几个样例Agent，打通“标准Schema请求 → 适配器 → 具体Agent”的最小链路；
2. 加一个基于规则的简单路由，路由判定条件先用task精确匹配和关键词匹配，跑一版线上日志看覆盖率；
3. 在调用量起来后，再引入语义路由和向量检索，用前面的日志数据做评估集，持续对比路由准确率；
4. 第一版编排只做链式串联，不要一上来就搞DAG，等真的遇到并行执行需求再扩展执行引擎；
5. 从第一天就带上Trace ID和日志打点，后面再补的话成本倍增。

这个路径的核心逻辑是：先把一条链路彻底跑通，用真实请求检验设计，再谈智能化和扩展。我见过不少项目一上来就设计庞大的Agent编排平台，结果核心链路都没走顺，最后反而收不了尾。

7. 写在最后：Agent基建的下一步想象空间

Agent-Reach做到现在的状态，回头最让我满意的不是代码量，而是它带来了一个思路转变：多人多团队协作的多Agent体系，不该通过相互之间的“你接我我接你”来生长，而应该通过一个公共底座来让每个Agent被看见、被调用、被管理。这套思路的合理性，我在几次内部故障和一次跨团队合作中充分体会到了。没有公共底座时，两三个团队之间的Agent协作要靠临时拉会对齐接口；有了底座后，新Agent上线意味着能力目录自动多一个条目，下游团队自行查阅、申请权限、开始调用即可。

当然，它还有很多不完善的地方。比如目前Agent间的会话记忆还是跟随链路的，没有一个跨链路的记忆总线；Agent能力的自动发现也还依赖人工注册，没有做到完全自动化的“能力爬虫”。这两个方向我会继续探索，如果有新的实用成果，再来分享。对我而言，这套系统最直接的收获是：Agent不再是各自孤岛，它们开始像一个团队一样协作，而网关就是让这个团队运转起来的“协作框架”。