Agent-Reach：为AI Agent打造可配置的触达层基础设施

项目概述：先说明白 Agent-Reach 到底在解决什么

先说结论：Agent-Reach 这个名字，字面意思是“智能体触达”，但在我实际做的这个项目里，它更像是一套“给 AI Agent 装长手”的基础设施。过去很长一段时间，大家讨论 Agent 都在卷模型推理能力、卷提示词工程，可真正把 Agent 放到生产环境里跑一遍就会发现，卡脖子的根本不是“智商”，而是“够不够得着”——够得着数据库吗？够得着遗留系统吗？够得着没有开放 API 的旧平台吗？够得着业务方随手甩过来的一份 Excel 吗？

我做这个项目最初的契机很简单：公司内部有十几个业务系统，有的有 API，有的只有网页后台，有的数据躺在 Oracle 里，有的在某个同事的共享盘里。团队想做一个能自动处理跨系统流程的 Agent，结果发现光是打通“触达”这一步，就消耗了六成以上的开发资源。于是我把所有 Agent 接入层的通用能力抽出来，单独做成了 Agent-Reach 这套框架，目的只有一个：让 Agent 能以可配置的、安全可控的方式，接到一切它需要的资源，并且让运维和业务看得见、管得住。

这个项目适合谁？适合所有正在做或者准备做 AI Agent 落地的人——不管是企业内部 Copilot、自动化流程机器人，还是垂直行业的智能助手。你不需要一开始就上全套能力，但至少应该理解“触达”这一层需要哪些组件、有哪些坑、怎么设计才不会把自己锁死。下面我会把整个设计思路、核心模块、一套可以直接抄的落地配置，以及我踩过的若干雷，全部摊开讲。

1. 整体架构思路：为什么需要单独的“触达层”

在动手写 Agent-Reach 之前，我其实也犯过一个典型的错误：把工具调用逻辑直接写死在 Agent 的 Prompt 里。当时觉得“不就是一个函数调用吗”，结果业务一多、系统一变，Prompt 变得臃肿不堪，模型开始随机漏掉某些工具，权限也根本没法细分。那段时间我意识到一件事：Agent 和外部世界的交互，本质上和微服务之间的通信一样，也需要一层独立抽象，而不是揉在业务代码里的一锅粥。

1.1 先看 Agent 原生能力的三个边界

模型的上下文窗口是第一个边界。哪怕现在窗口已经很大，也不可能把企业所有的 API 文档、数据字典、操作手册全部塞进去。你只能塞进去一部分“元信息”，让 Agent 知道自己有什么工具可用、什么参数必填。

工具调用的格式是第二个边界。OpenAI 的 function calling、Anthropic 的 tool use、开源模型的 JSON 输出，格式看似差不多，实际上对参数约束、必填项描述、枚举值定义的要求都不一样。如果你直接按某一家平台的格式写死了，后面想换模型供应商，就得把全部工具定义重写一遍。

权限边界是第三个，也是最容易被忽略的。Agent 不是一个独立的系统，它调用企业微信机器人、飞书文档、ERP 接口的时候，必须遵守原系统的权限模型。如果每个业务系统里的身份映射都要单独做，整个项目就会被拖死在权限泥潭里。

Agent-Reach 的设计思路，就是在 Agent 模型和外部资源之间插入一个“触达层”，这一层专门负责四件事：发现可用资源、格式化工具描述、执行鉴权、统一调用协议。说白了，它像是一个中间件，把模型的“我想查一下库存”翻译成对 ERP 系统的真实请求，并且在这个过程中不违反任何系统的权限规则。

1.2 方案选型：为什么不用现成的 MCP 或自研插件协议

2024 年底开始，MCP（Model Context Protocol）这个概念火起来了，很多人会问：既然有 MCP，为什么还要自己做 Agent-Reach？

