Agent-Reach 这个名字第一次看到的时候我脑子里蹦出来的是航拍项目——reach嘛够得着。后来看到它和 Agent 一起出现才反应过来这里的 Reach 说的是触达一个智能体不光要能想明白还得够得着外面的世界够得着工具、够得着数据、最后还得够得着人。这恰好是我过去大半年在内部做智能助手时踩坑最多的一段路所以看到这个词特别有共鸣干脆把自己这套东西整理出来权当一份项目复盘。Agent-Reach 在我的理解里是一层夹在大模型决策和真实世界动作之间的触达能力层。它干的事不复杂就三件把散落在各处的接口注册成 Agent 看得懂的清单把用户一句模糊的话翻译成一次带参数的、可校验的调用把调用的结果可靠地送到人手上。这三件事拆开看都不新鲜难的是串起来之后还得扛住线上流量、权限边界和故障重试。这篇东西适合两类人看。一类是刚上手做 Agent 应用的朋友你可能已经跑通了 demo但一接真实业务就发现工具一多就乱、一失败就哑、一上线就没人管另一类是已经在做智能助手、客服自动化、运维自愈这类系统的同学想找个参考把触达这一层单独抽出来做扎实。全篇不讲概念空话全是我自己写代码、压测、被线上问题追着跑之后留下的东西代码可以直接抄参数可以直接改。1. Agent-Reach 到底在解决什么问题1.1 先把触达这个词拆开看很多人一听触达就想到消息推送其实在 Agent 语境里触达是三层递进的关系缺一层系统就是残的。第一层是能力触达。Agent 要能够得着业务系统比如查订单、改工单状态、触发一次构建。这一层对应的是工具调用Tool Calling本质是把内部 API 包装成模型能理解的结构化函数。第二层是数据触达。光有动作能力不够Agent 还得知道动作该往哪儿打。这里涉及的是知识库检索、结构化查询、实时状态读取。和外层工具不同数据触达通常是只读的但对延迟和准确性要求极高。第三层是人的触达。这是最容易被忽略、上线后最容易出事故的一层。Agent 算出了结论然后呢发到哪里发给谁用户没看到怎么办发错了能不能撤回这些问题在 demo 阶段全被一句print()糊过去了一到生产就全冒出来。Agent-Reach 的定位就是把这三层用一套统一的抽象兜住。它不是模型也不是编排框架它更像一个最后一公里的配送网络——前面的大模型是仓库和分拣中心Agent-Reach 负责把包裹真正送到门口并签收。1.2 光靠 Function Calling 为什么撑不住我最初的做法很朴素把五六个工具的 JSON Schema 直接塞进 system prompt让模型自己选。跑起来非常顺直到工具数量涨到四十多个。第一个崩的是上下文成本。四十个工具每个 schema 平均 180 个 token光工具描述就吃掉七千多 token还没算上对话历史。这不是钱的问题是模型注意力的稀释——工具描述越长选错的概率越高。我当时做过一轮统计工具数从 6 涨到 42 的过程中工具选择准确率从 96% 掉到 71%掉得比我想象的狠。第二个崩的是失败处理。模型给出的参数格式对不对字段漏了怎么办接口超时重试几次重试会不会造成重复下单这些 Function Calling 协议本身一概不管全都得业务自己补。第三个崩的是可观测性。用户投诉Agent 答错了我打开日志只看到模型说我已经帮你处理了具体调了哪个工具、传了什么参数、返回了什么一概没有。这种黑盒状态在内部系统里是绝对过不了审的。所以 Agent-Reach 的第一个设计目标就很明确把工具的定义从 prompt 里挪出来放到一个独立注册表里用检索代替全量注入。第二个目标是把执行语义重试、幂等、超时、熔断从业务代码里收上来做成统一的执行层。第三个目标是把每一次决策和执行都留痕。1.3 谁该用它谁别碰说实话这东西不是所有项目都需要的。如果你的场景只有一个工具比如就是查天气那 Function Calling 一行就完事了上 Agent-Reach 属于杀鸡用牛刀光配置文件都够你写半天。真正划算的场景有这么几个共同特征工具数量超过 15 个且还在增长存在写操作且操作不可逆下单、退款、发消息、改配置有多个触达出口站内信、邮件、IM、工单系统业务方对为什么这么答有审计要求。反过来说如果你的 Agent 是纯问答、只读、单通道、没人管效果那这套东西的复杂度会拖累你。我见过有团队在只读检索场景硬上全套结果一半的代码在维护重试逻辑而那个场景压根不需要重试。2. 整体架构我为什么把它拆成四层2.1 四层结构各自的职责设计的时候我纠结过是三层还是四层最后定成四层因为路由这一步真的不能和执行混在一起。层级核心职责关键产出典型耗时能力注册层汇聚工具定义、校验契约、生成索引Tool Manifest 清单、向量索引离线分钟级路由决策层粗排候选、精排选择、参数抽取结构化调用意图200~800ms执行层参数二次校验、幂等、重试、熔断标准化执行结果取决于下游触达通道层通道选择、内容渲染、发送、回执送达状态100ms~数秒这么拆的好处是每一层都能单独测试。注册层可以写单元测试验证 schema 合法性路由层可以用离线数据集跑准确率执行层可以打桩模拟超时触达层可以做灰度。混在一起写的时候我改一个重试策略要跑全套集成测试拆开之后单测三秒出结果。另一层考虑是故障隔离。路由层挂了至少还能走关键词降级触达层挂了执行结果还能落库等待重发。如果全在一个大函数里任何一处异常都会导致整条链路静默失败。2.2 为什么选声明式注册 运行时校验工具定义有两种写法。一种是写代码注册函数的时候顺便把 schema 拼出来另一种是写声明用 YAML 或 JSON 描述这个工具长什么样代码里只实现执行体。我最终选了后者理由有三条都是吃过亏换来的。第一条是契约先行。声明式写法要求你先把输入输出、错误码、权限等级、超时时间这些东西想清楚再动手。我早期用代码注册的时候经常是函数写完了才回头补描述结果描述和实际行为对不上——比如描述里写返回订单列表实际返回的是分页对象模型拿到之后一脸懵。第二条是可比对、可生成。有了统一的 manifest我可以自动生成对外的接口文档、自动做 schema 的兼容性检查新版本删了字段会报警、自动生成 mock 服务给前端联调。这些在代码注册模式下都得手写。第三条是运行时校验的抓手。声明里写了required字段和类型约束执行前就能拦掉一批明显错误的调用不用等打到下游接口再报 400。这一条在我压测时救过命——模型幻觉出一个不存在的枚举值校验层直接拦下并回传明确错误模型第二次就改对了。2.3 一份 Tool Manifest 该写什么下面是我实际在用的一份模板字段名改过结构是真的。name: order.update_status version: 2.1.0 description: 修改指定订单的状态仅支持正向流转已完成的订单不可修改 category: write risk_level: medium auth_scopes: - order.write input_schema: type: object properties: order_id: type: string pattern: ^OD[0-9]{12}$ description: 订单号OD 开头加 12 位数字 target_status: type: string enum: [paid, shipped, delivered, closed] reason: type: string maxLength: 200 required: [order_id, target_status] output_schema: type: object properties: success: { type: boolean } previous_status: { type: string } trace_id: { type: string } execution: timeout_ms: 3000 max_retries: 2 backoff: exponential idempotent: true idempotent_key: order_idtarget_status rate_limit: qps: 20 burst: 40这里有几个字段值得单独说。risk_level决定了这个工具在路由阶段能不能被自动执行还是必须走人工确认。idempotent_key是幂等的依据它不是一个随机 UUID而是从业务参数里拼出来的——这一点后面 3.3 会详细讲因为这里踩过最大的坑。rate_limit是保护下游的不是保护自己的很多人会忘。description我写得很具体明确说了仅支持正向流转因为模型如果不知道这个约束就会尝试把已完成订单改回待支付然后被下游拒绝白白浪费一轮对话。工具描述的价值不在于介绍功能而在于提前告诉模型边界在哪。3. 核心实现注册、路由、执行3.1 能力注册把散落的接口收进一张清单注册层要解决的核心矛盾是工具的实现分散在各个业务模块里但 Agent 需要一份全局的、统一的视图。我的做法是在每个业务模块里放一个 manifest 文件和一个执行函数用一个装饰器把它们绑起来。# registry/decorator.py from functools import wraps from typing import Callable, Any import inspect import yaml _REGISTRY: dict[str, dict] {} def tool(manifest_path: str): def wrapper(fn: Callable) - Callable: with open(manifest_path, r, encodingutf-8) as f: manifest yaml.safe_load(f) name manifest[name] if name in _REGISTRY: raise ValueError(fduplicated tool name: {name}) manifest[handler] fn manifest[signature] inspect.signature(fn) _REGISTRY[name] manifest wraps(fn) def inner(*args, **kwargs): return fn(*args, **kwargs) return inner return wrapper def all_tools() - dict[str, dict]: return _REGISTRY用起来是这样# modules/order/tools.py from registry.decorator import tool tool(modules/order/manifest/update_status.yaml) def update_status(order_id: str, target_status: str, reason: str ) - dict: prev _repo.get_status(order_id) _repo.set_status(order_id, target_status) return {success: True, previous_status: prev}这里有个我坚持的设计注册阶段就做重名校验直接抛异常。早期我用了后注册覆盖前注册的策略结果两个团队各自实现了一个query_user上线之后行为随机漂移排查了两天才定位到。从那以后重名一律启动即失败。注册完成后我会跑一个离线任务把每个工具的name description category拼成一段文本算 embedding 存进向量库。这份索引就是后面路由粗排的基础。注意这里刻意没有把参数 schema 放进去——粗排只需要判断这个工具大概能不能解决问题参数细节留到精排阶段处理这样索引更轻、召回更准。3.2 路由与参数绑定两段式比一口气硬选更稳路由是我改动最多的一块。试过三种方案最后稳定在两段式。第一版是全量硬选把所有工具塞进 prompt 让模型选。工具少的时候没问题多了就崩前面说过。第二版是纯向量检索拿用户的话去向量库里搜最相似的三个工具直接执行。问题是检索只认语义相似度不认动作方向。帮我看看这个订单和帮我把这个订单关了在向量空间里距离很近但一个是读一个是写搞错了就是生产事故。现在用的是粗排 精排。粗排用向量检索召回 top-8 候选精排把 8 个候选的完整 schema 拼进 prompt让模型输出一个结构化的调用意图。{ tool: order.update_status, confidence: 0.87, arguments: { order_id: OD202405120001, target_status: closed, reason: 用户申请取消 }, need_confirm: true }精排 prompt 里我加了三条硬约束效果比任何调参都明显一是不允许编造工具名只能从候选里选否则返回null二是不确定就置低 confidence低于阈值走澄清追问而不是硬执行三是参数缺失必须留空不许猜。第三条尤其重要模型特别爱猜你不说它就随便填一个看起来合理的值。参数绑定环节我用了 Pydantic 做二次校验把成功字段的要求逐项过一遍。这里有个小技巧校验失败时不要只回传参数错误要把具体哪个字段、期望什么格式、实际收到什么全部回传。模型看到结构化错误之后的自纠成功率比看到一句笼统报错高出一大截我实测大概从 40% 提升到 82%。路由层的延迟预算我卡在 800ms 以内。粗排向量检索 50ms 左右精排模型调用 500~700ms剩下的留给网络抖动。如果超过预算我会降级到只执行高置信度的只读工具写操作一律转人工确认宁可慢一点也不能瞎写。3.3 执行容错重试、幂等、熔断怎么落地执行层的代码是整个项目里最枯燥但最不能省的部分。超时按工具配置来读操作 1.5 秒写操作 3 秒涉及第三方的放 5 秒。超时值不是拍脑袋定的我是拉了线上 P99 之后上浮 50%。低于 P99 会频繁误杀高于 P99 太多又会让失败感知变慢。重试只对幂等且错误类型可重试的做。可重试的错误包括连接超时、429 限流、502/503不可重试的是 400 参数错误和 403 权限错误——这两种重试一百次结果都一样纯属浪费。退避用指数加抖动import random def backoff_delay(attempt: int, base_ms: int 200) - float: raw base_ms * (2 ** attempt) jitter random.uniform(0, raw * 0.3) return (raw jitter) / 1000.0抖动这一项别省。早期我没加结果下游一抖动所有 Agent 会话在同一个时间点集体重试直接把对方接口打挂属于自己把自己 DDoS 了。幂等是我踩坑最深的地方。第一版我用uuid4()生成幂等键看着很标准实际上完全没用——因为每次重试都是新生成的 UUID服务端根本识别不出这是同一次请求。正确做法是从业务参数里推导import hashlib def build_idem_key(tool_name: str, args: dict, window_s: int 300) - str: ts_bucket int(time.time() // window_s) raw f{tool_name}|{args[order_id]}|{args[target_status]}|{ts_bucket} return hashlib.sha256(raw.encode()).hexdigest()[:32]加了时间窗是为了让同一个订单在五分钟内被改成同一个状态只生效一次但五分钟之后如果用户真的又操作了一次还能正常生效。窗口太短起不到去重作用太长会误伤正常重复操作。五分钟这个值是我根据业务操作频率调出来的你可以按自己场景测。熔断按下游系统维度做不按工具维度。因为我们有十几个工具都打同一个订单服务如果按工具熔断这个工具熔断了那个还在打下游照样扛不住。熔断阈值我设的是 20 秒内错误率超过 50% 且样本数大于 10触发后熔断 30 秒然后放 5% 流量试探。4. 触达通道把结果真正送到人手里4.1 通道抽象与统一发送接口触达层最容易写成意大利面。我见过一个项目发站内信的逻辑、发邮件的逻辑、发 IM 的逻辑分别写了三遍每遍都有自己的重试和模板渲染后来加了第四个通道直接没人敢动。我的做法是先定义能力矩阵再定义接口。通道支持富文本支持回执支持撤回单条速率上限典型延迟站内信是是是200/s200ms邮件是部分否50/s2~10sIM 机器人是是是20/s300ms短信否否否100/s1~5s工单评论是否否30/s500ms有了这张表通道选型就有依据了。比如需要用户明确确认的高危操作就必须选支持回执的通道短信直接排除。统一接口长这样from dataclasses import dataclass from typing import Protocol dataclass class ReachMessage: channel: str receiver: str title: str body: str priority: str # p0 / p1 / p2 dedup_key: str callback_url: str | None None class Channel(Protocol): def supports(self, feature: str) - bool: ... def send(self, msg: ReachMessage) - str: ... # 返回触达记录 id def revoke(self, record_id: str) - bool: ...每个通道只实现这个协议上层完全不关心底下是邮件还是 IM。新增通道的成本从一个星期降到半天。4.2 触达策略分级、去重、静默时段通道打通只是第一步真正决定体验的是什么时候发、发几次。分级按业务影响来定。P0 是操作失败、资金异常这类立刻发绕开静默时段P1 是任务完成、审批结果正常发P2 是日报、汇总、提醒类可以延迟到合适的时间批量发。我早期把所有消息都当 P0 发结果用户三天就把机器人免打扰了等于通道全废。去重用dedup_key规则是业务实体 动作 时间窗。同一个告警针对同一台机器十分钟内只发一次。这里有个细节去重要在发送成功之后才落标记不能发送前落。我有次写成发送前落结果一次网关抖动导致整批消息被标记为已发但实际没发出去用户什么都没收到还查不出问题。静默时段是可配置的默认晚十点到早八点不发 P1/P2。P0 消息在静默时段发的时候会自动在标题前加标记让用户一眼知道为什么半夜收到消息。聚合是 P2 的核心。如果一个人在同一小时内收到超过 5 条 P2我就合并成一条摘要发。聚合的实现要注意保持可跳转——摘要里每一条都要带回到详情的链接或指令否则用户看不全还得去翻体验反而更差。4.3 回执闭环别当甩手掌柜发出去不等于送达送达不等于已读。我把触达状态做成了一个状态机状态含义触发后续动作created已创建记录进入发送队列sent已提交到通道等待回执超时 30s 转 faileddelivered通道确认送达更新用户可见状态read用户已读关闭该条跟进任务failed发送失败按通道降级重试最多 2 次revoked已撤回记录撤回原因有了这个状态机我就能做一件很有价值的事对 P0 消息做升级触达。如果一条 P0 消息三分钟没有变成 delivered自动降级到备用通道再发一次。这个逻辑上线之后紧急通知的到达率从 91% 提到了 99.4%。read状态还有第二个用途判断 Agent 的结论到底有没有被人看到。有些场景下Agent 给出的建议如果没人看就等于没做这个指标比发送成功率更能反映真实效果。5. 可观测性与权限上线后最容易被忽略的两块5.1 决策留痕把黑盒撬开一条缝Agent 系统最难排查的问题是它为什么这么答。我见过的最惨案例是客服机器人给用户承诺了一个不存在的折扣翻遍日志只看到最终回复完全不知道是哪一步出的错。所以 Agent-Reach 从第一版就做全链路留痕结构是 trace span。一条 trace 对应一次用户请求包含用户原始输入、粗排召回的候选列表和分数、精排的完整 prompt 和模型原始输出、参数校验结果、每个工具的执行耗时和返回码、触达通道和最终状态。这里有几个实操上的取舍。第一原始 prompt 要不要全存我的做法是存但要脱敏手机号、身份证、邮箱统一替换成占位符。而且设 TTL默认保留 7 天便于排查但不至于无限膨胀。第二采样怎么做全量存成本高采样又容易丢关键样本。我的策略是分层采样所有失败请求 100% 保留所有写操作 100% 保留读操作按 10% 采样。这样既能控制存储又不会丢掉真正有价值的样本。第三怎么用起来光存不看等于没做。我搭了三个看板工具选择准确率人工标注 200 条做基线、路由降级率、触达失败率按通道分布。每周看一次发现异常就去查对应的 trace。上线三个月里光靠看板就揪出过两次工具描述写反了的问题。5.2 权限边界给高危操作加一道闸权限这块我吃过一次不大不小的教训。有个运维场景的 Agent我给它开了重启服务的工具测试环境跑得好好的某天配置同步出问题测试环境的凭据被带到了生产Agent 一口气重启了二十多台机器。从那以后我定了三档权限。只读档查询类工具自动执行不需要确认日志记录即可。写入档有状态变更但可逆的工具自动执行但对单次会话内的调用次数做限制。比如一个会话最多改三次状态超了就强制转人工。这个限制挡住了很多模型陷入循环反复改的情况。高危档不可逆或者影响面大的操作必须走确认。确认的方式分两种通道确认发一条带确认按钮的消息等人点和参数复核把即将执行的完整参数回显给用户用户回确认才执行。涉及批量操作的我强制走第二种因为批量场景下用户往往没意识到自己说的是全部。另外一道闸是参数白名单。有些工具的参数绝对不能由模型自由填比如env、tenant_id、operator_id这类。这些参数一律由系统上下文注入不出现在 input_schema 里。模型看不到也就没法改。这一条比任何 prompt 里的请不要修改都可靠。6. 常见问题与排查实录6.1 典型问题速查表现象最可能的原因排查动作处理方式模型频繁选错工具工具描述相似度过高导出候选分数分布合并同类工具或改写描述强调差异参数总是少字段精排 prompt 没给足示例看模型原始输出在 prompt 加 2~3 个正反例写操作被执行两次幂等键含随机数检查 idem_key 生成逻辑改为从业务参数推导触达成功率忽高忽低未加退避抖动看重试时间分布补抖动按通道限流用户投诉没收到去重标记落得太早对齐发送日志与标记时间改为发送成功后落标响应突然变慢候选工具数过多看精排 prompt token 数粗排 top-k 降到 6~8偶发权限错误系统参数被模型改写比对注入值与请求值参数移出 schema上下文注入6.2 几个踩过的坑坑一工具描述写成了接口文档。我一开始照搬 API 文档的描述什么调用该接口将返回订单信息。模型看了完全无感因为它不知道什么时候该用。后来改成场景化描述当用户询问订单当前进度、物流状态时使用本工具准确率立刻上了一个台阶。描述要回答的是什么时候用不是这个接口干什么。坑二把重试当成万灵药。有一段时间我给所有工具都配了三次重试觉得这样更可靠。结果是一个下游接口因为参数错误返回 400重试三次全是 400白白拖长了用户等待还产生了三倍垃圾日志。现在的原则是只重试可能因为时机不对而失败的错误不重试因为内容不对而失败的错误。坑三确认消息发得太频繁。高危操作走确认是对的但我一开始只要有写操作就发确认用户一天要确认几十次后来他直接无视所有确认消息等于这道闸彻底失效。现在的做法是分级单次小额操作不确认只做日志批量或不可逆才确认。确认的频次要控制在用户愿意认真看的范围内否则就是形式主义。坑四向量索引没做版本管理。我改了工具描述之后忘了重建索引导致线上按旧描述检索改动的效果一周后才生效中间还以为是模型的问题查了很久。现在只要 manifest 有变更CI 里强制触发索引重建索引版本号和 manifest 版本号绑定。6.3 压测时发现的几个隐藏问题压测阶段暴露的问题往往和功能测试完全不是一类这里单独说三个。第一个是连接池耗尽。Agent 的并发特征和传统 Web 请求不一样一次用户请求可能触发三到五次工具调用峰值并发是入口请求数的三到五倍。我按入口 QPS 配的连接池压测一上量就排队。后来按入口 QPS × 平均工具调用数 × 1.5重配问题消失。第二个是向量检索的内存抖动。索引全量加载到内存之后虽然查询快但每次索引更新都会引起一次明显的 GC 停顿。解决办法是把加载改成双缓冲新索引加载完之后原子切换旧索引延迟释放切换期间内存短暂翻倍但业务无感。第三个是模型调用的长尾。精排调用的 P50 是 480msP99 却到了 4.2 秒。这个长尾会拖垮整个路由层的延迟预算。我的处理是给精排加独立超时 1.2 秒超了就走降级路径只执行置信度最高的只读候选把长尾挡在用户体验之外。7. 后续扩展方向与我的一点体会如果这套东西你已经跑起来了我觉得有三个方向值得继续做。一是触达效果的闭环优化。现在我只记录到read但如果能把用户的后续行为点没点、回没回、处理没处理也串进来就能反推哪些消息是噪音进而自动调整触达分级。这件事的价值比优化模型本身还大因为触达层直接决定用户对这个 Agent 的信任度。二是多 Agent 场景下的工具共享。当系统里有三个以上 Agent 各自持有一部分工具时注册表可以升级成带权限标签的公共市场每个 Agent 按自己的身份取子集。这时候auth_scopes就从描述性字段变成真正的运行时隔离依据。三是路由的离线评测体系。我现在还在用人工标注 200 条的小样本规模上不去就没法做 A/B。理想状态是积累一批真实用户纠错数据用户说不对我要的是 XX自动生成评测集让路由准确率变成可量化、可迭代的指标。最后分享一个我自己踩过的认知坑。我一开始总觉得这套系统的核心是让模型选对工具所以把大量精力花在 prompt 调优上。做了半年才反应过来真正决定系统能不能上线的是执行层和触达层不是路由层。路由选错顶多是回答不好执行层没幂等会重复扣款触达层没回执会有用户永远收不到通知。工具选型的注意力分配最好和故障的破坏力成正比而不是和技术的炫酷程度成正比。这个判断我交了不少学费才想明白希望你能少走点弯路。