1. 项目缘起Agent-Reach 到底想解决什么问题做了小两年 AI Agent 相关的项目我最大的感受是搞 Agent 的人很多但真正把 Agent 落到业务里的人很少。原因倒不是模型能力不够而是 Agent 在真实环境里跑起来之后它怎么跟外部世界对话这件事远比你想象中麻烦。一开始我做的 Agent 只在单条链路上工作用户通过网页聊一句Agent 吐一个结果。Demo 阶段挺顺利展示效果也好看。但等到接企业客户的时候问题就来了——客户要求 Agent 不仅能聊天还得能发邮件、回工单、推送企微通知、调用内部系统 API甚至要跑到 Slack 频道里帮人查数据。而且这些动作不能是散的必须围绕同一个 Agent 的上下文来编排。你能想象一个 Agent 在邮件里解决的问题和它在飞书群里答的问题完全对不上号是什么体验吗Agent-Reach 就是我在这个背景下启动的项目。它是为 AI Agent 设计的一套多通道触达与编排基础设施。核心目标只有一个让同一个 Agent 能稳定、可控、可追踪地触达任意业务渠道同时保证所有渠道的上下文一致消息不丢、不重、不乱序。这个项目不是给你写 Agent 业务逻辑的它更像是一个连接层。它解决的是 Agent 和外部触点之间那“最后一公里”的问题。从技术栈上看它涉及消息路由、渠道适配、幂等控制、超时重试、背压处理、可观测性甚至还包括跟大模型的联动调度。每一样拎出来都能写几千字但更重要的是它们怎么被组合成一个整体。这篇文章我会从设计思路、核心模块、踩坑记录三个维度把 Agent-Reach 从 0 到 1 的完整过程掰开揉碎讲清楚。如果你正在做 Agent 相关的项目或者正准备把 Agent 接入到工单系统、群机器人、邮件等场景里这篇文章应该能帮你少走不少弯路。2. 从“聊得好”到“办得成”触达层为什么值得单独做一个项目2.1 Agent 的“输出”本质上是一次复杂的异步协作先聊聊我在拆解需求时发现的一个大问题。大多数入门教程教写的 Agent本质上就是“输入——模型推理——文本输出”的三段式。但一旦进入真实业务场景Agent 的输出往往不是一个字符串而是一个动作序列。比如先查一下订单状态再给用户回一封邮件告知结果把这次沟通记录同步到 CRM最后在客服工单里打上“已处理”的标签。这四个动作分布在完全不同的系统里需要完全不同的协议和数据格式。订单查询可能走内部 gRPC邮件走 SMTPCRM 有一组 REST API工单系统则只认 webhook。如果这些逻辑全写在 Agent 的代码里你会发现代码里一半是 HTTP 请求一半是重试和异常处理真正的 Agent 逻辑反而被淹没了。所以我做了一个关键决定把“触达”从 Agent 的核心逻辑里拆出来做成独立的中间层。Agent 只管决策至于怎么把消息送达、怎么保证送达之后端到端的一致性全交给 Agent-Reach 处理。这就像你不会在一个业务系统里直接拼 SQL 字符串一样触达也不应该散落在 Agent 的业务代码里。它是横切面就应该被集中治理。2.2 渠道的差异性不是数量问题是模型问题最让我头疼的不是渠道多而是渠道之间的行为差异太大了。就拿两个最常见渠道来说邮件和 IM 群机器人。邮件协议上虽说是 store-and-forward但发出去之后你实际上很难知道对方到底看没看群机器人倒是能即时回调但回调又不是同步的。队列的可靠性、消息时延、失败语义每个渠道都不一样。更别说什么 429 限流、超时断开、签名校验、文本编码这些细节。写适配器写到后来你会发现每个渠道都像一个有脾气的老系统不摸清楚它的脾气你的消息就送不到。所以 Agent-Reach 里所有渠道都被抽象成统一的 Message 模型。对外部渠道的差异尽可能在下层消化上层我只关心事件、路由、状态。这个抽象不完美但正是这种“不完美的统一”把复杂度控制住了。2.3 上下文一致才叫 Agent否则只是接口聚合第三个关键认知是上下文就是 Agent 的生命线。我在项目早期犯过一个错每个渠道独立处理消息结果同一个用户在小程序里问的问题和他在邮件里追问的问题Agent 完全不记得。这在用户体验上是致命的。后来我在 Agent-Reach 里加入了一个跨渠道的会话上下文模块。思路很简单给每个“业务实体”比如一个客户、一个工单绑定一个 context ID所有渠道的消息都通过这个 ID 挂到同一个会话上下文上。Agent 在回复前先把相关上下文捞出来再带着上下文去做决策。这一步是 Agent-Reach 区别于普通消息网关的灵魂所在。它触达的不只是消息本身而是带着记忆触达。看着简单但架构上的影响很大后面我会讲它如何反向约束了路由和数据存储的设计。3. 核心设计思路消息不丢、不重、不乱序是怎么做到的3.1 三层模型接收层、路由层、发送层Agent-Reach 的整体结构我按三层来搭**接收层Ingest Layer**负责接收来自各渠道的原始事件。比如企微回调、邮件 IMAP 轮询、飞书事件订阅。它会做三件事验签、解析、归一化。校验通过后原始事件会被转换成 Agent-Reach 内部的标准 Message然后投递到消息队列里。**路由层Orchestration Layer**是核心决策区。它消费队列里的 Message根据路由规则决定两件事这个消息要不要让 Agent 处理如果处理应该调用哪个 Agent 实例同时它会维护跨渠道的上下文状态把同一个 Context ID 的消息串起来保证 Agent 拿到的上下文是连续的。**发送层Delivery Layer**负责把 Agent 的产出发送到目标渠道。这里不只是把文本丢出去它要处理模板渲染、渠道差异适配、重试死信还要在发送前把状态写入存储以便追踪。这三层之间全部通过消息队列异步连接没有同步阻塞的调用链。为什么这么设计因为渠道的响应时延千差万别有的几十毫秒有的几十秒比如邮件投递如果整个链路同步等下去一个慢渠道会把整个系统拖死。异步化之后慢渠道只是被隔离成队列里的一条消息不会阻塞其他工作。3.2 幂等机制消息重试的前提是知道自己重复了做消息系统的人都知道分布式环境里“恰好一次”是奢侈品“至少一次”是常态。这意味着消息可能重复。重复投递会导致什么问题用户收到两条一样的邮件、一条工单被创建两次。这在业务上是不可接受的。Agent-Reach 的处理方式是给每条消息分配一个全局唯一的Message ID并在消费端做幂等控制。具体做法是在数据库里建一张 dedup 表主键就是 Message ID Handler 组合。消费前先尝试插入插入成功说明这是新消息正常处理插入失败主键冲突说明是重复消息直接跳过。这个方案很简单但细节里有个容易被忽略的点dedup 的时机必须和业务操作绑定在同一个事务里否则还是会出问题。比如你先插 dedup 记录再去发邮件中间服务挂了重启后消息再次投递dedup 表里有记录邮件却被跳过了。因此我们需要把“标记已处理”和“执行业务动作”放在同一个原子范围里。注意幂等不是只有数据库唯一键这一种做法还有基于业务字段的自然幂等比如幂等键由发送方生成。但无论如何一定要在架构上从一开始就把“重复”当成预期事件来设计而不是当成异常来防范。3.3 超时与重试不能盲目退避要区分错误类型重试是必须的但重试最忌讳的是无脑重试。Agent-Reach 里我把错误类型做了严格区分临时性错误网络抖动、目标服务 503/429。这些值得重试且采用指数退避。永久性错误比如目标渠道拒绝请求400、校验失败、模板格式错误。这类错误重试一百次也没用。对于临时性错误我实现了带指数退避 抖动jitter的重试策略。初值 1 秒倍增上限 30 秒每次在计算出的等待时间上乘一个随机系数避免多个消息同时重试造成“惊群效应”。真正麻烦的是 429 限流。不同渠道的限流语义不一样有的告诉你 Resets In多少秒后重置有的是滑动窗口。为了不频繁撞墙我在 Delivery 层加了一个渠道级的限流预估器动态统计近一段时间的发送成功率按比例自动调低或调高该渠道的并发度。这套机制上线后我能把一个体验最差的客户内部渠道的投递成功率从 92% 拉到了 99.6%代价只是增加了一点重试延迟。值得。3.4 顺序保证只在业务需要时做别为顺序牺牲吞吐一说消息队列就有人问顺序怎么保证我的答案是能不做就不做只在业务明确需要时才做。为什么因为全局顺序和水平扩展天生互斥。你要是非要所有消息严格有序那就只能单分区消费扩展性就没了。在 Agent-Reach 里只有同一个 Context ID 的消息才要求有序比如同一客户的会话消息不同 Context 之间是完全并行处理的。具体做法是按 Context ID 哈希分区同一个 Context 的消息永远进同一个分区、由同一个消费者处理。这样既保证了同一会话内的消息有序又不会牺牲整体吞吐。这个设计我觉得是 Agent-Reach 里性价比最高的一个决策花了一天改造换来了将近一个数量级的吞吐提升而且上下文连续性一点没破坏。4. 核心实现路由配置、渠道包、上下文存储怎么落地的4.1 一个最小可用的消息模型定义先看一段最核心的代码。我定义的标准 Message 模型大概长这样# agent_reach/models.py from datetime import datetime from typing import Any, Optional from enum import Enum class MessageStatus(str, Enum): PENDING pending # 收到待处理 PROCESSING processing # 处理中 SUCCEEDED succeeded # 成功 FAILED failed # 失败 DEAD dead # 转入死信 DUPLICATED duplicated # 被去重跳过 class AgentMessage: def __init__( self, message_id: str, context_id: str, channel: str, direction: str, # in / out payload: dict[str, Any], raw_event: Optional[dict] None, created_at: Optional[datetime] None, ): self.message_id message_id self.context_id context_id self.channel channel self.direction direction self.payload payload self.raw_event raw_event self.created_at created_at or datetime.utcnow() def to_dict(self): return { message_id: self.message_id, context_id: self.context_id, channel: self.channel, direction: self.direction, payload: self.payload, created_at: self.created_at.isoformat(), }这个模型看起来平平无奇但每个字段都是被逼出来的。message_id是幂等的基础context_id是跨渠道上下文聚合的键channel决定了发送链路direction区分入站和出站因为入站要走 Agent 决策出站要走渠道模板。分开之后代码清爽很多不会出现同一个结构里挤着两种语义的情况。4.2 路由配置用一张表描述所有的“什么消息走哪条路”路由逻辑我一开始是写在代码里的几十个 if else 非常爽爽完就后悔了。后来我改用声明式路由规则把“什么消息走哪条路”变成一张可动态加载的配置表。一个典型的 route 长这样# routes/reach_rules.yaml rules: - rule_id: ticket_event_to_agent match: channel: ticket_system event_type: ticket_created action: handler: agent_orchestrator agent_pool: support_agent_pool context_key: ticket_id fallback: timeout_ms: 30000 retry_times: 3 - rule_id: email_reply_to_notify match: channel: email event_type: reply_received action: handler: agent_swift_reply context_key: thread_id每个规则回答四个问题什么条件匹配消息交给谁用什么上下文 ID 关联失败了怎么办这里我想额外说下context_key的设计逻辑它是这套系统的点睛之处。拿工单渠道举例入站消息可能是“ticket_id12345 的新工单”出站消息可能是“回复 ticket_id12345 的邮件”。两者的渠道不同、方向不同、甚至消息 ID 都不同但业务上是同一件事。所以context_key就用来提取业务实体的标识把它作为连结点。Agent 拿到的上下文是围绕这个业务实体的连续历史而不是围绕某个渠道的碎片消息。路由表用 YAML 管理、支持热加载上线后调整策略只需要改配置不用重新发版灵活性和维护成本同时得到了保障。实测操作下来这种模式比代码硬编码至少提升了 5 倍的调整效率。4.3 渠道适配器的统一封装渠道适配器是 Agent-Reach 里最脏最累的活没有之一。我写了几个适配器之后总结出来的经验是要把渠道的“性格”压到最小接口里不要让个性化需求泄露到上层。每个渠道适配器统一实现这几个方法async def send_message(self, msg: AgentMessage) - DeliveryResult: ... async def verify_signature(self, raw_event: dict) - bool: ... async def fetch_inbound(self, cursor: str, limit: int 50) - list: ...至于速率限制了、消息超时了、签名校验失败这些统统在适配器内部消化不往外抛“渠道异常”这种模糊错误。上层只看到两种结果之一DeliveryResult(successTrue)或者DeliveryResult(error某种可分类错误)。举一个具体的例子。某个渠道的老版本 API 对文本长度有 2048 字符的限制。如果让这个问题冒泡到上层每个 Agent 开发者都得知道这个限制那就是设计失败。我的做法是在适配器里做分段投递超过长度就把消息切成多段挨个发送并在每段末尾标注“1/3”“2/3”。上层和用户看到的是完整消息但底层已经处理好了分片。做渠道包的时候还有几个常见的坑一是入站消息的时间字段各国格式五花八门要统一用 ISO8601 解析二是带附件的消息附件要单独存对象存储不能在 payload 里塞 base64三是系统卡在某渠道上不能影响其他渠道的可用性——每个适配器跑在独立的 worker 进程里做到了故障隔离。4.4 上下文存储为什么不能用 Redis 一把梭前面讲到跨渠道上下文是核心需求具体实现上我折腾了好几轮。第一版确实是 Redis。把所有 context 序列化塞到 Redis简单粗暴快速上线。结果很快撞上两个问题第一上下文会持续增长Redis 单键越来越大读写都有性能瓶颈第二Redis 默认没有持久化到能承受业务审计的程度出了问题想回溯历史非常困难。第二版我改成了PostgreSQL Redis 双层结构。PostgreSQL 用来存每一条上下文更新的历史记录只写不删Redis 只存“当前活跃上下文的一个紧凑快照”。Agent 要读取上下文时优先走 Redis如果快照未命中或者 Agent 明确需要更长的历史再从 PostgreSQL 里回放。这个方案有点像 CPU 的多级缓存设计。热点数据在内存冷数据在磁盘。关键是 PostgreSQL 里的记录带了created_at和context_id索引回放历史可以在几十毫秒内完成同时你获得了完整的审计能力——知道 Agent 在每一个时间点看到了什么上下文这在实际排障中太重要了。4.5 与模型调度的联动让 Agent 只做决策不操心触达Agent-Reach 不只是消息管道它还需要跟模型调度联动。具体来说路由层把消息送给 Agent 执行时并不是简单地把文本丢给模型而是构造一个带上下文和工具集的任务。例如一个工单事件进来Agent-Reach 会把过去对该客户的全部触达历史邮件、会话、工单记录压缩成一个精简的 context prompt再把可用的工具查库存 API、发通知 webhook、开退货单作为一个工具列表一并传给 Agent。Agent 根据这些信息做出“要做什么”的决策返回一个结构化的行动计划Agent-Reach 再逐个执行。典型的行动计划返回类似这样的 JSON{ context_id: ticket-12345, intent: issue_refund, steps: [ {action: call_internal_api, params: {endpoint: /refund, amount: 199.00}}, {action: send_email, params: {template: refund_notice, to: userexample.com}}, {action: update_ticket, params: {status: solved}} ] }这种设计的妙处在于模型不决定“怎么发”只决定“发什么”。消息模板的选择、渠道的适配、发送的可靠性、失败的处理都是基础设施的职责。说白了模型管决策Agent-Reach 管执行各司其职。5. 可观测性设计当你的 Agent 遍布多个渠道时如何定位问题5.1 全链路追踪从渠道回调到发送完成一条 Trace 走到底可观测性是我在项目上线后才开始重视、结果被现实狠狠教育了一轮的经验。有一次用户反馈“邮件没收到”我打开数据库状态是 SUCCEEDED。数据没问题但用户就是没收到。到底哪一步错了摸瞎了半天才在日志里发现是某个回调阶段的记录写错了导致状态提前置为成功。那次之后我痛下决心把全链路追踪当成 Agent-Reach 的一等公民来做。每一条消息从入站开始就创建一个唯一的 trace ID在整个生命周期入站 - 路由 - Agent 决策 - 出站投递 - 回调确认里所有日志、事件、耗时都挂在这个 trace ID 下。追踪信息我用 OpenTelemetry 标准来打因为它是中立的、可对接任意后端不会把项目绑死在某个具体平台上。每次跨服务调用trace 上下文随 HTTP header 或消息 header 传播。但即使没有全链路注入单机日志系统把所有 trace ID 打在同一行也能应付大多数排查场景。排查客户问题效率提升至少三倍。以前是问“邮件发出来没有”现在是直接搜索 trace ID 就能看完整生命周期。5.2 状态机的可视化每条消息处于什么阶段一目了然光有 trace 还不够我实现了一个消息生命周期状态机把所有消息的阶段性状态都记录下来。状态机的流转路径是固定的PENDING - PROCESSING - SUCCEEDED └ FAILED - DEAD PROCESSING - DUPLICATED通过这个状态机你可以回答几类关键问题现在系统里有多少消息卡在 PROCESSING 超过 1 分钟有多少 FAILED 且重试超过 3 次死信队列在增长还是下降这是一种完全不同的排查方式——你不再需要通过“搜日志猜原因”而是看状态机就知道系统哪个环节出问题了。5.3 实时监控面板需要关注的指标我的监控面板上有这么几组指标我觉得对任何相似的 Agent 触达系统都有参考价值入站速率和分布各渠道的每秒接收次数。渠道分布异常可能说明回调配置被改动或服务被攻击。Agent 决策时延P50 / P95 / P99从消息入站到模型返回决策的耗时。这基本就是用户体验的底线模型响应慢一切后端的优化都白搭。发送成功率按渠道维度分开统计。一个渠道一旦开始掉点往往意味着频控加重或接口变动。重试率整个系统重试在所有发送尝试里的占比。重试率 5% 就该查下游了持续恶化说明不是正常抖动。上下文命中率Agent 请求上下文时 Redis 快照的命中率。这个指标代表着你缓存设计之间的一致度。命中率长期偏低说明快照失效策略有bug也该去复盘了。这些指标在任意一个开源的监控方案里都能实现关键在于指标的定义对业务有没有区分度。挑太多指标等于没有指标只盯这五个系统哪坏了基本可以快速定位。6. 上线之后踩过的坑真实故障与排查实录6.1 幂等表膨胀导致性能劣化系统刚上线时一切顺利大约三周后我注意到消息处理延迟不断攀升。定位下来后发现是 dedup 表没有做清理策略积累了过多长期未更新的记录导致每次插入时唯一键索引的膨胀拖慢了事务提交。我的解决方案是为 dedup 记录加上 TTL只在消息处理后 24 小时内保留。为什么要 24 小时而不是更短因为渠道的某些重试可能延迟 30 分钟到几小时过短的保留期会放过晚到的重复消息。上线 TTL 清理后表体积稳定在一个健康范围P95 延迟回落。6.2 渠道适配器内存泄漏有一次我发现某个独立 worker 的内存持续上涨周而复始地到阈值后重启。排查结果是渠道适配器里有个静态缓存每次消息处理都往里塞数据但从不清理长时间运行后内存被耗尽。这个问题的教训是适配器虽是独立 worker但依然要遵守“无状态优先”原则任何缓存类数据结构都要仔细定义它的生命周期和清理策略否则在长时运行期间必出故障。6.3 邮件渠道的回调不可靠邮件渠道是最特殊的因为你发出去了之后你没法保证自己能马上收到对方的回执。有些邮件服务商的回调本身就是尽力而为可能延迟几十分钟也可能干脆没有。最终的方案是增加一个定期补偿巡检任务每隔一段时间扫描所有“已发送但未确认”的邮件消息主动查询邮件服务商的投递状态接口来修正消息状态。这本质上是从“事件驱动”降级为“轮询修正”丑但实用。凡是自带回调的渠道我都会保留一份轮询作为兜底宁可多查一次也不要查不到。6.4 重试风暴一发重试全员重试有一次下游系统短暂不可用Agent-Reach 的所有消息几乎同时进入了重试流程。因为初始 1 秒的指数退避是全局同步的几千条消息在同一秒全部开始重试下游刚恢复又被我们自己的流量打挂了。处理方式是我前面提到的抖动jitter也就是让每个人重试等待时间在基础退避值上增加一点随机差异。刚开始这只是计划里的一小条后来变成强约束。配合渠道并发度上限本质上是在帮下游做保护这在外部系统对接中非常关键。7. 经验总结Agent 系统的触达层值得被认真对待做 Agent-Reach 这个项目我最大的感受是把 Agent 的“脑”和“手”分离是让 Agent 真正进入业务环境的必经之路。做 Agent 认知能力的人都关心选什么模型、怎么调 prompt、怎么设计工具调用但对生产环境来说“手”稳不稳才是决定成败的因素。这里我把几个核心的设计原则再强调一遍触达层和决策层解耦。Agent 不应该关心消息是走 SMTP 还是 HTTP它应该只关心“要做什么”。这个边界越清晰系统越容易维护。消息系统该有的纪律一个都不能少。幂等、重试、死信、顺序保证、背压处理这些在传统消息系统里的默认约束对 Agent 触达完全适用一个都逃不掉。上下文是 Agent 的灵魂。不同渠道的消息必须靠业务上下文关联起来渠道之间不能是孤岛。没有这一层你的 Agent 只能叫“多渠道接口聚合器”。可观测性必须从第一天开始设计。等出问题再补你会发现自己已经无法回溯历史状态了。对渠道怀有敬畏之心。每一个你正在对接的渠道背后都可能是一整套你没见过的历史老系统。跟它们打交道永远保守、永远多验证。我在实际使用中还发现这套设计投入产出比相当高。原本以为要花三个月才能稳定的系统两个月出头就把核心链路打磨得比较扎实了后续只是持续的渠道适配和性能优化。如果你正在考虑给自己的 Agent 加一层触达基础设施我的建议是牢牢抓住三个关键词可靠性、连接性、可追踪性。围绕这三个交付标准去做你的 Agent 一定能在真实业务场景里站住脚。