我的回答是：MCP 是一个很好的通信协议标准，但它并不等于完整的触达层。MCP 解决的是“传输格式”和“服务发现”的问题，它没有解决权限模型映射、审批流、审计日志、故障降级这些生产环境里真正折磨人的东西。我在实际项目里是这么用的：只要外部系统支持 MCP，我就用 MCP 作为接入协议；但不支持的场景，Agent-Reach 用自己的适配器来处理。两者是互补关系，不是替代关系。

这里要特别说明一下选择自研而非直接全上 MCP 的第二个原因：老系统的接入问题。我手头有一个 2008 年上线的客户管理系统，既没有 REST API 也没有 MCP server，只有一套 SOAP 接口，而且部分操作还需要先登录一个 Web 管理后台去获取临时 token。这种场景下，MCP 帮不上任何忙，但 Agent-Reach 可以通过“UiAdapter + ProtocolAdapter”的双层适配器把它接进来，并且对上层 Agent 隐藏掉底层差异。这也是为什么我把这套东西叫做“触达层”而不是“接口网关”——它确实比网关卡得更深，直接深入到 UI 和协议层面的适配。

2. 核心模块拆解：Agent-Reach 的四个关键部件

在介绍具体实现之前，我先给 Agent-Reach 画一张逻辑上的部件图（不涉及源码，只是分工）。框架一共分四层：接入层、路由层、权限层、观测层。每一层解决一类独立问题，这样后续不管是加系统还是换模型，都不会牵一发动全身。

2.1 接入层：把“系统多样性”消化在边缘

接入层负责面对外部系统，它的设计理念是“边缘消化多样性”。外部系统的差异——REST、SOAP、GraphQL、Web 页面、Excel 文件、FTP 目录——只允许存在于接入层内部，绝不允许向上层扩散。

我实现的接入层有三种适配器：

1. 接口适配器：处理 REST/SOAP/GraphQL 这类带正式接口的系统。每个适配器声明自己的请求模板、认证方式、重试策略、限流规则。
2. 页面适配器：处理没有 API 的老系统。本质上是把浏览器操作封装成“虚拟接口”，例如“登录后台、进入报表页、选择日期范围、导出 CSV”。
3. 文件适配器：处理非结构化数据源，比如共享目录里的销售报表、定时生成的 JSON 文件、甚至邮件附件。

接入层还有一个很重要的职责叫“能力声明”。每个适配器向上一层暴露的不是一堆函数列表，而是一份结构化的能力描述：这个系统能做什么、需要什么输入、会返回什么。这份描述会直接影响后面路由层能不能把用户的意图对应到正确的工具上。

2.2 路由层：不让 Agent 自己瞎猜该调谁

路由层解决的问题是：当 Agent 说“我要上个月的销售汇总”，它怎么知道应该去查 BI 系统还是去查 Excel 文件？

我踩过的坑是，早期版本让模型自己从几十个工具里选，效果很差——工具一多，模型选择准确率直线下降。后来我把路由层改成了“两级路由”：先做粗粒度筛选，再做细粒度匹配。

粗粒度筛选基于语义向量：每一次能力声明会被预先向量化，用户的当前请求也做向量化，然后做相似度检索，召回 Top K 个候选能力。这个阶段可以容忍一定噪声，它只负责把范围从几十个缩小到三五个。

细粒度匹配才是让模型做决定：把路由层召回的候选能力描述发给模型，让它基于当前对话上下文最终确定调哪一个。这一步因为候选少，模型判定准确率明显上升。我把这个流程叫做“先检索再推理”，整体上比“一上来就推理选工具”稳得多。

这里有个细节值得展开：粗粒度检索的向量索引，需要定期更新。业务系统改版之后，旧的能力描述如果还在索引里，容易被误召回。我在系统里加了一个“能力生命周期”概念，每次业务方更新接口文档，旧的描述进入灰度期、观察期、最终归档期，归档后的描述不再参与召回。这套生命周期管理虽然简单，但极大地减少了路由错误。

