企业官网建设流程全解析

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 四层结构各自的职责

设计的时候我纠结过是三层还是四层，最后定成四层，因为路由这一步真的不能和执行混在一起。

这么拆的好处是每一层都能单独测试。注册层可以写单元测试验证 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_id+target_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", encoding="utf-8") as f: manifest = yaml.safe_load(f) name = manifest["name"] if name in _REGISTRY: raise ValueError(f"duplicated 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 的逻辑分别写了三遍，每遍都有自己的重试和模板渲染，后来加了第四个通道，直接没人敢动。

我的做法是先定义能力矩阵，再定义接口。

有了这张表，通道选型就有依据了。比如"需要用户明确确认的高危操作"，就必须选支持回执的通道，短信直接排除。

统一接口长这样：

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 回执闭环：别当甩手掌柜

发出去不等于送达，送达不等于已读。我把触达状态做成了一个状态机：

有了这个状态机，我就能做一件很有价值的事：对 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 典型问题速查表

6.2 几个踩过的坑

坑一：工具描述写成了接口文档。我一开始照搬 API 文档的描述，什么"调用该接口将返回订单信息"。模型看了完全无感，因为它不知道什么时候该用。后来改成场景化描述："当用户询问订单当前进度、物流状态时使用本工具"，准确率立刻上了一个台阶。描述要回答的是"什么时候用"，不是"这个接口干什么"。

坑二：把重试当成万灵药。有一段时间我给所有工具都配了三次重试，觉得这样更可靠。结果是一个下游接口因为参数错误返回 400，重试三次全是 400，白白拖长了用户等待，还产生了三倍垃圾日志。现在的原则是：只重试"可能因为时机不对而失败"的错误，不重试"因为内容不对而失败"的错误。

坑三：确认消息发得太频繁。高危操作走确认是对的，但我一开始只要有写操作就发确认，用户一天要确认几十次，后来他直接无视所有确认消息，等于这道闸彻底失效。现在的做法是分级：单次小额操作不确认，只做日志；批量或不可逆才确认。确认的频次要控制在用户愿意认真看的范围内，否则就是形式主义。

坑四：向量索引没做版本管理。我改了工具描述之后忘了重建索引，导致线上按旧描述检索，改动的效果一周后才生效，中间还以为是模型的问题查了很久。现在只要 manifest 有变更，CI 里强制触发索引重建，索引版本号和 manifest 版本号绑定。

6.3 压测时发现的几个隐藏问题

压测阶段暴露的问题往往和功能测试完全不是一类，这里单独说三个。

第一个是连接池耗尽。Agent 的并发特征和传统 Web 请求不一样，一次用户请求可能触发三到五次工具调用，峰值并发是入口请求数的三到五倍。我按入口 QPS 配的连接池，压测一上量就排队。后来按入口 QPS × 平均工具调用数 × 1.5重配，问题消失。

第二个是向量检索的内存抖动。索引全量加载到内存之后，虽然查询快，但每次索引更新都会引起一次明显的 GC 停顿。解决办法是把加载改成双缓冲：新索引加载完之后原子切换，旧索引延迟释放，切换期间内存短暂翻倍，但业务无感。

第三个是模型调用的长尾。精排调用的 P50 是 480ms，P99 却到了 4.2 秒。这个长尾会拖垮整个路由层的延迟预算。我的处理是给精排加独立超时 1.2 秒，超了就走降级路径（只执行置信度最高的只读候选），把长尾挡在用户体验之外。

7. 后续扩展方向与我的一点体会

如果这套东西你已经跑起来了，我觉得有三个方向值得继续做。

一是触达效果的闭环优化。现在我只记录到read，但如果能把用户的后续行为（点没点、回没回、处理没处理）也串进来，就能反推哪些消息是噪音，进而自动调整触达分级。这件事的价值比优化模型本身还大，因为触达层直接决定用户对这个 Agent 的信任度。

二是多 Agent 场景下的工具共享。当系统里有三个以上 Agent 各自持有一部分工具时，注册表可以升级成带权限标签的公共市场，每个 Agent 按自己的身份取子集。这时候auth_scopes就从描述性字段变成真正的运行时隔离依据。

三是路由的离线评测体系。我现在还在用人工标注 200 条的小样本，规模上不去就没法做 A/B。理想状态是积累一批真实用户纠错数据（用户说"不对，我要的是 XX"），自动生成评测集，让路由准确率变成可量化、可迭代的指标。

最后分享一个我自己踩过的认知坑。我一开始总觉得这套系统的核心是"让模型选对工具"，所以把大量精力花在 prompt 调优上。做了半年才反应过来，真正决定系统能不能上线的是执行层和触达层，不是路由层。路由选错顶多是回答不好，执行层没幂等会重复扣款，触达层没回执会有用户永远收不到通知。工具选型的注意力分配，最好和故障的破坏力成正比，而不是和技术的炫酷程度成正比。这个判断我交了不少学费才想明白，希望你能少走点弯路。