1. 我为什么需要Agent-Reach智能体的“触达半径”问题1.1 模型再强够不到业务系统也是白搭过去一年我一直在做AI Agent相关的落地项目有一个体会越来越深模型的推理能力进步飞快但真正卡住项目进度的往往不是“它想不想得到”而是“它够不够得着”。你可以把一个Agent当成一个很聪明但没有手脚的人。它能基于训练数据里的知识给出漂亮的回答但当你让它去查一下某个订单在内部系统里的真实状态、让它把一段文本写进企业微信的某个群、让它去翻一遍三个月前沉淀在语雀里的方案文档——它就懵了。因为它没有通道没有触达能力。它只能基于你喂给它的上下文去“猜”而猜出来的东西业务方是不敢用的。这个痛点在我做的几个项目里反复出现。最初我给Agent接的是Function Calling对就是OpenAI那套工具调用。但用下来有几个问题每个函数都要写一遍JSON SchemaAgent一多、工具一多维护成本直线上升函数之间完全没有统一的路由和权限控制谁都能调谁而且Function Calling本质上还是“模型主动去调”一旦模型的工具选择出错整个链路就歪了。后来我也试过用MCPModel Context Protocol去标准化工具接入方向是对的但MCP解决的是“工具怎么被调用”的协议问题它没有解决“Agent该怎么知道自己有哪些东西可以用、哪些可以用、哪些必须拦下来”的问题。MCP是“最后一公里”的传输协议而我需要的是一个更上层的、统一描述和管控“触达动作”的东西。这就是我为什么花了两个周末的晚上自己搭了一套轻量级的“触达层”框架取名Agent-Reach。它解决的核心问题可以概括成一句话让Agent知道自己能触达什么、通过什么方式触达、以及触达到什么边界为止。这篇文章就是把这套东西的完整思路、核心设计、踩坑过程和最终代码形态分享出来给同样被Agent“够不着系统”折磨的团队一个可参考的落地样本。1.2 实际项目里最常遇到的三个触达断层先说我在真实项目里遇到的三个“断层”你会发现它们根本不是模型能力问题而是工程问题。第一个是系统断层。Agent需要读数据库、调内部API、写工单、发消息。这些系统各有各的鉴权方式、参数格式、返回结构。有的老系统甚至没有API只有一套内部HTTP接口文档还缺一半。Agent要触达这类系统本质上是在做一件“系统集成”的活只是执行人从工程师变成了AI。第二个是知识断层。知识不都在模型脑子里大量项目知识和经验散落在Wiki、语雀、Confluence、本地Markdown仓库、PDF文档里。Agent如果只靠上下文窗口里的那点资料回答出来的东西往往是“正确的废话”。它需要能主动去检索而且要检索得准——不是随便拿一个向量库就往上怼而是要能区分“这个知识属于哪个项目域”“这个文档的权限等级是什么”“这个信息是实时更新的还是历史归档的”。第三个是协作断层。我做的项目里从来不只跑一个Agent。有做需求分析的、有写代码的、有做测试用例的、有负责回复客户的。它们如果各自为战每个Agent都从原始材料开始处理效率极低。但如果允许Agent之间互相触达又立刻出现一个新的问题到底谁有权限发起协作调度的结果怎么回传A给B派了个活B做完了怎么告诉A这其实也是一种“触达”只是触达的对象从“系统”变成了“另一个Agent”。1.3 Agent-Reach不是Agent框架而是触达层做Agent框架的团队很多LangChain、LlamaIndex、各类编排引擎都解决“Agent怎么想”的问题。但我的观察是Agent的决策能力已经够用了至少在垂直场景里难的不是让模型做出正确的决策而是让它做出决策之后真的能把它想做的事做出来。所以Agent-Reach的定位很明确它不是大脑不是身体它是连接大脑和身体的那套神经系统和四肢。大脑决定干什么Reach决定怎么触达、触达哪、触达之后带回来什么。在这套设计里我把“触达”定义成一次有明确边界、有清晰返回值、有可观测性的调用动作。它可以是调用一个Python函数可以是请求一个REST API可以是检索一次向量数据库也可以是给另一个Agent发消息。所有这些动作统一用一套描述规范挂在同一个Hub调度中心上由Agent执行循环在需要的时候发起执行结果再回填给模型。整个链路走完模型才真正“摸到了”它想摸的东西。我见过很多团队在Agent项目上投入巨大最后死于“模型的嘴巴和系统的手没有连上”。Agent-Reach就是我从这个坑里爬出来之后自己做的那根“连接管”。2. Reach Spec一套描述“触达”的通用规范2.1 一次触达就是一个“快递面单”刚开始设计的时候我脑子里很乱。函数、API、知识库、Agent消息这些东西形态差异太大了硬把它们塞进同一个框架里很容易变成一个大杂烩。后来我想清楚了一个类比一次触达本质上就是一次快递配送。快递要正常送到面单上必须写清楚收件人是谁、地址在哪、要送什么东西、有什么特殊要求比如生鲜要冷链、谁付的钱、寄件人是谁。我把这个思路搬到Agent-Reach里设计了一套统一的“触达描述”格式叫Reach Spec。每一个可被Agent调用的东西都对应一份Reach Spec就像每一个可送达的目的地都对应一张面单。一份Reach Spec长这样id: reach_kb_order_status type: knowledge name: 查询订单实时状态 description: 根据订单ID查询订单的当前状态待支付/已支付/已发货/已完成/已取消 input_schema: order_id: type: string required: true desc: 14位订单编号形如 20250101000123 env: type: enum values: [prod, test] default: prod desc: 环境标识 auth: scope: order_service.read owner: fulfillment-team timeout_ms: 3000 handler_type: python_function handler: order_repo.fetch_status这段描述告诉Agent几个关键信息这个触达动作能干什么查询订单状态、需要什么参数订单ID、属于什么权限范围、最长等待多久、底层由哪个函数执行。模型看到这份描述就知道“如果要查询订单状态应该用reach_kb_order_status需要提供order_id”。你可能会问为什么不直接把Python函数给它因为函数是给机器看的Reach Spec是给模型看的。模型需要的是语义化、结构化、带说明的自然语言接口描述。字段名称、值域、示例越清晰模型选错工具的概率就越低。实践下来一份好的Reach Spec比把一堆函数签名丢给模型的效果好得多。2.2 三类触达的归类工具、知识、消息我把所有触达动作归成了三大类每一类在Reach Spec里用type字段区分处理的侧重点也不同类型说明典型场景关键关注点tool调用工具/函数/API创建工单、查询库存、发企业微信消息参数校验、幂等性、超时knowledge检索知识库/数据库/文档查订单状态、检索内部Wiki、查价格策略相关性、权限过滤、来源引用reachAgent间协作委托代码评审、请求法务判断、同步任务状态会话上下文传递、去重、死锁防护为什么要做这个区分因为三类触达的“成功标准”不一样。tool类型看重的是执行结果准不准调用后系统状态有没有被正确改变knowledge类型看重的是检索到的内容对不对、有没有权限、来源能不能溯源reach类型看重的是消息有没有被目标Agent接收、响应是否超时。如果不做区分把它们全部当成“调一个函数”你就没法针对性地做超时策略、结果评估和权限管控。2.3 Resolver模型怎么知道该用哪个Endpoint有了Reach Spec下一步就是让模型在决策时能“选中”正确的那个。这里我踩过一个大坑一开始我把所有Reach Spec全部塞进系统提示词里让模型自己挑。结果项目跑了两个月注册了30多个Endpoint的时候prompt直接膨胀到接近1万token延迟暴增一倍模型的选择准确率反而下降了——信息太多它在几十个工具描述里很容易挑花眼。后来我把“让模型选”改成了“先检索再投喂”。在系统里加了一个组件叫Reach Resolver它的职责是根据用户当前的问题和对话上下文提前筛选出一个“候选Endpoint集合”只把这个集合的Reach Spec喂给模型。Resolver的筛选我用了三层策略关键词规则兜底问题里出现“订单”这个词就优先匹配描述里带“订单”的Endpoint池子。embedding语义检索把Reach Spec的description字段用向量表示和当前用户问题做相似度匹配Top K召回。小模型分类器兜底针对模糊场景用一个很轻量的分类模型把问题归到某个业务域再取该域内的Endpoint。实测下来这三层组合的效果最好。规则层保证了准确性语义层保证了覆盖面分类器层处理了那些跨域的复杂问题。最终每次Agent做触达决策时候选Endpoint数量稳定在3到5个模型的选择准确率从不足70%提升到92%以上。2.4 权限边界触达不等于放开我最担心的一件事是模型在触达时的“越权”。LLM有一个特性它倾向于“帮忙”它会把用户的话当成最高指令去执行。如果用户在对话里说“把那个订单删了”模型如果找到了一个疑似“删除订单”的触达端点它很可能会毫不犹豫地去调用哪怕实际业务规则要求“删除订单必须走审批”。所以在Agent-Reach里权限是硬编码在Reach Spec里的模型没有“临时授权”的能力。每次触达会经过一个Reach Gate权限网关它做三件事校验当前会话的scope是否覆盖该Reach Spec要求的auth.scope。对input_schema里声明了enum、pattern、range的字段做白名单校验超出值域直接拒绝不把非法请求发到业务系统。记录完整审计日志谁在什么时间通过哪个Agent发起了哪次触达传了什么参数返回了什么结果。这套权限模型一开始被团队吐槽“太啰嗦”但后来有一次模型在测试环境里生成了一笔异常金额的订单请求被Reach Gate拦下来了团队才真正认可模型是会犯错的而且它犯错的方式非常“自然”你还真不能拿它当正式员工去信任。3. Agent-Reach落地实操从零到跑通一次完整触达3.1 环境准备与最小化部署先说环境。Agent-Reach依赖并不多核心就三件一个放Reach Spec的注册中心我直接用了SQLite加内存表没上etcd、一个执行触达逻辑的Python进程用的FastAPI理由就一个词异步顺手、以及一个和LLM对接的桥接层兼容OpenAI格式的接口都行我实测对自定义Agent框架同样适用。安装过程非常简单python -m venv .venv source .venv/bin/activate pip install agent-reach0.2.0 fastapi uvicorn sqlalchemy uvicorn agent_reach.hub:app --port 8000跑起来之后默认会暴露两个HTTP接口一个是POST /reach/dispatch供Agent执行循环调用另一个是POST /reach/register用来注册新的Reach Spec。我开发调试时习惯本地起这个服务连一个debug模式的LLM这样每次改完Reach Spec能看到完整的触达链路日志。3.2 第一步注册一个“查订单状态”的触达点我们用刚才那个查询订单状态的例子走一遍注册流程。业务侧的查询逻辑可以长这样# order_repo.py from agent_reach import register register( idreach_kb_order_status, typeknowledge, description根据订单ID查询订单的当前状态待支付/已支付/已发货/已完成/已取消, input_schema{ order_id: {type: string, required: True, desc: 14位订单编号}, }, auth{scope: order_service.read, owner: fulfillment-team}, timeout_ms3000, ) def fetch_order_status(order_id: str) - dict: 内部函数从订单数据库取状态 row db.query(select status, updated_at from orders where order_id?, order_id) if row is None: return {found: False, message: 订单不存在} return {found: True, status: row[status], updated_at: row[updated_at]}这里有几个值得注意的设计细节id是全局唯一的格式我统一用reach_tool_、reach_kb_、reach_agent_前缀方便Resolver做类型过滤。description老老实实把这个触达能做什么、不能做什么写清楚。我见过有人写“一个订单函数”模型看了根本不知道什么场景该选它。timeout_ms不是随便填的。知识库查询如果超过3秒说明数据源有问题Agent不如直接告诉用户“暂时查不到”也好过等一个慢查询拖垮整个对话。注册完成后可以通过另一个脚本验证curl -X POST http://localhost:8000/reach/dispatch \ -H Content-Type: application/json \ -d {reach_id: reach_kb_order_status, params: {order_id: 20250101000123}}标准输出会返回{status: ok, data: {found: true, status: 已发货}}。走到这一步你的Agent-Reach服务已经被业务侧打通了。3.3 第二步改造Agent执行循环真正让Agent能动起来核心在于把Reach调用嵌进它的思考-行动循环里。我用到的执行循环结构大概是这样的伪代码def run_agent(user_input): pico_state {messages: [{role: user, content: user_input}]} for step in range(MAX_STEPS): # 1. Resolver 筛选候选 Reach Spec candidates reach_resolver.filter(user_input, pico_state) # 2. 组装上下文把候选 Spec 注入系统提示词 prompt build_prompt_with_reaches(candidates) # 3. 模型决策返回文本回复 或 一个 Reach 调用请求 response llm.chat({**pico_state, messages: [system(prompt), *pico_state[messages]]}) # 4. 如果模型决定触达 if response.tool_calls: for call in response.tool_calls: result reach_gate.dispatch(call.reach_id, call.params) pico_state[messages].append({role: tool, content: result}) continue # 继续下一轮思考 # 5. 如果模型给出最终回复 return response.content这个循环看起来很简单但有一个关键点必须强调每次模型触达之后返回结果必须作为新的“工具消息”追加进上下文让模型看到触达结果再基于结果生成最终回复。我见过不少团队在跑循环时把工具返回结果丢掉了模型等于“空手回复”触达动作做了个寂寞。为了让模型能正确产出触达请求我在它的系统提示词里固定加了一段说明当你需要查询实时信息、调用内部工具、或者向其他Agent发起协作时 请输出一个Reach调用请求格式如下 {reach_call: {reach_id: 候选Id, params: {}}} 只能使用Reach候选列表里给出的reach_id不要编造不存在的id。加一段Few-shot示例模型基本一次就能学会。3.4 第三步让Agent之间通过Reach互相触达单Agent跑通之后我开始做多Agent协作这也是Agent-Reach名字里“Reach”最有意思的部分。我在Hub上注册了三个Agent一个负责需求理解一个负责技术方案设计一个负责代码审查。它们之间通过type: reach类型的Reach点进行消息传递。实际注册一个Agent协作端点和其他类型没有本质区别id: reach_agent_code_review type: reach name: 发起代码审查 description: 将待审查的代码片段或PR链接发送给代码审查Agent返回审查意见列表 input_schema: review_id: type: string required: true code_ref: type: string required: true desc: Git仓库文件路径或PR URL priority: type: enum values: [low, normal, high] default: normal handler_type: python_function handler: agent_coordinator.request_review这个agent_coordinator.request_review内部做的事情是把任务内容塞进审查Agent自己的消息队列然后异步等待它的返回结果。为了不让发起方长时间干等我把这个协作用的是一次2分钟的“带超时轮询”超时返回“审查排队中稍后可查”。这个设计很好地避免了一个Agent长时间阻塞整个执行循环的尴尬。3.5 调试工具箱三条必用的排查命令实际开发里不是写了代码就能一次跑通。我给自己配了三个调试利器建议你也照着配一份查看当前所有已注册的Reach Spec清单GET /reach/list输出JSON格式方便检查有没有重复id、description写得是否模糊。模拟一次触达但跳过模型POST /reach/dispatch?dry_runtrue直接把参数喂给某个Endpoint看业务侧返回是否正常这样可以快速判断问题出在模型决策还是业务系统。看最近N条触达审计日志GET /reach/audit?limit50每一条触达的参数、结果、耗时、发起会话都记录在案排查线上问题全靠它。有一次线上故障排查我花了两个小时定位到是某个旧端点的超时配置写得太短业务侧逻辑处理到一半就被Agent-Reach主动断开了。后来全靠审计日志里的timeout_ms列一眼看到了问题。有审计和没审计Agent项目的线上运维是两种体验。4. 实测中遇到的四个坑现象、原因、解决办法4.1 上下文膨胀Reach Spec清单越塞越多模型选不准最初版本我会把所有已注册的Reach Spec全部投喂给模型让它在候选里做选择。项目跑到第3个月Endpoint数量到了27个每天早上10点高峰期的对话延迟明显比两周前高。我用消融法逐步排查一开始以为是对话历史变长了压缩历史后延迟还是高然后把系统提示词里的Reach Spec清单截断了一半延迟立刻降了40%。再细看日志模型在选择Endpoint时面对20多个候选经常犹豫有时还会输出一个不存在的id。根因是信息过载。模型面对一堆相似描述的工具选择难度指数级上升。解决方案就是我前面提到的“先检索再投喂”三层Resolver上线后每次实际投喂的候选不超过5个模型选择准确率从69%升到了92%prompt体积缩到原来的三分之一。4.2 慢触达拖垮对话Agent等结果等到“失忆”有个触达是调用外部CRM系统的API查询客户历史沟通记录。CRM那边时不时响应超过5秒。问题来了Agent发出触达请求后整个执行循环会同步等待等待期间上下文里的临时信息不会刷新等结果回来时模型已经“忘了”最初用户说的是什么回复质量直线下滑甚至有两次模型在等待期间自己脑补了一个结果完全没看真实返回值。我做的修复是给触达分了三档SLA级别典型场景超时上限等待策略快速本地函数、缓存查询300ms同步等待标准内部接口、知识检索3s同步等待慢速外部CRM、跨Agent协作10s以上异步回调先回进度消息对于慢速触达我改成了“先给用户一个中间反馈例如‘正在为您查询CRM记录预计需要15秒’然后触达完成后把结果作为一条新消息追加进会话让模型再基于结果生成最终回复”。这样用户的体验是“Agent先应答、后出结果”而不是“整个对话卡死十秒”。4.3 模型“发明”了一个不存在的触达点这是个很好笑也很吓人的坑。有一次模型在回答用户“帮我查一下供应商到货记录”时输出了一份Reach调用请求reach_id是reach_kb_supplier_arrival但它根本不存在。我的代码直接用这个id去查注册表返回了空结果模型居然还在那里一本正经地编了一份“供应商到货记录”出来。排查链路是这样的我先在审计日志里输入输出比对发现调用失败但模型没有感知到失败依然生成了答复。进一步看系统提示词发现里面只有一句“使用候选列表中的reach_id不要编造不存在的id”模型在候选列表语义不够清晰时会“合理想象”一个名字。修复做了两件事。第一在Reach Gate里强制加入了“only_dispatch_known1”的配置遇到未知id直接中断流程并明确返回“该触达点不存在请从候选中选择”让模型看到这个错误后自纠。第二给每个候选Reach Spec加上了更加明确的示例和“不能做什么”的负面说明减少模型“自由发挥”的空间。从那以后编造id的情况基本清零。4.4 Agent互相等待协作型死锁做多Agent协作的时候最复杂的一个问题是死锁。有一次线上跑着跑着一个需求分析Agent在等代码审查Agent的审查结果而代码审查Agent又在等需求分析Agent提供补充材料两边互相等待各自执行循环都卡在超时边缘请求越积越多整个Hub的响应都变慢了。我用两条机制解决了这个问题给每个type: reach的协作端点加了max_hops限制即一次协作触达最多允许嵌套转发3次超过直接返回“协作链路过深请拆分子任务”。给协作请求加了一个全局唯一的request_chain_id发现同一链路里出现循环等待时立即熔断返回“检测到循环协作已终止”。这个机制上线后再没出现过Agent互相等到天荒地老的状况。多Agent协作看起来自由其实比单Agent更需要纪律。Agent-Reach的协作端点就是给这种“有纪律的自由”兜底。5. Agent-Reach的操作心得哪些设计值得坚持哪些地方还该优化5.1 这个方案解决了什么问题整套Agent-Reach跑下来大半年我最满意的不是某个Agent的回答准确率提升了多少而是它把“Agent触达”这件事从“每个Agent自己随便发挥”变成了“一套可注册、可筛选、可审计的规范动作”。团队里新来的同学接手Agent项目不再需要翻遍代码找某个功能写在哪而是打开/reach/list看Reach Spec清单就知道系统里有哪些触达能力、每个能力需要什么参数、有什么权限要求。这套思路放大了说其实就是把Agent当成一个有“规范API”的员工在管理而不是当成一个“你说什么它猜什么”的应急工具。模型负责理解和生成Agent-Reach负责把理解和生成落到真实世界的动作上。两者各管一段出了问题也好定位。5.2 目前妥协的地方与值得尝试的优化说得务实一点Agent-Reach现在还有几个不完美的地方。一是Resolver的语义检索依赖embedding模型的质量遇到专业术语很多的场景召回结果偶尔会跑偏。目前我是靠规则层兜底纠正的但如果团队有预算用一个针对垂直领域微调的embedding模型效果会更好。二是触达结果没有做“语义级缓存”。同一个用户隔了一天问同样的订单状态Reach还是会打一次数据库。如果做一个按“参数时间窗口”的缓存层很多查询类触达的响应速度还能再上一个台阶。三是审计日志目前只记录到了“参数和结果”级别没有记录“这次触达前后模型上下文的差异”也就是说我看不到“模型因为这次触达回复质量到底变好了多少”。下一篇技术分享我想做的方向就是给每条触达算一个“上下文增益”指标用来自动评估每个Endpoint的真实价值把那些“模型经常选错、触达后回复质量没有提升”的冗余端点清理掉。5.3 给准备做同类体系的团队三个建议如果你们团队也在搭自己的Agent触达层无论叫不叫Agent-Reach有三点我强烈建议从第一天就坚持从第一个触达点开始就带权限和审计别想着后补。模型一旦习惯了“什么事都能直接调”再收权限会非常痛苦。Reach Spec的description请认真写写清楚“能做什么、不能做什么、参数怎么填”在这里花十分钟能省下后面几周的调参时间。一切触达的请求和返回值都走结构化JSON不要图省事直接用自然语言文本回传。结构化数据模型能直接消化自然语言回传还要额外做一层“理解”白白增加延迟和出错概率。我自己的感受是Agent项目到了中后期拼的不是谁的模型更强而是谁的Agent更能“够得着”。你给它触达能力之前它只是一个聪明的文本生成器你给它一套收放有度的触达层之后它才真正像一个能干活、能担责、能被管理的数字员工。Agent-Reach这个名字起的其实就是这个意思。
Agent-Reach：智能体触达层框架的设计与落地
1. 我为什么需要Agent-Reach智能体的“触达半径”问题1.1 模型再强够不到业务系统也是白搭过去一年我一直在做AI Agent相关的落地项目有一个体会越来越深模型的推理能力进步飞快但真正卡住项目进度的往往不是“它想不想得到”而是“它够不够得着”。你可以把一个Agent当成一个很聪明但没有手脚的人。它能基于训练数据里的知识给出漂亮的回答但当你让它去查一下某个订单在内部系统里的真实状态、让它把一段文本写进企业微信的某个群、让它去翻一遍三个月前沉淀在语雀里的方案文档——它就懵了。因为它没有通道没有触达能力。它只能基于你喂给它的上下文去“猜”而猜出来的东西业务方是不敢用的。这个痛点在我做的几个项目里反复出现。最初我给Agent接的是Function Calling对就是OpenAI那套工具调用。但用下来有几个问题每个函数都要写一遍JSON SchemaAgent一多、工具一多维护成本直线上升函数之间完全没有统一的路由和权限控制谁都能调谁而且Function Calling本质上还是“模型主动去调”一旦模型的工具选择出错整个链路就歪了。后来我也试过用MCPModel Context Protocol去标准化工具接入方向是对的但MCP解决的是“工具怎么被调用”的协议问题它没有解决“Agent该怎么知道自己有哪些东西可以用、哪些可以用、哪些必须拦下来”的问题。MCP是“最后一公里”的传输协议而我需要的是一个更上层的、统一描述和管控“触达动作”的东西。这就是我为什么花了两个周末的晚上自己搭了一套轻量级的“触达层”框架取名Agent-Reach。它解决的核心问题可以概括成一句话让Agent知道自己能触达什么、通过什么方式触达、以及触达到什么边界为止。这篇文章就是把这套东西的完整思路、核心设计、踩坑过程和最终代码形态分享出来给同样被Agent“够不着系统”折磨的团队一个可参考的落地样本。1.2 实际项目里最常遇到的三个触达断层先说我在真实项目里遇到的三个“断层”你会发现它们根本不是模型能力问题而是工程问题。第一个是系统断层。Agent需要读数据库、调内部API、写工单、发消息。这些系统各有各的鉴权方式、参数格式、返回结构。有的老系统甚至没有API只有一套内部HTTP接口文档还缺一半。Agent要触达这类系统本质上是在做一件“系统集成”的活只是执行人从工程师变成了AI。第二个是知识断层。知识不都在模型脑子里大量项目知识和经验散落在Wiki、语雀、Confluence、本地Markdown仓库、PDF文档里。Agent如果只靠上下文窗口里的那点资料回答出来的东西往往是“正确的废话”。它需要能主动去检索而且要检索得准——不是随便拿一个向量库就往上怼而是要能区分“这个知识属于哪个项目域”“这个文档的权限等级是什么”“这个信息是实时更新的还是历史归档的”。第三个是协作断层。我做的项目里从来不只跑一个Agent。有做需求分析的、有写代码的、有做测试用例的、有负责回复客户的。它们如果各自为战每个Agent都从原始材料开始处理效率极低。但如果允许Agent之间互相触达又立刻出现一个新的问题到底谁有权限发起协作调度的结果怎么回传A给B派了个活B做完了怎么告诉A这其实也是一种“触达”只是触达的对象从“系统”变成了“另一个Agent”。1.3 Agent-Reach不是Agent框架而是触达层做Agent框架的团队很多LangChain、LlamaIndex、各类编排引擎都解决“Agent怎么想”的问题。但我的观察是Agent的决策能力已经够用了至少在垂直场景里难的不是让模型做出正确的决策而是让它做出决策之后真的能把它想做的事做出来。所以Agent-Reach的定位很明确它不是大脑不是身体它是连接大脑和身体的那套神经系统和四肢。大脑决定干什么Reach决定怎么触达、触达哪、触达之后带回来什么。在这套设计里我把“触达”定义成一次有明确边界、有清晰返回值、有可观测性的调用动作。它可以是调用一个Python函数可以是请求一个REST API可以是检索一次向量数据库也可以是给另一个Agent发消息。所有这些动作统一用一套描述规范挂在同一个Hub调度中心上由Agent执行循环在需要的时候发起执行结果再回填给模型。整个链路走完模型才真正“摸到了”它想摸的东西。我见过很多团队在Agent项目上投入巨大最后死于“模型的嘴巴和系统的手没有连上”。Agent-Reach就是我从这个坑里爬出来之后自己做的那根“连接管”。2. Reach Spec一套描述“触达”的通用规范2.1 一次触达就是一个“快递面单”刚开始设计的时候我脑子里很乱。函数、API、知识库、Agent消息这些东西形态差异太大了硬把它们塞进同一个框架里很容易变成一个大杂烩。后来我想清楚了一个类比一次触达本质上就是一次快递配送。快递要正常送到面单上必须写清楚收件人是谁、地址在哪、要送什么东西、有什么特殊要求比如生鲜要冷链、谁付的钱、寄件人是谁。我把这个思路搬到Agent-Reach里设计了一套统一的“触达描述”格式叫Reach Spec。每一个可被Agent调用的东西都对应一份Reach Spec就像每一个可送达的目的地都对应一张面单。一份Reach Spec长这样id: reach_kb_order_status type: knowledge name: 查询订单实时状态 description: 根据订单ID查询订单的当前状态待支付/已支付/已发货/已完成/已取消 input_schema: order_id: type: string required: true desc: 14位订单编号形如 20250101000123 env: type: enum values: [prod, test] default: prod desc: 环境标识 auth: scope: order_service.read owner: fulfillment-team timeout_ms: 3000 handler_type: python_function handler: order_repo.fetch_status这段描述告诉Agent几个关键信息这个触达动作能干什么查询订单状态、需要什么参数订单ID、属于什么权限范围、最长等待多久、底层由哪个函数执行。模型看到这份描述就知道“如果要查询订单状态应该用reach_kb_order_status需要提供order_id”。你可能会问为什么不直接把Python函数给它因为函数是给机器看的Reach Spec是给模型看的。模型需要的是语义化、结构化、带说明的自然语言接口描述。字段名称、值域、示例越清晰模型选错工具的概率就越低。实践下来一份好的Reach Spec比把一堆函数签名丢给模型的效果好得多。2.2 三类触达的归类工具、知识、消息我把所有触达动作归成了三大类每一类在Reach Spec里用type字段区分处理的侧重点也不同类型说明典型场景关键关注点tool调用工具/函数/API创建工单、查询库存、发企业微信消息参数校验、幂等性、超时knowledge检索知识库/数据库/文档查订单状态、检索内部Wiki、查价格策略相关性、权限过滤、来源引用reachAgent间协作委托代码评审、请求法务判断、同步任务状态会话上下文传递、去重、死锁防护为什么要做这个区分因为三类触达的“成功标准”不一样。tool类型看重的是执行结果准不准调用后系统状态有没有被正确改变knowledge类型看重的是检索到的内容对不对、有没有权限、来源能不能溯源reach类型看重的是消息有没有被目标Agent接收、响应是否超时。如果不做区分把它们全部当成“调一个函数”你就没法针对性地做超时策略、结果评估和权限管控。2.3 Resolver模型怎么知道该用哪个Endpoint有了Reach Spec下一步就是让模型在决策时能“选中”正确的那个。这里我踩过一个大坑一开始我把所有Reach Spec全部塞进系统提示词里让模型自己挑。结果项目跑了两个月注册了30多个Endpoint的时候prompt直接膨胀到接近1万token延迟暴增一倍模型的选择准确率反而下降了——信息太多它在几十个工具描述里很容易挑花眼。后来我把“让模型选”改成了“先检索再投喂”。在系统里加了一个组件叫Reach Resolver它的职责是根据用户当前的问题和对话上下文提前筛选出一个“候选Endpoint集合”只把这个集合的Reach Spec喂给模型。Resolver的筛选我用了三层策略关键词规则兜底问题里出现“订单”这个词就优先匹配描述里带“订单”的Endpoint池子。embedding语义检索把Reach Spec的description字段用向量表示和当前用户问题做相似度匹配Top K召回。小模型分类器兜底针对模糊场景用一个很轻量的分类模型把问题归到某个业务域再取该域内的Endpoint。实测下来这三层组合的效果最好。规则层保证了准确性语义层保证了覆盖面分类器层处理了那些跨域的复杂问题。最终每次Agent做触达决策时候选Endpoint数量稳定在3到5个模型的选择准确率从不足70%提升到92%以上。2.4 权限边界触达不等于放开我最担心的一件事是模型在触达时的“越权”。LLM有一个特性它倾向于“帮忙”它会把用户的话当成最高指令去执行。如果用户在对话里说“把那个订单删了”模型如果找到了一个疑似“删除订单”的触达端点它很可能会毫不犹豫地去调用哪怕实际业务规则要求“删除订单必须走审批”。所以在Agent-Reach里权限是硬编码在Reach Spec里的模型没有“临时授权”的能力。每次触达会经过一个Reach Gate权限网关它做三件事校验当前会话的scope是否覆盖该Reach Spec要求的auth.scope。对input_schema里声明了enum、pattern、range的字段做白名单校验超出值域直接拒绝不把非法请求发到业务系统。记录完整审计日志谁在什么时间通过哪个Agent发起了哪次触达传了什么参数返回了什么结果。这套权限模型一开始被团队吐槽“太啰嗦”但后来有一次模型在测试环境里生成了一笔异常金额的订单请求被Reach Gate拦下来了团队才真正认可模型是会犯错的而且它犯错的方式非常“自然”你还真不能拿它当正式员工去信任。3. Agent-Reach落地实操从零到跑通一次完整触达3.1 环境准备与最小化部署先说环境。Agent-Reach依赖并不多核心就三件一个放Reach Spec的注册中心我直接用了SQLite加内存表没上etcd、一个执行触达逻辑的Python进程用的FastAPI理由就一个词异步顺手、以及一个和LLM对接的桥接层兼容OpenAI格式的接口都行我实测对自定义Agent框架同样适用。安装过程非常简单python -m venv .venv source .venv/bin/activate pip install agent-reach0.2.0 fastapi uvicorn sqlalchemy uvicorn agent_reach.hub:app --port 8000跑起来之后默认会暴露两个HTTP接口一个是POST /reach/dispatch供Agent执行循环调用另一个是POST /reach/register用来注册新的Reach Spec。我开发调试时习惯本地起这个服务连一个debug模式的LLM这样每次改完Reach Spec能看到完整的触达链路日志。3.2 第一步注册一个“查订单状态”的触达点我们用刚才那个查询订单状态的例子走一遍注册流程。业务侧的查询逻辑可以长这样# order_repo.py from agent_reach import register register( idreach_kb_order_status, typeknowledge, description根据订单ID查询订单的当前状态待支付/已支付/已发货/已完成/已取消, input_schema{ order_id: {type: string, required: True, desc: 14位订单编号}, }, auth{scope: order_service.read, owner: fulfillment-team}, timeout_ms3000, ) def fetch_order_status(order_id: str) - dict: 内部函数从订单数据库取状态 row db.query(select status, updated_at from orders where order_id?, order_id) if row is None: return {found: False, message: 订单不存在} return {found: True, status: row[status], updated_at: row[updated_at]}这里有几个值得注意的设计细节id是全局唯一的格式我统一用reach_tool_、reach_kb_、reach_agent_前缀方便Resolver做类型过滤。description老老实实把这个触达能做什么、不能做什么写清楚。我见过有人写“一个订单函数”模型看了根本不知道什么场景该选它。timeout_ms不是随便填的。知识库查询如果超过3秒说明数据源有问题Agent不如直接告诉用户“暂时查不到”也好过等一个慢查询拖垮整个对话。注册完成后可以通过另一个脚本验证curl -X POST http://localhost:8000/reach/dispatch \ -H Content-Type: application/json \ -d {reach_id: reach_kb_order_status, params: {order_id: 20250101000123}}标准输出会返回{status: ok, data: {found: true, status: 已发货}}。走到这一步你的Agent-Reach服务已经被业务侧打通了。3.3 第二步改造Agent执行循环真正让Agent能动起来核心在于把Reach调用嵌进它的思考-行动循环里。我用到的执行循环结构大概是这样的伪代码def run_agent(user_input): pico_state {messages: [{role: user, content: user_input}]} for step in range(MAX_STEPS): # 1. Resolver 筛选候选 Reach Spec candidates reach_resolver.filter(user_input, pico_state) # 2. 组装上下文把候选 Spec 注入系统提示词 prompt build_prompt_with_reaches(candidates) # 3. 模型决策返回文本回复 或 一个 Reach 调用请求 response llm.chat({**pico_state, messages: [system(prompt), *pico_state[messages]]}) # 4. 如果模型决定触达 if response.tool_calls: for call in response.tool_calls: result reach_gate.dispatch(call.reach_id, call.params) pico_state[messages].append({role: tool, content: result}) continue # 继续下一轮思考 # 5. 如果模型给出最终回复 return response.content这个循环看起来很简单但有一个关键点必须强调每次模型触达之后返回结果必须作为新的“工具消息”追加进上下文让模型看到触达结果再基于结果生成最终回复。我见过不少团队在跑循环时把工具返回结果丢掉了模型等于“空手回复”触达动作做了个寂寞。为了让模型能正确产出触达请求我在它的系统提示词里固定加了一段说明当你需要查询实时信息、调用内部工具、或者向其他Agent发起协作时 请输出一个Reach调用请求格式如下 {reach_call: {reach_id: 候选Id, params: {}}} 只能使用Reach候选列表里给出的reach_id不要编造不存在的id。加一段Few-shot示例模型基本一次就能学会。3.4 第三步让Agent之间通过Reach互相触达单Agent跑通之后我开始做多Agent协作这也是Agent-Reach名字里“Reach”最有意思的部分。我在Hub上注册了三个Agent一个负责需求理解一个负责技术方案设计一个负责代码审查。它们之间通过type: reach类型的Reach点进行消息传递。实际注册一个Agent协作端点和其他类型没有本质区别id: reach_agent_code_review type: reach name: 发起代码审查 description: 将待审查的代码片段或PR链接发送给代码审查Agent返回审查意见列表 input_schema: review_id: type: string required: true code_ref: type: string required: true desc: Git仓库文件路径或PR URL priority: type: enum values: [low, normal, high] default: normal handler_type: python_function handler: agent_coordinator.request_review这个agent_coordinator.request_review内部做的事情是把任务内容塞进审查Agent自己的消息队列然后异步等待它的返回结果。为了不让发起方长时间干等我把这个协作用的是一次2分钟的“带超时轮询”超时返回“审查排队中稍后可查”。这个设计很好地避免了一个Agent长时间阻塞整个执行循环的尴尬。3.5 调试工具箱三条必用的排查命令实际开发里不是写了代码就能一次跑通。我给自己配了三个调试利器建议你也照着配一份查看当前所有已注册的Reach Spec清单GET /reach/list输出JSON格式方便检查有没有重复id、description写得是否模糊。模拟一次触达但跳过模型POST /reach/dispatch?dry_runtrue直接把参数喂给某个Endpoint看业务侧返回是否正常这样可以快速判断问题出在模型决策还是业务系统。看最近N条触达审计日志GET /reach/audit?limit50每一条触达的参数、结果、耗时、发起会话都记录在案排查线上问题全靠它。有一次线上故障排查我花了两个小时定位到是某个旧端点的超时配置写得太短业务侧逻辑处理到一半就被Agent-Reach主动断开了。后来全靠审计日志里的timeout_ms列一眼看到了问题。有审计和没审计Agent项目的线上运维是两种体验。4. 实测中遇到的四个坑现象、原因、解决办法4.1 上下文膨胀Reach Spec清单越塞越多模型选不准最初版本我会把所有已注册的Reach Spec全部投喂给模型让它在候选里做选择。项目跑到第3个月Endpoint数量到了27个每天早上10点高峰期的对话延迟明显比两周前高。我用消融法逐步排查一开始以为是对话历史变长了压缩历史后延迟还是高然后把系统提示词里的Reach Spec清单截断了一半延迟立刻降了40%。再细看日志模型在选择Endpoint时面对20多个候选经常犹豫有时还会输出一个不存在的id。根因是信息过载。模型面对一堆相似描述的工具选择难度指数级上升。解决方案就是我前面提到的“先检索再投喂”三层Resolver上线后每次实际投喂的候选不超过5个模型选择准确率从69%升到了92%prompt体积缩到原来的三分之一。4.2 慢触达拖垮对话Agent等结果等到“失忆”有个触达是调用外部CRM系统的API查询客户历史沟通记录。CRM那边时不时响应超过5秒。问题来了Agent发出触达请求后整个执行循环会同步等待等待期间上下文里的临时信息不会刷新等结果回来时模型已经“忘了”最初用户说的是什么回复质量直线下滑甚至有两次模型在等待期间自己脑补了一个结果完全没看真实返回值。我做的修复是给触达分了三档SLA级别典型场景超时上限等待策略快速本地函数、缓存查询300ms同步等待标准内部接口、知识检索3s同步等待慢速外部CRM、跨Agent协作10s以上异步回调先回进度消息对于慢速触达我改成了“先给用户一个中间反馈例如‘正在为您查询CRM记录预计需要15秒’然后触达完成后把结果作为一条新消息追加进会话让模型再基于结果生成最终回复”。这样用户的体验是“Agent先应答、后出结果”而不是“整个对话卡死十秒”。4.3 模型“发明”了一个不存在的触达点这是个很好笑也很吓人的坑。有一次模型在回答用户“帮我查一下供应商到货记录”时输出了一份Reach调用请求reach_id是reach_kb_supplier_arrival但它根本不存在。我的代码直接用这个id去查注册表返回了空结果模型居然还在那里一本正经地编了一份“供应商到货记录”出来。排查链路是这样的我先在审计日志里输入输出比对发现调用失败但模型没有感知到失败依然生成了答复。进一步看系统提示词发现里面只有一句“使用候选列表中的reach_id不要编造不存在的id”模型在候选列表语义不够清晰时会“合理想象”一个名字。修复做了两件事。第一在Reach Gate里强制加入了“only_dispatch_known1”的配置遇到未知id直接中断流程并明确返回“该触达点不存在请从候选中选择”让模型看到这个错误后自纠。第二给每个候选Reach Spec加上了更加明确的示例和“不能做什么”的负面说明减少模型“自由发挥”的空间。从那以后编造id的情况基本清零。4.4 Agent互相等待协作型死锁做多Agent协作的时候最复杂的一个问题是死锁。有一次线上跑着跑着一个需求分析Agent在等代码审查Agent的审查结果而代码审查Agent又在等需求分析Agent提供补充材料两边互相等待各自执行循环都卡在超时边缘请求越积越多整个Hub的响应都变慢了。我用两条机制解决了这个问题给每个type: reach的协作端点加了max_hops限制即一次协作触达最多允许嵌套转发3次超过直接返回“协作链路过深请拆分子任务”。给协作请求加了一个全局唯一的request_chain_id发现同一链路里出现循环等待时立即熔断返回“检测到循环协作已终止”。这个机制上线后再没出现过Agent互相等到天荒地老的状况。多Agent协作看起来自由其实比单Agent更需要纪律。Agent-Reach的协作端点就是给这种“有纪律的自由”兜底。5. Agent-Reach的操作心得哪些设计值得坚持哪些地方还该优化5.1 这个方案解决了什么问题整套Agent-Reach跑下来大半年我最满意的不是某个Agent的回答准确率提升了多少而是它把“Agent触达”这件事从“每个Agent自己随便发挥”变成了“一套可注册、可筛选、可审计的规范动作”。团队里新来的同学接手Agent项目不再需要翻遍代码找某个功能写在哪而是打开/reach/list看Reach Spec清单就知道系统里有哪些触达能力、每个能力需要什么参数、有什么权限要求。这套思路放大了说其实就是把Agent当成一个有“规范API”的员工在管理而不是当成一个“你说什么它猜什么”的应急工具。模型负责理解和生成Agent-Reach负责把理解和生成落到真实世界的动作上。两者各管一段出了问题也好定位。5.2 目前妥协的地方与值得尝试的优化说得务实一点Agent-Reach现在还有几个不完美的地方。一是Resolver的语义检索依赖embedding模型的质量遇到专业术语很多的场景召回结果偶尔会跑偏。目前我是靠规则层兜底纠正的但如果团队有预算用一个针对垂直领域微调的embedding模型效果会更好。二是触达结果没有做“语义级缓存”。同一个用户隔了一天问同样的订单状态Reach还是会打一次数据库。如果做一个按“参数时间窗口”的缓存层很多查询类触达的响应速度还能再上一个台阶。三是审计日志目前只记录到了“参数和结果”级别没有记录“这次触达前后模型上下文的差异”也就是说我看不到“模型因为这次触达回复质量到底变好了多少”。下一篇技术分享我想做的方向就是给每条触达算一个“上下文增益”指标用来自动评估每个Endpoint的真实价值把那些“模型经常选错、触达后回复质量没有提升”的冗余端点清理掉。5.3 给准备做同类体系的团队三个建议如果你们团队也在搭自己的Agent触达层无论叫不叫Agent-Reach有三点我强烈建议从第一天就坚持从第一个触达点开始就带权限和审计别想着后补。模型一旦习惯了“什么事都能直接调”再收权限会非常痛苦。Reach Spec的description请认真写写清楚“能做什么、不能做什么、参数怎么填”在这里花十分钟能省下后面几周的调参时间。一切触达的请求和返回值都走结构化JSON不要图省事直接用自然语言文本回传。结构化数据模型能直接消化自然语言回传还要额外做一层“理解”白白增加延迟和出错概率。我自己的感受是Agent项目到了中后期拼的不是谁的模型更强而是谁的Agent更能“够得着”。你给它触达能力之前它只是一个聪明的文本生成器你给它一套收放有度的触达层之后它才真正像一个能干活、能担责、能被管理的数字员工。Agent-Reach这个名字起的其实就是这个意思。