2.3 权限层：权限模型千万不能和业务系统绑定

权限层是 Agent-Reach 里我投入时间最多的部分，因为权限问题是生产落地时最容易被业务方挑战的点。

首先要明确一点：Agent 本身没有“身份”，它必须借用某个真实用户的身份去操作业务系统。所以权限层的核心工作是“身份映射”。一个业务系统的用户 A，在另一个系统里可能是用户 B，在第三个系统里可能只有只读权限。Agent-Reach 把这种映射统一维护成一份关系表，并强制要求“最小权限原则”——每次都只申请当前操作所需的最小权限，而不是把 Agent 当成一个超级管理员账户。

我设计了三级权限控制：

1. 系统级：这个 Agent 能不能访问某个系统。比如财务系统只允许特定几个 Agent 调用。
2. 资源级：在系统内部，允许访问哪些资源。比如只允许读客户列表，不允许改价格。
3. 操作级：一个具体动作是否允许。比如“查询订单”允许，“删除订单”永远拒绝。

操作级的控制我非常推荐做成白名单机制。宁可在配置里多写几行允许规则，也不要依赖黑名单去拦截。因为黑名单永远追不上真实操作的变化，白名单至少天然限制了可操作空间。一个典型的反例是我早期接过一个采购系统，当时只做了资源级限制，没有区分“新增采购单”和“修改采购单”，结果 Agent 在一次测试中把一批错误的单价直接写进了正式单据，虽然有审批流兜底，还是让团队紧张了很久。

2.4 观测层：每次触达都要能回溯

观测层在很多人眼里是“加分项”，但在我这里它是“必选项”。没有观测，Agent 出错的时候你根本不知道是哪一步触达出了问题，更别提定位到是 prompt 的问题还是系统接口的问题。

Agent-Reach 的观测层会记录四条链路信息：

• 触发请求：用户原始的自然语言请求是什么。
• 路由结果：经过粗粒度、细粒度路由后，最终选择了哪个能力。
• 调用详情：适配器发送的真实请求参数、请求头、返回状态码、耗时。
• 人工反馈：这位用户最终是否确认了结果正确，有没有手动修正。

这里面最有价值的是“人工反馈”数据。我一开始也没做这个字段，后来发现，很多 Agent 操作看起来是成功的，但用户其实一直在偷偷手工修改产出物。把这些反馈收集起来，就可以定期生成一份“Agent 触达质量报告”，哪些系统的输出经常被改、哪些操作结果经常被标记为错误，一目了然。基于这份报告去调路由或者修适配器，效率比凭感觉调试高太多。

3. 实操详解：从零搭建 Agent-Reach 的最小可用版本

下面这部分是一套我实际用过的配置方案，可以直接照着落地。为了描述清晰，我把关键部分用伪代码和配置文件来说明，但这些配置已经足够接近真实工程的形态。我会按照“初始化配置—适配器开发—路由配置—权限配置—联调验证”的顺序来讲。

3.1 初始化：定义触达层的基础数据模型

第一步，创建一份全局配置文件，用来定义 Agent 的基础属性、默认权限边界、路由策略和观测开关。下面是一个 YAML 配置模块的示例：

agent: name: procurement-assistant actions: - query_inventory - create_purchase_order - modify_purchase_order default_scope: - read_only: true transport: protocol: mcp endpoint: localhost:9001 security: identity_mapping: - source_system: erp source_user: pmo_service target_system: crm target_user: automation_svc permission_mode: whitelist observability: enabled: true audit_logs: true feedback_collector: true

这里有几个点需要解释。第一，actions列表不是用户会说的话，而是这个 Agent 能力的顶层入口。第二，transport协议我建议先用 MCP，如果业务系统不支持再换自研适配器，因为现阶段 MCP 的客户端和服务端库已经比较成熟。第三，identity_mapping是权限层的心跳配置，务必逐条核实映射关系的真实性，不能想当然地认为两个系统里的账号就是同一个人。

