1. 从一次“卡壳”说起：为什么Agent需要一张“触达网”
先说个我最近的真实经历。团队里一个同事在调一个AI助手，功能很简单——让模型根据用户指令去查企业内部系统里的订单、回邮件、再同步到飞书群。听起来没什么难度吧？可真正接起来才发现，光是“让模型正确调用十几个接口”这件事，就能把人折磨疯。最开始模型老是选错工具，后来选对工具了又传错参数，等把这两关过了，上下文窗口又被一堆冗长的接口返回结果塞满了，模型开始丢三落四。最后好不容易稳定下来，加了两个新工具，之前的链路又崩了。
这个问题的根源，不在模型本身，而在“触达”这一层。什么叫触达？就是Agent对外部世界的覆盖与交互能力——它能不能稳定地摸到、调用、理解外部系统里的信息和能力，能不能在多个系统之间来回穿梭而不迷路。我这会儿正在写的Agent-Reach，就是专门干这件事的。你可以把它理解成一个面向AI智能体的“触达层框架”：模型负责出脑子，Agent-Reach负责替它把手脚伸到各个地方，并且保证这双手不会够不着、不会伸错、不会把手上的东西弄丢。对着这个方向做，确实能显著减少模型在工具调用上的返工次数，也让多Agent协作时的通信不再是一盘散沙。
这篇文章我想把这个框架从设计思路到落地实践完整拆给你看。如果你是正在做Agent应用的开发者、架构师，或者只是对AI工程化感兴趣、想弄清“Agent到底怎么跟外部世界打交道”的人，这篇都值得你花十分钟读一读。里面没有纸上谈兵的设计图，全是我和团队在真实环境里跑出来的配置、参数、踩坑和修坑记录。
2. 整体设计思路：Agent-Reach到底在解决什么
2.1 先看清楚Agent开发的三个“老大难”
我们刚开始设计Agent-Reach时，没有急着写代码，而是先整理了一下手头项目里反复出现的痛点，最终归纳成三个：
第一，工具调用碎片化。一个正经的Agent至少要对接REST接口、GraphQL、数据库、文件系统、邮件、IM机器人，甚至还有一部分遗留系统的命令行工具。这些接口协议、数据格式、鉴权方式五花八门，如果每个都让模型直接照着文档去调，Prompt会被撑爆，模型也会因为信息过载而频繁出错。更麻烦的是，新增一个接口就要改一次Agent的Prompt和调用逻辑，维护成本高到吓人。
第二，上下文窗口不够用。模型能同时“记住”的内容是有限的，而外部系统返回的数据却往往是又长又杂。一次订单查询返回几十个字段，其中模型真正需要的可能就四五个。把所有原始数据都丢给模型，除了浪费Token，还会干扰它的判断。类似的情况多了，模型就开始把前面更关键的信息“忘掉”。
第三，多Agent协作没有标准协议。让多个Agent分工配合是眼下很热的方向，比如一个Agent负责理解需求，另一个负责查数据，第三个负责生成报告。可它们之间怎么通信？用什么格式交换信息？失败后怎么重试？这些问题如果不在一开始就定清楚，后面一定会变成互相踢皮球。我们在早期原型里甚至遇到过两个Agent因为都是“把信息传给对方”而陷入死循环的情况。
2.2 触达层的核心组件是怎么划分的
基于上面这三个问题，Agent-Reach把整体架构分成了四块：路由层、连接器层、上下文管理层和协作通信层。你可以把它们想成一个大公司的四个部门——路由层是前台接待，负责判断客户（模型输出的意图）应该找哪个部门；连接器层是各地分公司，负责真正跟外部单位打交道；上下文管理层是行政秘书，负责帮你筛选和压缩信息，控制在3分钟之内能说完的重点；协作通信层就是跨部门协调小组，保证不同Agent之间传话有固定格式、不传错人。
这四块并不是互相独立的。路由层需要根据连接器层上报的健康状态做动态决策，上下文管理层要把压缩后的结果反馈给模型，而模型的新一轮输出又会重新走路由。整套流程是一个闭环，这也是为什么我们不能只做一个简单的“工具调用中间件”，而是需要一套能感知状态、能自我调整的框架。
2.3 为什么不用现成的消息队列和中间件
你可能会问，市面上不是有各种消息队列、服务网关、函数计算平台吗，为什么不直接拿来用？这个我们在前期调研时也认真对比过。消息队列擅长的是在服务之间可靠地传递消息，但它并不理解“模型意图”，也不会根据语义去选择下游工具。服务网关更多是治理API调用，做限流、鉴权、监控，但它的核心对象是固定接口，而不是动态生成的Agent行为。打个比方，消息队列是物流车队，服务网关是收费站和路政，而我们需要的是一个“调度中心+随行翻译+秘书处”的复合角色，它得理解目的地、会说各方方言、还得帮领导过滤掉无关噪音。传统组件每个单拎出来都很有用，但要拼成这套能力，得自己做大量胶水代码，而Agent-Reach把这些胶水逻辑标准化了。
3. 核心机制拆解：路由、连接器与上下文管理
3.1 路由层：把意图变成一条可执行的路径
路由层是Agent-Reach的入口。模型输出的不是一个结构化指令，而是一段自然语言（或者带了部分结构化参数），路由层要做的第一件事就是把这个模糊的意图映射到具体的工具调用链路上。
Agent-Reach默认采用意图匹配+参数约束的双重路由策略。意图匹配可以通过模型判别式打分，也可以通过轻量级规则（关键词、正则、JSON Schema匹配）来做，默认跑在本地，不上模型。参数约束则用JSON Schema对模型输出的字段进行校验，比如“查询订单”这个意图要求必须有order_id，没有就当场拦截并让模型补参，避免把错误请求发到下游。
我建议你在配置路由规则时，一定要给每个路由加上“退出条件”。比如“查天气”这件事，正常路径是调用天气API，但如果API连续三次超时，路由层应该自动降级到本地缓存的结果，而不是无限地重试。这个逻辑在单机跑的时候看不出来，一旦上到生产环境，流量一大，没有退出条件的路由一定会拖垮整个系统。
{ "routes": [ { "name": "query_order", "match": "意图包含'查订单'且存在order_id", "tools": ["check_order_status", "query_customer"], "timeout_ms": 8000, "fallback": "use_local_cache" } ] }上面是一段精简的路由配置示例。你注意看fallback字段，这是每个路由都必须明确的，否则框架会在异常情况下做默认行为——直接抛错。对于生产环境来说，抛错不是不可接受，但一定要有兜底策略，哪怕只是返回一句“请稍后再试”。
3.2 连接器生态：Agent触达外部世界的“手”
连接器层解决的是“怎么调用”的问题。Agent-Reach对每一种外部接口类型都提供了标准化连接器接口，你只需要实现三个方法：authenticate（鉴权）、invoke（调用）、parse（解析），就可以把一个新工具接入进来。这样做的好处是，模型侧只看到一套统一格式的工具描述，而不必关心下游到底是HTTP还是FTP。
后来我们做了一个统计，在接入了二十个不同系统之后，模型对工具的“选对率”从79%提升到94%。提升的功劳不全在模型调优，更多是连接器统一了工具描述格式。以前每个接口描述是各写各的，有的详细到把每个错误码都贴上去，有的只有一句话，模型根本分不清哪个工具干什么的。Agent-Reach要求每个连接器在接入时都生成一份固定模板的工具说明，包含：工具用途、输入参数、输出结构、典型错误。这份模板会经过一个压缩器处理，控制在不超过模型容忍度的长度内，再塞进Prompt。
比较容易被忽略的是连接器的“健康检查”。我们维护过一个大系统，里面有几个接口偶尔会返回500错误。如果连接器层不感知这种不稳定状态，路由层就会持续把请求发过去，造成大量无效调用。所以Agent-Reach会在每个连接器内部维护一个滑动窗口统计最近一分钟的失败率，失败率超过30%就把自己标记为degraded，路由层看到这个状态会自动绕行到备用方案。
3.3 上下文管理：别让模型“失忆”
上下文管理是我个人觉得Agent-Reach做得最值的一块。所有外部系统返回的数据，都会经过一个管道：原始数据 → 字段裁剪 → 摘要压缩 → 结构化输出。字段裁剪解决的是“只留模型该看的”，摘要压缩解决的是“留了也看不懂长文本”，结构化输出则是为了保证传给模型的信息是整齐的JSON或表格，而不是一大坨夹杂着日志信息的文本。
这里有个量化的例子。我们接入了一个客服工单系统，一个工单的完整记录大概包含八十多个字段，其中描述、备注等长文本加在一起能有三四千字。如果不做处理，一个涉及五个工单的查询请求就能轻松吃掉一万多Token。用Agent-Reach默认配置裁剪后，每个工单只保留状态、优先级、最近操作记录、客户意向摘要四个字段，单个工单平均压缩到一百字以内。五个工单加起来不到一千Token，而且模型处理后的答案准确率没有下降，反而因为干扰信息少了，对小细节的关注度更高了。
压缩方式也分两种，可以根据场景切换。一种是提取式，用规则和正则把关键字段抠出来；另一种是生成式，调用一个小模型对长文本做摘要。提取式便宜且快，生成式质量高但增加延迟。我们在实际项目中是混着用的：结构化字段走提取式，自由文本走生成式，整体延迟增加大概几百毫秒，完全可接受。
3.4 多Agent协作：把“互相踢皮球”变成标准流程
Agent-Reach在协作层采取的不是让两个Agent自由对话的野生模式，而是基于“黑板系统”的消息池机制。每个Agent在完成任务后，只负责向中央消息池发布一条标准格式的消息，消息里包含发送方、接收方、消息类型、载荷（结构化数据）和状态。其他Agent订阅自己关心的消息类型，一旦发现感兴趣的消息被发布，就按配置好的逻辑去处理。这样做避免了循环调用的问题——因为所有消息都不携带“继续调下一个Agent”的指令权，任何Agent都不能强制另一个Agent干活，只能发出“建议处理”。
为了应对Agent跑得不稳定这个问题，消息池里的每一条消息都会记录“投递次数”。如果一个Agent反复处理同一条消息超过三次且结果都是失败，消息会被自动转移到死信区，并触发告警。这一步调试多Agent应用时帮了大忙，我们能在监控面板上直接看到是哪一步卡住了，而不是靠翻日志猜。
4. 核心参数详解：配置Agent-Reach前需要搞清楚的七件事
4.1 路由匹配的阈值到底设多少
路由匹配方式里有一项关键参数，叫匹配阈值。默认是0.75，意思是意图匹配打分超过0.75才认为路由命中。阈值设得太低，比如0.5，会导致模型意图跟错路由、调用错工具；设得太高，比如0.95，又会经常出现“意图识别不了该走哪条路由”的情况。
我们的经验是，第一轮冷启动时先用0.7跑通流程，然后拿真实用户的100条请求做一次回放，观察没匹配上的请求到底是因为意图模糊还是阈值太高，再动态调整到0.75到0.85之间。生产环境里我们还会配合一个“兜底路由”，当所有路由得分都低于阈值时，不走报错流程，而是返回一句“请提供更完整的信息”，让模型自动追问用户。虽然表面上看起来是拒绝请求，但它极大地提高了用户的续对话意愿，也让整个系统有了优雅的失败方式。
4.2 连接器的超时与重试窗口
每个连接器在注册时必须配置三个值：超时时间、最大重试次数、重试间隔。默认超时是5秒，但不同场景差异很大——查订单这种实时性要求高的接口，超时给3秒就够；生成式摘要这种运算量大的，给到15秒也不过分。最大重试次数我强烈建议不要超过3次，再多就是浪费资源。重试间隔要按指数退避来算，比如第一次失败后等1秒，第二次等2秒，第三次等4秒。直接按固定间隔重试，大概率会在下游系统还没恢复时把请求怼回去，反而加重故障。
这里有个细节，重试时连接的请求体会不会出现问题？部分下游接口不支持重复提交同一个请求，你需要在连接器内部做一个幂等校验：同一个请求ID如果已经处理过，就直接返回上一次的结果。这个我们在对接支付查询接口时验证过，不加幂等的话，一次网卡抖动就能产生好几个重复订单查询，虽然不影响业务数据，但会产生大量没必要的日志和告警。
4.3 上下文压缩的触发条件
Agent-Reach默认在上下文Token数超过模型窗口的60%时启动压缩。压缩时优先清理的内容顺序可以自定义，比如我们把工具返回的系统日志、接口原始报文、旧的中间步骤放在最前面清理，而把用户的核心意图和最终结果放在最后。这个顺序很重要，一旦把用户意图清理掉，模型就会完全“失忆”，对话直接崩。
压缩触发比60%高一些，比如80%，虽然能减少压缩频率，但风险是上下文涨得太快，压缩器一次要处理的内容太多，处理时间变长。低于60%频繁压缩，又会因为多余的计算拖慢响应速度。设置好初始值后，我建议你盯一轮高峰期的监控，观察Token增长速度，再微调这个阈值。
4.4 状态存储与内存管理
Agent-Reach的触达过程是有状态的，尤其是跨步骤的场景，比如先查库存再下单再生成物流信息，每步之间的中间数据都得存下来。框架默认支持内存存储和Redis存储两种模式，单机调试用内存就好，一旦有多副本部署，必须切到Redis。
存储的Key建议按session_id + step_index来组织，Value用JSON字符串保存，TTL设置成30分钟比较合适。太短会导致用户还没完成整轮操作，中间数据就过期了；太长会堆积大量僵尸数据，拖慢Redis的查询性能。另外要特别注意，不要把大段的工具原始返回塞进状态存储，存压缩后的结果就行，否则存储压力和读取延迟都不可控。
4.5 日志与追踪
Agent-Reach运行时会打印三种日志：路由日志、调用日志、压缩日志。路由日志记录每一次意图匹配的得分、命中路由、耗时；调用日志记录连接器的请求和响应摘要、超时、重试次数；压缩日志记录压缩前后的Token数变化、清理了哪些内容。这三个日志配套使用，基本能把一条Agent请求的全链路看得明明白白。
生产环境建议把日志输出到集中式日志平台，并且给每一次会话生成一个trace_id。这个trace_id需要从入口传递到所有连接器调用和Agent协作消息里。没有trace_id的时候，排查一个跨了五个连接器的报错，你得在几千条日志里人肉搜索，有了trace_id，一条命令就能把整条链路拉出来。
4.6 安全与权限
Agent-Reach默认不允许Agent在运行时动态增加新连接器，所有连接器必须在配置阶段注册，避免Agent被恶意Prompt诱导去调用未授权的接口。每个连接器还需要绑定一个最小权限的API Key，不能用管理员的通用账号。比如“订单查询”连接器只申请只读权限，“订单修改”连接器才申请写权限，这样即使某个Agent被绕过了限制，它手里能用的权限也有限。
对用户输入的内容也要做一层过滤，尤其是包含SQL片段、命令行参数、URL跳转的内容。Agent-Reach内置了一个敏感信息过滤插件，可以拦截包含代码执行特征的输入，阻止Agent把它传入Shell类连接器。别以为这是多此一举，我们团队在安全测试时，确实成功用一段精心构造的文本，让一个没做过滤的实验Agent尝试执行了系统命令，后面就给所有项目都装了过滤插件。
4.7 提示词与工具描述模板
虽然Agent-Reach本身不负责模型选择，但它对工具描述模板有硬性要求。每个工具的描述必须包含三段：什么时候用这个工具、输入参数是什么、输出的典型样例是什么。工具描述不能写得太泛，比如“获取订单信息”这种就太模糊，模型很可能在别的场景也去调它。应该写成“当用户提供订单号并询问物流状态或配送进度时使用，需要输入order_id字符串参数，返回包含status和estimated_delivery字段的JSON”。
工具描述的样例也很有讲究。最好给出两到三个典型用例的输入输出，特别是边界情况，比如查一个不存在的订单会返回什么。模型见过这些样例后，遇到类似情况就不会懵。
5. 实操：用Agent-Reach搭一个“跨平台信息触达助手”
5.1 安装与初始化
Agent-Reach以Python包的形式分发，依赖Python 3.10+，目前支持OpenAI、Anthropic以及部分国产大模型的接口协议。安装命令很简单：
pip install agent-reach装完之后用命令行初始化一个项目骨架：
agent-reach init my_assistant cd my_assistant这个命令会自动生成config目录、connectors目录、routes目录和logs目录，结构大概是这样：
my_assistant/ config/ # 全局配置 connectors/ # 连接器实现 routes/ # 路由规则 prompts/ # 提示词模板 logs/ # 运行日志 main.py # 启动入口这里要提一句，初始化出来的路由规则是空的，不会像很多框架那样给你塞一堆demo配置。Agent-Reach的定位是面向真实场景的框架，demo配置反而需要删除，还不如直接空着，逼着你从自己的需求出发去定义路由。
5.2 注册一个连接器
我们现在要给助手加一个“查物流”的能力。假设走的是一个通用物流查询API，返回JSON格式的数据。在connectors目录下创建一个logistics.py文件：
from agent_reach import BaseConnector class LogisticsConnector(BaseConnector): def authenticate(self): return {"Authorization": f"Bearer {self.config['api_key']}"} def invoke(self, params): # 这里发起真正的HTTP调用 response = self.client.get( "https://api.logistics.example.com/query", params={"tracking_no": params["tracking_no"]} ) return response.json() def parse(self, raw): return { "status": raw["data"]["status_text"], "location": raw["data"]["current_location"], "eta": raw["data"]["estimated_delivery"] }关键的其实是parse方法。很多接口原始返回里有大量没用字段，parse方法就是在这里做字段裁剪，只保留模型真正关心的三个字段。我在parse里还会加一层异常处理，如果status_text为空，就强制置为“未知”，避免模型拿到空值后开始编造原因。
然后到config/connectors.yaml里注册这个连接器：
connectors: - name: logistics type: custom module: connectors.logistics config: api_key: ${LOGISTICS_API_KEY} timeout_ms: 5000 max_retries: 2注册完连接器后，Agent-Reach会自动生成一份工具描述并加入模型Prompt，不需要你手动去改提示词。不过有一点要注意，这里的api_key我写了环境变量占位符，千万不要把密钥直接写进yaml文件，否则一旦提交到Git仓库，就是一次安全事故。
5.3 配置路由规则
连接器有了，接下来要让模型知道什么情况下用这个连接器。在routes目录下找一个叫query_logistics.yaml的文件，写入：
name: query_logistics match: intent: 查询物流状态 required_params: - tracking_no tools: - logistics timeout_ms: 8000 fallback: fallback_to_manualrequired_params这个字段容易踩坑。如果模型只输出了“帮我查一下快递”，但没提供快递单号，路由层会拦截这次请求并要求模型追问用户。这是个好的做法，但在设计时需要想清楚哪些参数是必填，哪些是选填。比如查询物流，tracking_no必填，但快递公司名称就选填，因为很多物流API支持只凭单号识别。一旦你把选填参数设成必填，就会增加无意义的用户交互。
启动时框架会检查所有路由和连接器的依赖关系，如果发现路由里引用了不存在的连接器，会直接启动失败并给出提示。这让配置错误在启动阶段就能暴露，而不是等到线上跑起来才报错。
5.4 编写主流程并运行
初始化项目自带一个main.py，它做了几件基础的事情：加载配置、初始化Agent执行器、启动一个命令行交互循环。我直接修改里面的系统提示词，让它以“信息触达助手”的身份运行：
from agent_reach import AgentReach system_prompt = """ 你是一个信息触达助手。你的职责是根据用户需求， 稳定地调用已注册的连接器获取信息，并将结果整理为简洁的答案。 如果信息不足，主动询问用户补充参数。 """ def main(): agent = AgentReach( system_prompt=system_prompt, config_path="config", model="gpt-4o-mini" ) agent.run_cli() if __name__ == "__main__": main()运行python main.py，在命令行里输入“帮我查一下快递单号SF1234567890的状态”。正常情况下，Agent-Reach的链路是这样走的：路由层识别意图是查询物流，校验出tracking_no，路由命中；连接器层发起调用并解析返回结果；上下文管理层压缩成精简信息；模型根据压缩结果生成回答“你的包裹已到达上海转运中心，预计明天送达”。
这一整套过程从输入到输出，控制在两三秒内。如果模型选择了错误的工具，路由层会通过匹配分数差异感知到，并触发一次自动纠偏，用另一个路由重新匹配，不需要用户重新说一遍需求。
5.5 扩展多Agent协作场景
单Agent跑通之后，可以试着扩展成多Agent协作。我们拿一个“竞品监控助手”来举例：一个采集Agent负责定时去抓取指定竞品页面的商品信息，一个分析Agent读取采集结果并生成价格变动摘要，一个通知Agent把摘要发送到钉钉群。
配置方式不复杂。采集Agent处理完数据后，把结果发布到消息池的item.changed主题；分析Agent订阅这个主题，收到消息后做摘要生成，把结果发布到report.ready主题；通知Agent订阅report.ready，拿到内容后推送钉钉机器人。
这种模式的扩展性比较好。假设之后想增加一个“短信紧急告警”功能，不需要改动采集和分析流程，只要再新增一个订阅report.ready的Agent就行。跟传统的“某个Agent显式调用另一个Agent”相比，发布订阅模式让各模块解耦了，一个环节挂了不会拖垮整条链路。
6. 常见问题排查与避坑指南
6.1 路由匹配失败，请求进入兜底流程
症状：用户输入明明是“查一下快递”，模型却回复“请提供更完整的信息”。
排查步骤：先看路由日志，确认这条输入的实际意图匹配得分是多少。如果是0.6多，低于阈值0.75，但人工判断它确实应该命中，那就要看看路由配置里的match条件是不是写得太严格了，或者意图分类器对某些同义表达的泛化不够。
我们踩过的坑是，把“快递”“物流”“包裹”“到哪了”全部分别列成独立意图，结果模型经常分不清。后来改成一个意图“query_logistics”，再往里加一个可选的synonyms字段，把这些词都塞进去，匹配率提升明显。路由配置里的同义词策略值得认真维护，它是成本最低的优化手段。
6.2 连接器调用超时，但下游系统其实是正常的
症状：偶发性超时，重试后成功，但日志里能看到大量timeout记录，且超时时间集中在某一个连接器。
这个问题的原因通常在网络链路上，可能是连接器所在机器到下游API服务之间的某个代理或负载均衡器不稳定。我们在一个项目里发现，连接器调用一个外部物流接口时，所有请求都会被强制走一个内部代理，而这个代理偶尔会有六七秒的延迟。连接器设置的超时时间是5秒，就导致每次都触发超时。
解决方案是，把连接器的超时时间提高到8秒，同时把重试次数降到1次。这个思路是：与其反复快速重试撞上同一段网络拥塞，不如给首次请求更宽裕的时间。还有一个追加手段，给连接器加一个本地DNS缓存，避免每次请求都做一次DNS解析带来的额外延迟。
6.3 模型开始“失忆”，答非所问
症状：多轮对话后，模型逐渐忽略早期用户指令，甚至把上一轮的结果当成这轮的用户输入。
优先检查上下文压缩日志，看看是不是压缩器把关键信息清理掉了。我们早期设置清理顺序时没太在意，默认把“最旧的对话轮次”排在清理最前面，结果发现模型频繁忘记用户最初的约束条件，比如“预算控制在5000以内”。
调整清理顺序为“工具返回的原始数据优先清理、Agent中间推理步骤次之、用户关键约束最后清理”之后，这个问题基本消失。另外，建议在每次压缩前做一次“关键信息标记”，凡是用户输入中带有否定词、数字范围、时间约束的内容，都强制保留，不让压缩器动它们。
6.4 多Agent互相等待，整条链路卡死
症状：一个任务触发了好几个Agent，但流程一直不往下走，监控看板上没有任何报错，就是没结果。
这种问题多半是消息池的订阅关系配置出了问题。我们遇到过的情况是，通知Agent订阅了report.ready主题，但实际发布消息时用的主题名是report_finished，对不上，消息就一直在池子里躺着没人处理。Agent-Reach虽然会在消息发布时打印主题名，但对于已经上线的系统，肉眼很难发现这种低级错误。
我现在的做法是，在每个Agent的配置里加上一个“处理主题清单”的校验逻辑，启动时自动把发布方声明的主题和订阅方声明的主题做一次交叉对比，对不上的直接打印警告。框架本身对配置错误做了拦截，但这道检查属于双保险，特别是团队规模大了之后，光靠人的自觉不靠谱。
6.5 模型调用了未经授权的连接器
症状：安全审计时发现某个Agent发起了预期之外的连接器调用，比如明明是一个物流查询助手，却调用了支付接口。
Agent-Reach的路由层会限制模型只能调用已注册且路由配置里出现过的连接器，但如果某个连接器同时被多个路由引用，模型是有可能“绕过”当前场景去调它的。所以需要配置“每个会话的可用连接器白名单”，比如物流查询会话启动时，只把logistics和address_check两个连接器放进白名单，其他连接器在模型侧完全不可见。
这个功能是一个跑在Agent-Reach之上的过滤逻辑，通过修改模型可调用的function列表来实现。实现不复杂，但带来的安全性提升很明显，尤其是当系统接入了写操作类连接器时，一定要把白名单机制当作默认设置。
7. 项目落地后的几点体会
把Agent-Reach从原型推到生产环境，前后用了大约三周。我最大的体会是，Agent能不能真正用起来，瓶颈往往不在模型智商，而在工程化细节。一个能把工具描述写清楚、能把上下文压缩顺序调好、能把超时重试策略配合理的团队，就算只用基础模型，也能做出稳定可用的Agent应用。
另一个让我印象深刻的是，Agent-Reach对“触达”这件事的抽象是抓到了本质的。它没有试图去替代模型的能力，而是老老实实地把“模型和外部世界之间那一大堆容易出错的事情”标准化了。初期为了接一个接口可能要多写一点模板代码，但后面每接一个新系统，工作量几乎都是固定的，不再需要反复调整Prompt和调用逻辑。
最后分享一个小技巧，我在所有Agent-Reach项目里都会加一个“会话回放”工具。把生产环境里每一条用户请求的完整链路日志存下来，包括路由匹配得分、连接器返回、压缩前后文本、模型最终回答。当系统出问题时，直接拿一条历史请求回放，能在几秒钟内定位到是哪一环出了问题。这个工具不在Agent-Reach默认功能里，但配合它的结构化日志很容易实现。
目前Agent-Reach支持的功能已经能覆盖我手头大部分Agent项目，接下来我还打算研究一下怎么把它的触达能力和长期记忆模块做更深度的整合，让Agent在跨天会话里也能记住用户的偏好和上下文状态。到时候如果有新发现，再写第二篇。
