如果最近你也在搞AI应用一定有一个很明显的体感单个Agent好做多个Agent难搞。上个月我刚把团队内部代号为Agent-Reach的多智能体接入框架从内部工具转成了正式项目上线一周接入了12个业务场景的27个Agent总量不算大但把此前散落在各个项目里的重复开发彻底收口了。这篇就聊聊这个项目为什么长这样、核心模块怎么拆、以及我在落地过程中踩过的那些坑。Agent-Reach 不是什么炫酷的大模型它解决的是非常朴素的问题当你手里有十几个能力各异的Agent时到底怎么让它们被统一管理、按需调度、安全地把活干完。适合正在做多Agent应用的人参考不管你是独立开发者还是团队里的技术负责人下面这套设计思路和实操细节都能直接搬。1. Agent-Reach 出现的背景1.1 智能体孤岛我们到底在解决什么问题先说一个真实场景。我所在的团队有十几个业务小组半年内各个组分别做了客服问答Agent、工单分类Agent、舆情监控Agent、报表生成Agent、合同审查Agent。结果就是每个Agent都有自己的鉴权逻辑接入方式五花八门有的走HTTP有的走消息队列有的干脆是把模型放在一个内网服务里直接调。上层业务方想用这些能力只能挨个对接文档还经常过期。同一个多轮会话需要先后调用三个Agent时状态在各家自己手里维护一断就乱。想加一个统一的上报、限流、审计的能力发现每个Agent都得改一遍代码。这种状态我用一句话概括智能体孤岛。Agent本身能用但彼此之间、Agent和业务之间都缺一个“公共层”。Agent-Reach 的出发点就是把这层补上让上层业务不再直接面对一个个Agent实例而是面对一个统一的“接入面”。我考察过市面上一些编排框架发现它们大多把重心放在“工作流编排”上比如定义DAG、串行执行步骤、绑定模型参数。但我们的诉求其实更底层先把连接问题解决掉再谈编排。很多团队连Agent的注册、发现、统一调用都没做好直接上复杂编排框架结果就是配置比业务代码还多。1.2 为什么不做单体编排而是做接入层这里有个关键取舍Agent-Reach 刻意不承担“流程引擎”的角色。它只做三件事注册、路由、网关。为什么因为流程编排本质上是业务逻辑今天A流程是“客服先分类再回答”明天B流程是“先查库存再改订单”这些应该由业务层的编排器或者Agent本身决定而不是让一个底层框架把流程写死。把Agent-Reach 定位成“接入层”还有一个额外好处对已有的Agent零侵入。我们的合同审查Agent是用Python写的工单分类Agent用的是Java舆情监控Agent甚至直接调外部SaaS接口。接入层只需要统一它们的调用协议和返回格式不需要重写任何业务逻辑。这个决策在后面几个月里帮我们省掉了大麻烦因为其他小组可以各自独立迭代自己的Agent只要保证出入口遵守约定即可。所以Agent-Reach 的本质是一套“Agent中间件”类似你熟悉的API网关只不过它网关的对象从普通的REST服务变成了“有状态、会对话、需要记住上下文”的Agent。2. 整体架构与核心模块拆解2.1 五层结构的设计Agent-Reach 从顶层往下拆分五层每层解决一个独立问题。我在设计时强制自己遵守一个原则层与层之间只通过接口通信谁也不能越层调用。层级职责核心问题接入层统一对外提供HTTP/WebSocket接口业务方怎么调用协议层定义请求/响应/事件的标准格式Agent间消息长什么样路由层根据意图分配Agent谁来处理这次请求会话层管理多轮上下文与状态怎么记住前面的对话治理层限流、鉴权、审计、监控怎么保证安全和稳定这个结构不是一开始就拍出来的是踩了两次坑后才定的。第一次我们试图把“会话状态”放进路由层结果路由规则一旦热更新所有会话就跟着失效。第二次我们把鉴权放到了接入层最前面但后来发现不同的Agent需要不同的API Key必须把鉴权下沉到路由完成之后。所以最终形态是接入层只负责建立连接鉴权在路由层确定目标Agent之后再做。2.2 协议层Agent-Reach 里的最小交互单元协议层是整个框架的地基。Agent-Reach 没有发明新协议而是定义了一组轻量的JSON消息结构。核心是三个信封类型AgentRequest请求消息包含session_id、intent、payload、priority。AgentResponse响应消息包含session_id、status、content、metadata。AgentEvent异步事件包含event_type、source_agent、data。这里有一个当初争论很久的点为什么不直接传原始文本给Agent原因很简单Agent-Reach 在一个请求生命周期内可能要经过“入口Agent分流 → 专业Agent处理 → 结果合流”三个阶段。如果只传文本中间层无法知道该把文本转给谁。所以我们让每个请求都带一个轻量的intent字段它不要求是复杂的语义结构只是一个字符串标签例如intent: customer_service.refund。路由层只需要按前缀和权重匹配这个标签就能完成分发。协议层另外一个细节是版本号必须带在信封上。我们曾经忽略这件事结果一个Agent升级返回格式后调用方还在用旧字段解析线上事故。后来明确规定所有消息必须带protocol_version: 1.2升级不兼容版本时强制改版本号路由层根据版本号决定是否放行。2.3 路由模型从固定路由走到能力路由Agent-Reach 的路由模型经历了两次迭代。第一版是固定路由配置文件里写死“意图A → Agent1”非常直观但缺陷也很明显同一个意图会有多个Agent都能处理固定路由无法容灾Agent1挂了请求就失败了。第二版我们改成能力路由每个Agent注册时上报自己具备的能力例如capabilities: [refund, order_query]。路由层收到请求后先根据intent过滤出具备该能力的Agent候选集再结合权重、负载、故障状态综合评分。评分公式不长但管用score 0.5 * (1 - 当前负载/最大负载) 0.3 * 静态权重 0.2 * 近5分钟成功率这个公式的权重是我们用历史数据调出来的。最初静态权重占0.6结果运维把一个新上线的Agent权重配高了流量全打过去把那个服务打崩了。后来把“当前负载”和“成功率”拉进来才让路由真正有了自适应能力。注意这里的负载不是CPU而是Agent侧上报的在途请求数因为Agent主要瓶颈是并发会话数而不是CPU。3. 从零接入搭建一个最小可用系统3.1 环境准备与部署Agent-Reach 的核心是一个无状态网关服务状态全部丢给Redis路由规则存在数据库里Agent本身可以分布在任意网络可达的位置。它在我的环境里部署方式很简单一个Docker Compose文件就能拉起来version: 3.8 services: agent-reach: image: agent-reach/gateway:1.2.0 ports: - 8080:8080 environment: AGENT_REACH_REDIS_ADDR: redis:6379 AGENT_REACH_ROUTE_TABLE: /config/routes.yaml AGENT_REACH_REGISTRY_TYPE: consul AGENT_REACH_REGISTRY_ADDR: consul:8500 volumes: - ./routes.yaml:/config/routes.yaml depends_on: - redis - consul redis: image: redis:7-alpine consul: image: hashicorp/consul:1.16 command: agent -dev -client0.0.0.0两个关键设计说明一下。为什么用Redis存会话因为我们要求网关无状态任意一个网关实例都能处理同一个会话的后续请求Redis的过期时间顺便解决了会话泄漏问题。为什么注册中心用Consul而不是直接写配置文件因为Agent实例会动态扩容缩容固定配置没法及时感知实例变化。Agent启动时向Consul注册自己的地址和能力下线时自动注销路由层每次取的是实时实例列表。3.2 注册一个自定义Agent注册Agent比我想象中简单。任何语言只要能HTTP回调就能接入。这里给一个Python示例假设你手上已经有一个处理退款意图的Agentimport requests agent_info { name: refund-agent, endpoint: http://10.0.0.15:9001/agent, capabilities: [refund, order_query], weight: 10, max_concurrency: 20, auth_token: sk-refund-2024 } resp requests.post( http://agent-reach:8080/registry/register, jsonagent_info, timeout5 ) assert resp.status_code 200注册成功后Agent-Reach 会立刻给这个Agent发送一个健康检查请求路径是GET /healthz。这要求每个Agent必须实现这个接口。踩过坑才知道为什么如果Agent不实现健康检查路由层无法感知Agent进程是否还活着只能等调用超时才摘除那会儿用户已经感受到了失败。Agent被调用的方式是Agent-Reach 把原本的业务请求包装成标准的AgentRequestPOST到Agent的/agent端点。Agent处理完返回AgentResponse。同步场景下整个链路就是一个简单的HTTP请求异步场景则需要Agent主动回调Agent-Reach 的/events/report接口。3.3 路由规则配置与联调部署和注册完事后还要把“意图”和“能力”建立关联。Agent-Reach 的路由规则文件是YAML结构很简单routes: - intent_prefix: refund require_capability: refund session_required: true timeout_ms: 8000 fallback_intent: human_handoff - intent_prefix: order.query require_capability: order_query session_required: false timeout_ms: 1500这个配置文件上线后可以被网关热加载不需要重启进程。联调时有个技巧先用一个假的Agent直接返回固定话术的服务跑通全链路再切到真实Agent。这样做的好处是能把“框架问题”和“Agent问题”剥离开。我第一次联调时直接接真实Agent出了问题查了很久才发现是Agent自身有个NPE异常跟Agent-Reach 一点关系都没有。联调过程中一定要验证三种返回结果成功、Agent业务异常、Agent超时。Agent-Reach 里这三者在响应体里都有标识调用方应该分别处理。但很多业务方只写了成功分支异常分支全部靠默认的500兜底导致用户看到的是笼统的“系统错误”。后来我们强制要求接入方必须处理status: agent_error的情况。4. 调度细节会话、并行与降级4.1 多轮会话状态如何保持Agent-Reach 最容易出错的地方就是会话状态。一次用户请求可能涉及多个Agent比如客服场景里“用户先问订单状态再问能不能退款最后问退款多久到账”这三句话可能被路由到订单查询Agent、退款Agent、以及一个话术生成Agent。这三个Agent需要共享同一个上下文否则第二句话就不知道用户在说哪笔订单。Agent-Reach 的方案是会话上下文不由Agent保存而是由Agent-Reach 统一保存请求发出之前注入到消息里。具体来说Redis里存一个session:{id}的Hash结构包含原始对话历史、当前实体、前序Agent输出摘要。每次路由前Agent-Reach 会取最近N轮摘要拼进AgentRequest的payload.context字段。这里有一个很实在的参数N到底取多少我们测试后发现直接把完整历史丢给Agent不仅占用token而且会让Agent混淆“用户说过什么”和“系统推断出什么”。最终我们把历史分成两层原始轮次最多5轮超过5轮的压缩成摘要摘要由大模型每10轮生成一次。这样既不丢关键信息又控制输入长度。4.2 多Agent并行与结果合并有些场景下一个请求需要多个Agent独立处理后合并结果。比如用户问“这个商品能发货到哪个地区以及保修政策”这需要发货Agent和售后Agent同时工作。Agent-Reach 支持在路由层配置parallel组网关会同时在协程/goroutine里调用多个Agent然后做结果合并。并行最需要注意的是超时叠加问题。很多人以为并行调用时总耗时等于最慢的那个。实际上如果三个Agent分别设置了2秒超时它们并行发起总耗时就约等于最慢的2秒而不是6秒。前提是超时计时是共享同一个deadline而不是各自起一个计时器。Agent-Reach 的实现是统一用context.WithTimeout生成一个总deadline传给所有子调用这个细节救了不少次线上体验。合并结果也有讲究。最开始我们简单拼接两个Agent的文本结果用户看到一段话里前后矛盾。后来我们用了一个轻量级的合并策略每个Agent返回时必须带confidence置信度和conflict_hint冲突提示。合并层发现两个Agent答案冲突时以置信度高者为准但会把另一个答案作为补充说明给用户而不是硬塞。4.3 失败降级与人工兜底再坚固的系统都会失败。Agent-Reach 把降级分成三级一级降级同能力Agent切换。路由候选集里有两个退款Agent第一个超时后自动切到第二个。二级降级意图重路由。所有具有该能力的Agent都不可用时尝试路由给同领域的泛化意图Agent比如“退款专员不可用转给通用客服”。三级降级人工兜底。前面都失败时不再尝试调用Agent直接生成一张人工工单把会话上下文完整转给人工坐席。三级降级里有个容易被忽视的细节降级时要修改intent字段并通知调用方。否则调用方拿到的响应跟预期意图不匹配容易产生误解。我们维护了一个degradation_log记录每个请求被降级的原因、调度路径、耗时每周Review一次发现某个Agent经常触发降级就直接推进它的稳定性改造。同能力切换这个方案我建议做一次混沌演练。我们每个月手动把线上某个Agent停掉观察路由层是否在3秒内感知并切换。第一次演练就出了事故健康检查的探测间隔是10秒也就是说Agent挂了以后最多还有10秒流量会打过去。后来把探测间隔改成3秒切换延迟才符合预期。5. 性能、限流与参数调优5.1 三个必须提前想清楚的数字Agent-Reach 配置里有一组数字最好在项目启动前就定好否则后面改起来到处受影响单Agent最大并发。单位是“会话数”不是“QPS”。因为一个会话内部可能有多轮消息占用的连接和上下文资源远超单次请求。我们的经验值是单Agent实例的Redis连接池大小的70%。网关侧会话超时。一个空闲会话多久算失效这个和业务强相关客服场景10分钟数据分析场景可能30分钟。短了用户多问几句就要重建上下文长了Redis里堆积大量过期Key。路由缓存TTL。Agent能力列表不是实时查询注册中心的那样太重。我们设置TTL为5秒但Agent上下线时通过事件通知主动刷新缓存TTL只是保底兜底。这三个数字挂到配置文件顶部并加注释说明它们之间的关系。后来接手维护的小朋友告诉我这是他们最快的上手入口。5.2 限流、超时和重试配置Agent-Reach 的治理层提供三种保护机制。它们的配置对象不同别搞混入口限流按调用方AppID维度控制每秒最大请求数。这个主要防上游异常流量。Agent出口限流按目标Agent维度防止某个调用方把单个Agent打爆。重试策略仅在“连接异常”和“超时”两种情况下允许重试业务异常绝不重试。重试次数和退避策略我也给一个经过验证的配置max_attempts: 3 initial_interval_ms: 200 max_interval_ms: 2000 multiplier: 2.0简单说就是首次失败等200ms重试一次再失败400ms再800ms最多3次。为什么上限设3次因为大多数Agent的瞬时故障连接闪断、GC暂停在几百毫秒内都能自愈3次足够覆盖。超过3次说明是持续性问题再重试只会放大压力。这个表可以用在排查时的参考。5.3 可观测性怎么落地Agent-Reach 让我最痛的不是功能开发而是排障。一个全链路涉及“调用方 → 网关 → 路由 → Agent → LLM调用”任何一个环节慢都可能导致整体超时。没有可观测性就只能靠猜。我们的方案是每个请求进来就生成一个trace_id并把它贯穿到所有日志和响应头。Agent-Reach 里每个Agent调用的开始、结束、失败都会产生指标和日志指标进Prometheus日志进Elasticsearch。我重点加了一个自定义指标叫agent_route_mismatch_total用来统计“路由层预测的意图”和“Agent实际执行后返回的意图”不一致的次数。这个指标的值意外地有用它直接暴露了意图标注质量的问题。比如客服Agent收到intent: refund却返回一个关于物流的回答那要么是意图标注错误要么是Agent没按协议干活。这类问题靠人工看日志根本看不到全貌只有聚合指标才能暴露规律。6. 踩坑实录与常见问题速查6.1 我在落地中遇到的4个典型问题问题1Agent返回的JSON里有非法字符导致链路报错。有一个Agent返回的content里包含了一个未被转义的换行符网关的JSON解析器直接抛异常。这是最low但最常出现的问题。解决办法是网关不做全量校验而是用“宽进严出”策略Agent返回非法JSON时网关先把原始内容记录下来然后包装成一个agent_error响应返回给调用方同时告警。这样至少业务方不会看到系统500。问题2会话上下文泄漏到另一个会话。这是我们犯过最严重的错误。当时复用了Redis的session key生成逻辑没有纳入app_id维度导致两个不同业务方如果用了相同的用户ID会读到彼此的会话。这个Bug查了一整天才定位。教训是所有session key必须是{app_id}:{user_id}:{session_id}三段式缺一不可。Agent-Reach 后续版本直接在框架层强制了此格式堵住了人为失误的空间。问题3Agent升级后路由规则没变但行为变了。一个工单分类Agent升级了模型分类结果变了但能力注册没变导致所有流量都还是打给它。问题是Agent能力变更没有被显式标示。后来我们规定Agent版本升级必须递增versionAgent-Reach 检测到版本变化后自动将新版本置为“金丝雀”状态只接收5%流量观察指标健康后自动放开。这个机制帮我们避免了一次大规模回归。问题4并行调用的子任务一个失败导致全链路失败。最开始实现时并行组里一个Agent失败会直接让整个请求返回失败。后来改进为子任务失败不影响同批其他Agent返回失败Agent生成一个占位段落在最终结果中说明“该模块暂时不可用”。这样用户的体验是能拿到部分答案且知道哪里缺失。这个设计的心理感受差别很大用户对“部分可用”的容忍度远高于“整个功能故障”。6.2 不容易注意的3个细节细节1健康检查一定要带业务指标。Agent-Reach 默认健康检查只检查进程存活但我强烈建议在健康检查响应体里带上ready字段它表示Agent内部依赖数据库、模型服务、缓存是否就绪。我们曾经有Agent进程活着但依赖的外部模型服务超时导致所有请求都失败。路由层只看存活没有用必须看ready才是真正的健康检查。细节2会话过期时间要比业务空闲会话时间长一点。这是个时间差问题。如果业务层定义的会话空闲超时是10分钟Agent-Reach 的Redis过期时间建议设为12分钟。因为业务层可能在下发一条消息前要做一轮计算比如生成推荐内容这个时间不计入“空闲”但Redis可不管。不够这个余量的话会话会被Redis提前删除导致后续消息找不到上下文。这个细节我们是从一次“用户说了两句话间隔11分钟第二句丢失”的工单里发现的。细节3所有Agent的响应时间要按分位数观测别只看平均值。我们的购物助手Agent的平均响应时间一直是900ms看起来很好但P95其实到了6秒。因为有一部分请求会触发复杂的多步推理少数慢请求拖垮了体验。如果只看平均值这类问题根本发现不了。Agent-Reach 的监控面板强制显示P50/P95/P99三条线这才把“少数慢请求”暴露出来。后来给慢请求单独加了一条“快速兜底路径”P95才从6秒降到2.2秒。最后分享一个实操小技巧Agent-Reach 里我最喜欢的一个能力是路由规则预览。每次修改路由配置之后不必直接上生产可以先用一个调试接口传一条模拟请求看路由层会把它分给哪个Agent、评分是多少、超时设置是多少。这个功能帮我省了大量联调时间。很多配置问题在预览阶段就能发现不需要真的把生产流量发出去验证。我个人在实际操作中的体会是多Agent系统的复杂度不是来源于Agent本身而是来源于“连接和治理”。Agent-Reach 能把这个问题收敛到一个可控范围内但前提是接入方愿意遵守协议、上报真实状态、接受统一治理。如果你正在被多Agent的接入混乱困扰不妨按这套思路搭一个轻量级接入层从两三个Agent开始先跑通会话保持和路由切换这两个关键链路再逐步扩大场景。这东西前期越简单后期越稳定。