注意：这个 YAML 只是骨架。在实际项目里，配置不要都放在一个文件里，建议拆成 agents、adapters、routing、policies 四个子目录，按环境（dev/staging/prod）分别管理。否则配置一多，一个文件几百行，后续维护会非常痛苦。

3.2 适配器开发：把“查询库存”翻译成系统指令

现在来实现一个最简单的适配器：查本地 ERP 库存。假设 ERP 系统提供 REST API，但查询前需要先获取一个临时 session token。适配器的核心逻辑是：

# adapter_erp_inventory.py class ErpInventoryAdapter: def __init__(self, base_url, username, password): self.base_url = base_url self.session = None def connect(self): # 先执行一次登录握手，拿到临时 token resp = requests.post(f"{self.base_url}/auth", json={ "username": self.username, "password": self.password, }) self.session = resp.json()["session_id"] def call(self, params) -> dict: # step 1: 如果会话过期，先重连 # step 2: 调用库存查询接口 resp = requests.get( f"{self.base_url}/inventory/query", headers={"X-Session-Id": self.session}, params={"sku": params["sku"]}, ) return resp.json()

适配器开发有一个关键教训：不要追求“一个适配器通吃所有系统”。我见过有人写了一个万能适配器，试图通过配置文件映射所有接口，结果每个系统的鉴权方式、参数风格、错误码含义都有微妙差异，最终配置反而比写代码还复杂。正确做法是每个系统一个适配器文件，每个适配器内部再拆成几个小方法，保持直观和可测试。

适配器还需要做输入校验。不要相信模型生成的参数一定合法，比如 “sku” 字段必须符合字母加数字的格式，就在适配器入口做一次正则校验。一次不合法的参数直接触发系统重试，通常比发送给 ERP 接口再等那边的校验错误要快。我亲测，这种方式还能顺便减少外部系统上的无效调用记录，对业务方也更友好。

3.3 路由配置：让 Agent 面对模糊意图不慌

路由层的最小配置，需要给每个能力准备一个“语义描述”。注意这个描述不是让人看的，而是让向量检索找得到。描述里应该包括功能标签、常见同义词、典型使用场景。

routing: candidates: - capability: query_inventory vector_tags: - 库存 - 物料 - 缺货 - stock system: erp - capability: query_sales_report vector_tags: - 销量 - 报表 - 月度销售 - sales system: bi_portal

粗粒度检索用的是 embedding 模型，这一步对模型的选型要求不高，bge-m3 或者 text-embedding-3-small 这样的通用模型都够用。细粒度匹配则可以复用你正在用的主对话模型。

实践中的一个细节：向量召回时，为了提升准确率，我给每个能力还加了一个“同义词表”和一个“禁区词表”。同义词表负责扩展潜在的说法，禁区词表负责在明显不相关的时候把候选排掉。比如 user 问“库存成本是多少”，如果某个候选能力虽然带“库存”标签但其实只管数量不管金额，就会因为“成本”“金额”这类词被重排到底部。这个机制很廉价，但对效果的提升非常明显。

3.4 权限联调：在最小权限和易用之间找平衡

权限配置是联调阶段最容易翻车的地方。我的做法是分三步走：

第一步，先在预发环境把所有权限放开，让测试人员体验 Agent 的完整流程，目的是确认“功能层面一切正常”。

第二步，把权限收紧到白名单模式，观察哪些操作开始报错。这时候要仔细分析报错：是 Agent 表述错误，还是权限配置过于保守？我碰到过一种很尴尬的情况，系统要求用户具有“导出记录”权限，但我只给了“查看记录”，于是 Agent 能看到数据却导不出报表。这类问题表现为功能时好时坏，排查起来特别迷惑。

