Agent-Reach 这个名字是我在做第三个内部智能体项目时定下来的。前面两个都卡在同一个地方模型在对话框里说得头头是道一旦让它去查一条订单、改一个字段、推一条通知就开始出岔子——要么挑错工具要么参数少一半要么把整段原始 JSON 塞回上下文把窗口撑爆。我当时判断问题不在模型本身而在于我们从来给 Agent 铺过一条稳定的触达通道。Agent-Reach 就是这条通道工具注册、鉴权、路由、重试、幂等、结果压缩、链路追踪全部收进一层独立服务让 Agent 只负责想清楚要做什么至于怎么安全、可复现地做到交给 Reach。它适合已经跑通提示词和工具调用、准备把智能体推进生产环境的同学也适合想搞清楚 Agent 工程化落地细节的初学者。下面我把每一步的选型理由、参数计算和踩过的坑都摊开讲。1. Agent-Reach 到底解决什么问题把会聊天变成真触达1.1 三个让我下决心动手的场景第一个是客服工单场景。用户问我上周那单退款到哪一步了模型需要先按手机号查客户再查订单再查退款流水三步全对才能答。上线第一周我拉了一下日志端到端成功率只有 41%其中真正因为模型不会想导致的失败不到三成剩下七成全是触达环节的问题手机号带了空格导致校验失败、订单接口分页参数没传导致只返回了第一页、退款流水接口返回的时间戳单位是秒而模型按毫秒解读算出个 1970 年的日期。这些错误跟智能两个字毫无关系纯粹是工程细节没兜住。第二个是内部运维巡检。我们希望每天早上一句话触发出一次巡检拉取各服务的健康检查、比对昨天的错误日志量、把异常项整理成简报。这里的难点不是分析是权限和副作用。巡检脚本里既有只读的查询也有重启实例扩容副本这类破坏性操作。第一版我把它们平铺成十几个工具全部丢给模型结果出现过一次模型在分析完日志后顺手把测试环境的一个实例重启了——它没做错逻辑是我们没在架构层面区分读和写。第三个是内容发布。这个场景最典型的故障是重复发布模型调用发布接口后网络抖动超时它按失败了就重试的直觉又调了一次于是同一篇内容发了两遍。这类问题用提示词是治不好的必须在链路层做幂等。注意如果你现在的智能体只做检索问答还没碰过写操作那 Reach 这一层可以先简化一旦出现任何会改变目标系统状态的调用就必须先把幂等和权限设计好再考虑接更多工具。1.2 Reach 层的边界什么该它管什么不该我见过不少团队把 Reach 做成一个万能中间件最后变成什么都管、什么都管不好的大泥球。我给自己划的边界很硬Reach 不管意图理解不管多步任务的规划顺序不管最终给用户的话术它只管四件事——能力目录有哪些工具、每个工具什么语义、准入谁能调、能调哪些、执行调用、超时、重试、幂等、整形结果裁剪与格式统一。规划交给编排层话术交给对话层。打个比方Reach 更像是快递体系里的分拣中心加安检口它不决定你买什么东西也不负责最后跟你寒暄但它保证包裹贴对了单、过了检、走对了路线、丢了能查、重复投递能被识别。把这个类比落到代码上就是 Reach 对外只暴露两个接口list_capabilities(ctx)返回当前调用主体可见的工具清单call(name, args, ctx)执行一次触达。编排层拿到清单后自己决定调哪个Reach 不参与决策。这样切的好处非常直接。工具扩容时我只需要在 Reach 里加适配器编排层的提示词一个字都不用改权限策略调整时改的是 Reach 的 scope 配置不用去翻散落在各个 Agent 里的代码想换模型供应商Reach 完全无感。我实测过两次整体换模型的迁移Reach 侧零改动只调了编排层的提示词和温度参数两天就切完了。1.3 一个必须从第一天就盯住的指标触达成功率我给自己定的核心指标叫触达成功率口径是在一批固定的端到端任务里对目标系统产生预期副作用或取回预期数据的比例。注意它跟接口返回 200是两回事——接口 200 但参数写错了、写到了错误的记录上仍然算失败。这个口径逼着我把校验做在链路里而不是只看 HTTP 状态码。配套还有三个辅助指标。首调命中率衡量模型第一次选工具选对的比例用来判断工具描述写得好不好幻觉调用率指模型调用了清单里根本不存在或它无权访问的工具的比例正常应该压到 1% 以下重试后恢复率指第一次失败、经过重试后成功的比例这个数太高说明下游不稳定太低说明重试策略没生效。我一般每周看一次这四个数的趋势比看单次日志有用得多。2. 整体架构设计为什么把触达能力从 Agent 里剥出来2.1 四层结构拆解最终我落地的是四层结构从上到下依次是意图层、编排层、适配层、执行层。意图层负责把用户那句口语化的话翻译成结构化目标比如看看昨天有没有异常会变成{domain: ops, action: inspect, window: 2025-XX-XX}。编排层是真正调模型的地方它拿着 Reach 给的能力清单做多步规划决定调用顺序和参数。适配层是 Reach 的主体每个工具对应一个适配器函数负责参数校验、鉴权注入、协议转换、结果整形。执行层是最底下真正碰外部系统的那部分包括 HTTP 客户端、数据库连接、容器沙箱、浏览器会话。四层的失败影响完全不同意图层错了是答非所问编排层错了是步骤乱序适配层错了是参数或格式问题执行层错了是网络和下游问题。分层之后我能按层看错误分布一次定位就快很多。层级主要职责输入输出典型失败意图层口语转结构化目标用户原话目标对象目标识别错编排层多步规划与工具选择目标 能力清单调用序列工具选错、顺序错适配层校验、鉴权、整形工具名 参数标准化结果参数非法、越权执行层真实触达外部系统规范化请求原始响应超时、限流、下游故障2.2 工具接入协议选型MCP、OpenAPI、自研适配器怎么选这是我被问得最多的问题。我的结论是先看两个维度工具是否有状态、是否要跨团队复用。有状态指的是调用需要维持会话比如长连接的消息通道、需要登录态的浏览器操作这类基本只能走自研适配器因为协议本身承载不了会话语义。无状态的 HTTP 接口如果已经有 OpenAPI 描述文件那直接写个生成器把 OpenAPI 转成工具清单最省事我的经验是转换加人工校对二十个接口大概半天能搞定。跨团队复用的场景我才建议上协议化方案。它的价值在于描述文件就是契约别人写好的工具你可以直接挂载不用读它的源码。但代价是多一层转换和一层进程间通信我实测同一次调用的端到端延迟会增加 15 到 40 毫秒对于需要大批量并发调用的场景要算清楚这笔账。接入方式适合场景优点代价OpenAPI 自动生成已有规范描述的无状态接口快、描述天然完整参数语义仍需人工补自研适配器有状态、强定制、需要会话完全可控、性能最好每个都要写和测协议化挂载跨团队、跨系统复用契约清晰、易共享多一层转换与通信开销2.3 为什么不做一个超级工具库我第一版就是把所有工具平铺给模型一共 47 个。结果误选率高得离谱我拿 80 条评测用例跑出来首调命中率只有 63%。后来我把它拆成两级第一级只暴露 6 个域客户、订单、内容、运维、财务、检索模型先选域第二级在域内再暴露 4 到 8 个具体工具。同样的用例首调命中率提到 89%。背后的原因不难理解。工具清单本质上是一份要模型阅读的上下文候选越多相似描述之间的干扰越强查询订单和查询订单流水这种一字之差的工具放在一起模型很容易蒙。我现在的经验阈值是单次暴露给模型的工具不要超过 12 个超过就做域分层或做关键词预过滤。预过滤的做法是先用一次轻量检索甚至就是关键词匹配加向量召回把候选压到 10 个以内再让模型选这个改动我把它叫召回前置实测能再降一截幻觉调用率。3. 核心模块细节与实操要点3.1 工具注册表能力描述怎么写才不会被模型用错工具描述是整个系统里最容易被低估的部分。我一开始照着接口文档抄把字段说明写得很详尽结果命中率反而下降。后来才明白模型需要的不是这个接口有什么字段而是什么时候该用这个工具。所以我的写法是第一句必须写使用场景第二句才写返回什么字段说明放在参数 schema 里。命名也有讲究。我统一用动词_名词的结构比如query_order、update_ticket_status、publish_article。不要用orderApiV2这种名字模型看不出它能干什么。还有一个硬规则一个工具只做一件事。我曾经把查询客户和更新客户塞进同一个工具用mode参数区分结果模型十次里有两次会把 mode 传错改成两个工具后再没出过这个问题。from dataclasses import dataclass, field from typing import Literal dataclass class ToolSpec: name: str # 动词_名词全局唯一 summary: str # 第一句写何时用第二句写返回什么 params_schema: dict # JSON Schemarequired 必须写全 effect: Literal[read, write, external] timeout_s: int 20 max_retry: int 2 idempotency: Literal[none, key, natural] none scopes: list[str] field(default_factorylist) cost_hint: str low # low / mid / high用于预算控制effect这个字段看着简单价值很大。它是后续所有安全策略的开关read 类可以放心并发和重试write 类必须走幂等账本external 类比如对外发消息、调用第三方计费接口还要额外加一层人工确认或额度限制。没有这个字段你后面所有的策略判断都只能靠硬编码工具名列表维护起来是灾难。3.2 权限与沙箱最小授权怎么落地权限我做了两层。第一层是 scope 绑定调用主体每个调用进来都带一个ctx里面有主体标识和它被授予的 scope 集合适配器执行前先做交集判断没有对应 scope 直接拒绝连下游都不碰。第二层是参数级约束比如某个主体只能查自己名下的订单那适配器里会把主体 ID 强制注入查询条件模型即使传了别人的 ID 也会被覆盖掉。第二层是我认为最关键的一层因为它防的是参数被诱导这种情况。涉及自由代码执行的场景我单独开了沙箱。做法是把执行放进一个一次性容器网络直接断掉根文件系统只读只挂一个工作目录进去。下面是实际用的参数docker run --rm \ --network none \ --read-only \ --tmpfs /tmp:rw,size64m \ --memory 512m --cpus 1 \ --pids-limit 128 \ --security-opt no-new-privileges \ -v /srv/reach/workspace:/work:rw \ reach-sandbox:0.3 \ python /work/entry.py几个参数的计算理由说一下。--memory 512m是按我们最重的数据处理脚本峰值算的实测峰值 380MB 左右留了三成余量--cpus 1是防止某个脚本跑满宿主机宁可慢也不要影响其他服务--pids-limit 128是为了挡住 fork 炸弹这类情况正常的 Python 脚本线程加子进程不会超过 40 个--tmpfs /tmp:rw,size64m是因为根目录只读后很多库会往 /tmp 写临时文件不给它写会直接报错。--network none是最重要的一条需要联网的场景我改成走 Reach 的白名单代理而不是给容器开网。注意沙箱的挂载目录一定要和宿主机的业务目录物理隔离我见过直接把项目根目录挂进去的一次误操作删库的代价太大了。3.3 幂等、重试与超时写操作的三道闸幂等键的生成我固定用一个公式hash(主体ID 工具名 规范化参数 业务时间窗)。业务时间窗是这个设计里最容易被忽略的部分——如果没有它用户第二天用完全相同的参数再发一次会被判成重复直接返回旧结果。我的做法是按业务语义设窗口比如订单类操作按天消息推送类按分钟内容发布类不给窗口同一篇文章就该只发一次。重试策略上我把错误分成三类。瞬时错误连接超时、下游 5xx允许退避重试可判定错误参数校验失败、权限不足不重试直接返回结构化错误未知错误保守处理只重试一次。退避我用的是指数加抖动间隔是min(0.4 * 2^attempt, 4)秒加抖动是为了避免大量请求同时失败后形成重试风暴。超时的预算要提前算清楚不能随手写个 30 秒。假设单次超时设为 T最大重试次数为 R退避总和约为 S那么一次调用最坏情况会占用T*(R1) S秒。举个例子T8、R2、退避为 0.4 加 0.8那么最坏是8*3 1.2 25.2秒。如果上游给我的整体响应预算是 20 秒这个配置就不合理我得把 T 降到 6 或者把 R 降到 1。这个账不算清楚线上就会出现用户等了半分钟还以为是卡死的情况。错误类型典型信号是否重试处理方式瞬时错误连接超时、下游 5xx、限流 429是退避重试指数退避加抖动最多 R 次可判定错误参数校验失败、scope 不足否返回结构化错误不回灌原文未知错误序列化异常、意外异常保守重试 1 次记录完整现场告警3.4 结果压缩与回灌别把上下文撑爆这是我最开始完全没重视、后来花时间最多的一块。第一版我把下游接口的原始 JSON 直接丢回给模型有一次查询返回了 340 条记录单次调用就吃掉了 6 万 token直接把上下文挤爆导致后续步骤全部失忆。后来我定了一套整形规则在适配器出口统一执行。规则有四条。第一字段白名单只保留模型做决策真正需要的字段其余一律丢掉第二列表截断默认最多返回 20 条同时明确告诉模型共 N 条已展示前 20 条让它可以决定要不要翻页第三格式统一所有时间统一转成带时区的 ISO 8601 字符串所有金额统一转成数值加币种的对象绝不把原始时间戳丢出去第四长文本摘要超过 500 字的文本字段先截断成前 200 字加省略提示需要全文时再单独调一个读取工具。整形项处理前处理后效果字段数量平均 32 个保留 6 到 9 个单次结果 token 降约 70%列表长度最多 340 条默认 20 条加总数峰值被压住时间格式秒级时间戳带时区 ISO 8601消除跨时区误算长文本原始全文前 200 字加标记需要时二次拉取还有个细节值得说错误信息不要原样回灌给模型。我踩过一个坑下游返回了一段包含堆栈的错误文本模型看到后非常努力地反复重试同一个调用连着试了五次。正确的做法是把错误转成一个简短的枚举比如UPSTREAM_TIMEOUT再附一句人类可读的解释和一条建议动作模型看到建议稍后重试或改用其他工具就不会死磕了。3.5 可观测性一条 trace 看懂全链路我要求每次触达都必须能还原出一棵完整的调用树从用户那句话开始到编排层的每一次工具选择再到适配器内部的每一步。实现上就是给每次会话生成一个 trace id每个步骤一个 spanspan 上必打这几个字段工具名、effect 类型、参数摘要脱敏后、重试次数、耗时、返回字节数、是否命中幂等。日志脱敏我在适配器层做规则是手机号中间四位打码、身份证只留后四位、令牌类字段一律不落盘。采样策略我设的是全量记录 write 类调用read 类按 10% 采样错误调用 100% 记录。这个比例是按存储成本算的我们日均调用量在两万次左右全量存一个月大概 40GB按 write 占比 15% 计算实际存储能压到 8GB 以内。出问题时我第一件事就是拉某个 trace id 的全链路正常情况下三分钟能定位到是哪一层的问题。4. 动手跑通一个最小闭环4.1 环境准备与目录结构建议从只读工具做起跑通了再加写操作。依赖很简单Python 3.11 加几个库就够HTTP 客户端用 httpx支持异步省线程校验用 jsonschema服务框架用 FastAPI观测用 OpenTelemetry 的 Python SDK。目录我按职责分不要按文件类型分这样扩容时能直接照抄reach/ ├── registry/ # 工具清单 yaml按域分文件 ├── adapters/ # 每个工具一个适配器模块 ├── core/ │ ├── router.py # 路由、重试、幂等 │ ├── ledger.py # 幂等账本 │ └── shaper.py # 结果整形 ├── sandbox/ # 沙箱执行器与镜像 ├── eval/ # 评测集与跑分脚本 └── obs/ # trace 与指标导出4.2 写出第一批工具清单清单用 YAML 维护好处是改描述不用动代码评审时也好读。下面是一个只读工具的真实形态注意anyOf那段它明确告诉模型手机号和客户 ID 至少给一个这种约束写在 schema 里比写在描述里有效得多- name: query_customer summary: 需要按手机号或客户 ID 定位某个客户时使用。返回基础档案与最近三条工单。 effect: read timeout_s: 8 max_retry: 3 scopes: [crm:read] params_schema: type: object properties: phone: type: string description: 11 位手机号与 customer_id 二选一 customer_id: type: string description: 客户唯一 ID与 phone 二选一 anyOf: - required: [phone] - required: [customer_id] additionalProperties: falseadditionalProperties: false这一条我强烈建议加上。模型在不确定的时候很容易自己造一个字段出来比如给查询工具传个limit加上这条约束后校验会直接拦住返回参数 limit 不被接受模型收到明确反馈后下次就改对了。4.3 路由与调用核心代码路由是 Reach 的心脏把校验、鉴权、幂等、超时、重试全串起来。下面这段是我线上简化后的版本去掉了一些业务判断主干逻辑是完整的import asyncio, hashlib, json, time class ReachRouter: def __init__(self, registry, adapters, ledger, tracer): self.registry registry self.adapters adapters self.ledger ledger self.tracer tracer def _idem_key(self, spec, args, ctx): if spec.idempotency none: return None payload json.dumps(args, sort_keysTrue, ensure_asciiFalse) raw f{ctx.subject}|{spec.name}|{payload}|{ctx.biz_window} return hashlib.sha256(raw.encode()).hexdigest()[:32] async def call(self, name, args, ctx): spec self.registry[name] self._check_scope(spec, ctx) # 越权直接抛不碰下游 self._validate(spec, args) # JSON Schema 校验 key self._idem_key(spec, args, ctx) if key: hit self.ledger.get(key) if hit is not None: return {**hit, _replayed: True} deadline time.monotonic() spec.timeout_s last_err None for attempt in range(spec.max_retry 1): budget deadline - time.monotonic() if budget 0: break try: with self.tracer.span(ftool.{name}, attemptattempt) as sp: out await asyncio.wait_for( self.adapters[name](args, ctx), timeoutbudget ) shaped self.shaper.shape(spec, out) sp.set(result.bytes, len(str(shaped))) if key: self.ledger.put(key, shaped, ttl86400) return shaped except (asyncio.TimeoutError, TransientError) as e: last_err e if attempt spec.max_retry: await asyncio.sleep(min(0.4 * 2 ** attempt, 4)) continue raise ToolFailed(name, type(last_err).__name__, retryableTrue)这段代码里有几个地方是踩坑换来的。幂等账本写入放在整形之后保证重放返回的和首次返回完全一致避免第一次返回 20 条、重放返回 10 条这种诡异现象。asyncio.wait_for用的是剩余预算而不是固定超时这样重试不会把总耗时拖爆。异常处理只捕获瞬时错误和超时其他异常会向上抛让编排层看到真实的失败原因而不是被吞掉变成一次神秘的超时。4.4 评测集与指标口径没有评测集的 Reach 就是黑盒。我维护一套 80 到 120 条的固定用例分四类正常用例占五成覆盖每个工具的主路径边界用例占两成比如空结果、只有一条记录、超长文本异常用例占两成模拟超时、限流、下游 500越权用例占一成专门验证 scope 拦截是否生效。每类都断言最终的系统状态或返回内容不看中间过程。跑分脚本我做成可以每周自动跑一次输出一张对比表。这么做的收益很实在有一次我优化了结果整形规则主观感觉应该更省 token 了跑完评测发现首调命中率掉了 4 个百分点——原因是字段裁剪时误删了一个时间字段模型看不到时间就没法判断用哪个工具。要是没有评测集这个问题可能要到线上才暴露。指标计算口径我的目标线实测改善后触达成功率端到端任务达成数 / 总任务数≥ 92%94%首调命中率首次选对工具 / 总调用≥ 88%89%幻觉调用率调不存在或无权限工具 / 总调用≤ 1%0.6%重复副作用率重复写操作 / 写操作总数005. 常见问题与排查实录5.1 故障速查表下面这张表是我攒了两年的排查经验基本覆盖了我遇到过的九成问题。建议按现象那一列去搜比按错误码搜快得多。现象大概率原因排查动作处理方式模型反复调同一个工具错误信息原样回灌看回灌的错误文本转成枚举加建议动作参数少一半schema 里 required 没写全检查 JSON Schema补 required 与 anyOf同一操作执行两次幂等键缺失或没带业务窗查幂等账本命中记录补幂等键写操作强制开启返回时间算错时间戳单位不统一看整形输出统一转带时区 ISO 8601偶发串号、返回别人的数据共享会话或连接池串了主体查 ctx 传递链路主体信息随请求传不放全局首调命中率突然下降新加工具造成描述干扰对比新增工具前后的跑分做域分层或召回前置上下文被撑爆大列表未截断看单次返回字节数列表截断加总数提示5.2 几个反直觉的坑第一个坑是描述越详细越好的误解。我把接口文档整段粘进工具描述后命中率从 81% 掉到 74%。原因很简单描述太长模型在多个长描述之间做选择时注意力被大量无关细节稀释了。现在的做法是描述控制在三句话内细节全部下沉到参数 schema 的 description 字段里需要的时候模型自然会看。第二个坑是重试放大副作用。这个前面提过但值得再强调一次因为它最容易在网络抖动这种看似无害的情况下发生。我现在的硬性规则是只要 effect 不是 read就一定有幂等键账本 TTL 至少覆盖业务窗口做不到就不允许上线。第三个坑是并发下的主体串号。我早期用了一个全局的会话对象存鉴权信息单线程跑测试完全正常一上并发就开始返回别人的数据。原因是有个异步任务在切上下文时共享了那个对象。这类问题在日志里看起来像随机数据错乱极难定位。修复方式很土但有效所有主体相关的信息必须作为参数一路透传禁止使用全局或类级别的可变状态。注意如果你发现某些工具的错误率明显高于其他工具先别急着改代码去看它的描述是不是和另一个工具的措辞太像了。我在这个问题上浪费过整整两天。5.3 参数调优超时、重试、并发怎么定我的调参思路是拿数据说话不凭感觉。具体做法是先把每个工具的 P50、P95、P99 耗时打出来跑了三天收集足够样本然后按 P99 的 1.5 倍设初始超时再按前面那个最坏耗时公式验证是否超出上游的响应预算。比如某个查询工具 P99 是 2.4 秒那超时设 4 秒左右比较合理而不是随手写 30 秒——超时写太长的实际后果是故障时大量请求挂着不释放把连接池占满。重试次数我按 effect 分档read 类可以给到 3 次因为读操作安全且便宜write 类最多 1 次而且必须有幂等键兜底external 类对外发消息、调用计费接口不重试失败直接交给人工兜底队列因为这类操作的错误成本远高于重试带来的收益。并发上限我用信号量控制在适配器层每个下游系统单独限流比如某个老接口只扛得住每秒 20 个请求那就按 15 设上限留 25% 余量应对突发。6. 从能用走向好用几条我自己踩出来的经验先说最重要的一条把只读做透再碰写操作。我在第一个版本里急着加写工具结果一次幂等没有覆盖到的场景导致重复推送被业务方投诉。后来我强制自己遵守一条规则——每加一个写工具必须先跑完 20 条对应的评测用例包括重复调用、参数越权、下游超时三种场景全绿才允许接入。这条规则让我的上线节奏慢了两周但之后半年再没出过重复副作用。第二条经验是永远留一条人工接管通道。Reach 判断不了的情况一定存在比如下游返回了语义模糊的错误或者模型连续三次都没调对。这时候正确的做法不是让模型继续试而是把请求连同完整的 trace id 推进人工队列让人处理完把结果写回。我在工单场景加了这条通道后用户感知到的卡住从每周十几起到基本为零。第三条是给工具和策略都做版本管理。工具描述改了、schema 改了、下游接口升级了这些都会影响命中率。我的做法是给工具清单打版本号每次变更记一条变更日志评测跑分保留历史版本出问题能快速回滚到上一个已知可用的版本。这个习惯在一次下游接口悄悄改了字段名的事故里救了我——回滚到上一版描述后业务立刻恢复我第二天才慢慢改适配器。最后分享一个小技巧。在 Reach 返回给编排层的能力清单里我会给每个工具附一句如果你在什么情况下犹豫就别用这个工具。这句话看起来有点怪但实测能有效降低误用率因为它给了模型一个明确的退出条件。加了这句话之后我们的幻觉调用率从 2.1% 降到了 0.6%改动成本几乎为零。