第三步，等白名单稳定运行几周之后，再根据观测层收集的“实际调用频次”调优权限粒度。那些从来不会用到的权限可以直接移除，而高频操作如果发现误拦截较多，可以放宽为“操作前二次确认”。

我这里强烈建议不要为了省事给 Agent 配置一个“系统管理员”角色。表面上看能解决所有权限问题，实际上是把风险和监控全丢了。一旦出了问题，连最基本的操作责任归属都查不清，更别提业务方还愿不愿意继续用这个 Agent。

4. 实操过程中踩过的坑与问题排查实录

这部分内容的素材来自我过去一年在真实项目里积累的经验，每一个问题都是我亲手处理或者协助团队处理的。列成一个速查表，方便读者快速对照自己的情况。

4.1 调用失败时，先确认问题出在“路由前”还是“路由后”

我最常见到的现象是：用户对 Agent 说了一句话，Agent 回了一句“抱歉，我无法完成此事”。这时大多数人第一反应是怪大模型能力不行，其实多数情况是路由层没有匹配到能力，或者匹配到了错误能力。

排查顺序是这样的：

• 先看观测层日志：路由层到底召回了哪几个候选。
• 再看候选排名：如果正确的候选排在后面，检查向量描述里是不是缺了业务常用词。
• 再看细粒度匹配：如果粗召回正常但模型选了错误工具，可能是候选之间的语义区分度不足。

我举一个真实例子：有一次 Agent 频频把“查客户应收账款”路由到“查客户基本信息”，原因是两者的向量标签都包含“客户”两个字，导致候选描述太像。后来我在能力描述里增加了“排除性语句”，比如“本能力仅返回余额，不含地址、电话等基本信息”，问题立刻缓解。这个经验很值得参考：能力描述不仅要告诉模型“我能做什么”，还要告诉它“我不能做什么”。

提示：在排查路由问题时，不要只盯着准确率指标。重点看“误召回的后果”——有些错误召回虽然概率低，但一旦发生就可能触发不可逆操作。对这种能力，应在路由层加“硬性确认条件”。

4.2 适配器超时与重试：别让 Agent 等到天荒地老

接外部系统时，超时和重试是绕不开的。Agent 的调用链路比普通 API 多了一层模型推理和最外层自然语言生成，所以整体耗时天然偏长——如果适配器还不争气地反复超时重试，用户体感会特别差。

我总结了一组比较可靠的重试参数：

当初学池里设置这些参数时，我还特意加了一个“快速失败”策略：如果某个适配器连续失败次数过多，就把这个系统标记为“降级状态”，后续一段时间内 Agent 直接告诉用户“系统暂不可用，请稍后再试”，而不是反复发起无效调用。虽然看起来少了一些成功机会，但避免了坏调用阻塞整个 Agent 进程。实际运行数据显示，加了熔断之后，下游系统的负载骤降，整体任务完成率反而上升了。

4.3 老系统页面操作不稳定：UI 选择器尽量别用绝对路径

我负责过一个老客户管理系统，没有 API，只能用页面适配器。刚开始开发时，我用的是比较具体的 CSS 选择器路径，比如“#main-body > div#header > form#searchForm > input.input-text”。结果系统一升级，页面结构稍微调整，这套选择器全部失效。

后来我把页面适配器的选择器策略改成了“语义优先”：优先用按钮文本、输入框 placeholder、表单 aria-label 这类更稳定的语义属性来定位元素。比如要点击“导出 Excel”按钮，用button:has-text("导出 Excel")而不是依赖它在页面里的绝对位置。这个改动之后，页面结构升级的冲击被大幅削弱。

还有一个小技巧：页面操作前，适配器先做一次“页面健康检查”，确认关键元素在当前屏幕上可见并且可点击。检查失败就直接报错，不再往下执行，避免元素没找到还要硬点导致的连锁麻烦。

4.4 权限映射搞错导致的典型事故分析

必须专门把权限映射问题单独拿出来讲，因为它是所有坑里最隐蔽的。有一次我把 ERP 里的“service_account”映射到了 CRM 里的“service_account”，名字一样，以为是同一个人。后来发现 CRM 里那个账号权限很有限，Agent 能登录却查询不了任何数据，折腾了很久才定位到映射错误。

这种问题之所以隐蔽，是因为配置全疯了也不会报“账号不存在”，只会在某个特定操作时报权限不足。我的建议是：在初始化阶段，跑一遍“权限自检脚本”，用每个映射后的账号去执行该账号权限范围内的简单只读操作，验证通路是否真的可用。这个脚本我强烈建议所有接 Agent 的团队都做一遍，成本极低但能避免后续大量无效排障。

5. 扩展方向：把 Agent-Reach 变成团队基础设施

如果你已经把一个最小可用的触达层跑通了，下一步要考虑的就是它怎么变成一个真正的团队基础设施。我自己的规划分成了三个阶段。

第一个阶段是“适配器商店化”。当团队里有多个 Agent、多个业务系统的时候，每个连接的适配器都应该可以做成一个独立包，有自己的版本号、维护者和测试集。别的 Agent 想接入同一套系统，直接引用这个适配器包，而不是另写一套。这个做法跟软件工程里“不要重复造轮子”是一个道理，只是在 Agent 时代很多人容易忽略。

第二个阶段是“能力市场”。在适配器之上，接入层暴露的能力描述，应该有一个可检索的目录。业务方可以在目录里查看自己的系统到底开放了哪些能力给哪些 Agent；开发团队也能直观看到哪些能力还没有被任何 Agent 使用，可能是废弃接口，也可能是还没有 Agent 去基于它开发场景。这个目录我用的是一个很简单的静态站点，把所有能力描述渲染成页面，效果意外地好，因为业务方终于有了一个“可读”的 AI 接入地图。

第三个阶段是“组织级权限审计”。当 Agent 开始跨越多个系统完成任务时，单一系统的权限管理已经不够了，需要把“Agent 的整个操作链路”当成一个整体来看待。我做过一次实验，让 Agent 从 ERP 读取订单，到 CRM 创建客户跟进记录，再到财务系统标记应收。这个链路涉及三个系统三个账号，如果每个系统单独审计，很难回答“这次操作到底是谁发起的”。Agent-Reach 的观测层引入了 trace_id 的概念，一次完整任务链路里的所有调用共享同一个 trace_id，这样审计时可以按 trace_id 一次拉出全链路调用记录。这个能力在上生产环境时几乎会被所有安全团队追问，建议你提前做好。

6. 写在最后：一些我踩过坑之后的真实体会

先分享一个小小的经验：这套触达层能不能跑得顺，很大程度上不取决于模型，而取决于你对自己的业务系统有没有足够清晰的认知。很多团队之所以在 Agent 项目上卡住，是把太多精力花在调 Prompt 上，却连“每个系统里的账号到底有什么权限”都没搞清楚。Agent-Reach 这类触达层，本质上就是在逼你把“系统集成清单”这件事做扎实，绕不过去。

另一个体会是，权限和安全设计一定要前置，不要在功能跑通以后再说。我见过太多 Agent 项目在 Demo 阶段很惊艳，一上生产就被安全团队叫停，原因是操作不可审计、权限边界模糊。如果你从第一天起就让触达层带审计日志和最小权限配置，后面的路会顺非常多。

最后给一个可落地的起步建议：如果你现在就想试这个思路，别急着写框架，先把你业务中最高频的三个跨系统操作列出来，然后为每个操作写一个最简单的适配器——哪怕是硬编码的、只能处理一种场景的版本——先把链路打通，再逐步抽象。任何新系统，先求通，再求稳，最后才是通用化。这是我做过多个 Agent 项目之后，最想对后来者说的一句话。