做 agent 开发这两年我发现一个特别有意思的现象几乎每个人在搭完第一个 agent demo 之后的第二天就会撞上同一堵墙。Demo 里那个 agent 能查天气、能算数、能帮你总结一篇文章你觉得它无所不能。可一旦你让它去读公司内网的接口、去调一个需要鉴权的第三方服务、去把结果写进某个具体的业务系统里它立刻就开始胡说八道或者干脆报错退场。这个从能聊天到真能干活之间的鸿沟就是我这次想聊的 Agent-Reach 要解决的核心问题。第一次看到 Agent-Reach 这个名字很多人会下意识把它当成又一个 agent 框架。但Reach这个词其实很关键它说的是 agent 的触达能力——一个 agent 到底能伸手够到多远的东西。是只能摸摸本地的几个函数还是能稳定地触达工具、技能、外部系统、乃至另一个 agent。这套思路不是要替代你手里正在用的 agent 框架而是补上框架最容易忽略的一层把能力变成可被路由、可被复用、可被观测的东西。我下面会按自己搭这套东西的完整过程来讲包括架构为什么这么设计、每一步具体怎么落地、会踩哪些坑、报错怎么排查、测试怎么跑、安全边界怎么划。不管你是刚接触 agent 开发、想搞懂 ai agent 到底是什么还是已经写过几个 agent 项目、想往工程化和多 agent 协作方向走应该都能从里面捞到点能直接抄作业的东西。1. 先搞清楚 Agent-Reach 里的Reach到底指什么在动手之前得先把概念对齐不然写着写着就会乱。我见过太多人把 agent 框架、agent skill、harness 这几个词混着用结果架构图画出来自己都看懵。1.1 一个所有 agent 开发者都绕不开的老问题假设你现在手里有一个能跑起来的 agent底层接的是某个大模型工具注册了五六个函数。你让它做一件事帮我把上个月的销售报表拉出来按地区汇总然后生成一张图。这句话背后其实藏了三段截然不同的触达需求。第一段是拉数据它要触达一个数据源第二段是按地区汇总它要触达一段计算逻辑第三段是生成图它要触达一个绘图能力。问题来了这三段能力谁来决定用哪个谁来保证调用顺序某一段失败了怎么办模型说它想调用一个根本不存在的能力你怎么办大部分 demo 级 agent 的答案是把这三件事全塞进系统提示词里让模型自己去猜、去编。这就是一切混乱的源头。模型不是不能编排而是它编排的依据全在上下文里缺少一个外部的、结构化的能力目录来兜底。Agent-Reach 要干的第一件事就是在模型和真实能力之间插一层专门管理触达的中间结构。1.2 Reach 不是连接是触达能力很多人第一反应会把 Reach 理解成网络连接、接口打通。这个理解偏了。连接解决的是能不能通而 Reach 解决的是够不够得着、够得着多少、够得着之后稳不稳。打个比方。你家有根网线插上就能上网这叫连接。但如果你要在网上办一件事你得知道去哪个网站、要填什么表、表单字段格式对不对、填错了系统会不会吐回一个错误、下一步该点哪个按钮——这一整套知道去哪、知道怎么操作、知道出错怎么办的组合才叫触达。Agent-Reach 里那个 Reach说的是后者。落到工程上它至少要管四件事能力的登记有哪些工具、技能、子系统可以被 agent 使用它们的名字、参数、约束是什么。能力的路由用户那句自然语言该被拆成哪几步、每步该落到哪个能力上。能力的执行与回传调用出去之后结果怎么结构化地回来异常怎么捕获。能力的记忆这次触达过哪些能力、踩了什么错下次能不能少走弯路。这四件事被管住了agent 才从花架子变成能干活的工具人。1.3 Agent-Reach 和 skill、harness、框架到底啥区别这几个词是热词里问得最多的我用一个表把它讲透后面看架构图会顺很多。概念关注点类比谁来做agent 框架整个 agent 的骨架、循环、模型接入一辆车的底盘和发动机你选型比如某个开源编排框架agent skill一个具体可复用的能力单元车上的一个专用工具头业务方或第三方提供harness把模型包起来、控制它怎么被调用和评测的外壳试车台专门测这车行不行评测和调试阶段搭Agent-Reach让 agent 能稳定触达外部能力的路由与治理层车载导航加调度中心你自己搭贴着业务长一句话总结框架决定 agent 是什么skill 决定它能做什么harness 决定你怎么测它而 Reach 决定它实际够得着并且用得稳什么。很多人混淆 harness 和 agent本质是没分清被测对象和测试外壳。换到 agent 和 skill 的区别上则是没分清主体和能力。所以 Agent-Reach 不是又一个框架它更像一层能力总线。你可以把它挂到任何主流的 agent 编排方案上也可以先手写一个最小版本跑通再逐步替换里头的组件。这也是我建议的路线先跑通再优化别一上来就追求大而全。2. Agent-Reach 的整体架构与设计取舍讲完概念说架构。我不打算给你画那种十八个框、箭头绕来绕去的图因为那种图除了好看没啥用。我只讲真正影响你编码的三个层以及每一层为什么非这么切不可。2.1 三层结构入口层、路由层、执行层我把 Agent-Reach 拆成三层这个切法是我试过几轮之后定下来的核心原则是每一层只干一件事出错了好定位。入口层负责把五花八门的输入收拢成统一格式。用户的自然语言、上一步的中间结果、系统注入的上下文全在这里被规整成一个标准请求对象。为什么要单独拎出来因为真实场景里输入来源太杂了——有网页端的、有定时任务的、有另一个 agent 转发过来的。如果不在入口统一后面每一层都要写一堆兼容代码改一次哭一次。路由层是整个系统的咽喉也是热词里反复出现的路由识别节点所在的地方。它吃进标准化后的请求吐出要调用哪个能力、按什么顺序、传什么参数的执行计划。这一层是 Agent-Reach 区别于普通 agent 的关键因为它把模型自由发挥收窄成了在能力目录内做选择。执行层拿着执行计划去真正调用能力负责参数校验、异常捕获、结果回传。它的设计要点是无状态、可重试每次调用都当成一次独立事务来处理。三层之间只通过明确定义的数据结构通信绝不共享内部状态。这样你换掉任何一层——比如把规则路由换成模型路由或者把本地执行换成远程执行——其他两层基本不用动。这是我踩过耦合地狱之后最想强调的取舍。2.2 路由识别节点为什么是整个系统的咽喉路由节点值得单独拿出来说因为它决定了 Agent-Reach 的上限。我一开始图省事让大模型直接输出调用哪个工具结果发现两个稳定问题。第一模型会编能力名尤其是能力多的时候它会造一个听起来很合理但根本不存在的工具出来。第二模型对调用顺序没概念它会同时想调三个工具完全不顾它们之间的依赖。这两个问题靠提示词是治不干净的。后来我改成两段式路由。第一段是候选召回先从能力目录里按关键词、语义相似度、历史命中召回一个不超过 N 个我一般设 8 到 12的候选集。第二段才是精排与决策把候选集连同请求一起交给模型让它在这个受限集合里做选择并输出结构化的执行计划。这样做的好处立竿见影。因为模型的选择空间被收窄了它编不出目录里没有的能力因为执行计划的格式是强约束的谁在前、谁依赖谁、参数走哪个字段顺序问题也能被校验出来。代价是你要维护一个还算像样的能力目录——但这份维护成本比起线上 agent 天天乱调能力的排查成本简直不值一提。2.3 记忆层让 agent 记住它究竟触达过什么热词里agent 记忆被问得很多但很多人的理解停留在把对话历史存下来。放在 Agent-Reach 的场景里记忆还得再多记两样东西能力使用记录和错误经验。能力使用记录指的是针对这类请求历史上哪个能力组合效果好。有了它路由节点的候选召回就能带上先验命中率和速度都会好一截。错误经验则更值钱某个能力在什么参数区间容易失败、某个外部接口的限流规律、某类请求的常见失败原因这些都该被沉淀下来而不是每次都从零开始试。我的做法是分两层存。短期记忆放在进程内的一个轻量缓存里只保留当前会话最近的若干次触达记录读写极快。长期记忆落到一个持久化存储里按能力维度和请求类型维度分别建索引。查询时先查短期miss 了再回落到长期。这套分层在实测里能把路由的重复计算砍掉一大半。提示记忆层不要什么都存。我吃过亏一开始把每次调用的完整入参出参全存了存储涨得飞快不说召回时噪声还特别大。后来改成只存摘要关键参数结果状态效果好很多。3. 从零把 Agent-Reach 搭起来完整实操拆解前面都是铺垫接下来是能直接上手抄的部分。我按真实搭建顺序讲每一步都带上我的选择理由和当时的现场记录。3.1 环境与依赖准备先把最小依赖定下来。别一上来装一堆库跑通再说。# 一个能跑的 Python 环境即可我用的 3.10 python -m venv .venv source .venv/bin/activate # 核心依赖就这几个 pip install pydantic requests # 如果你要接模型再装对应 SDK这里不绑定具体厂商我特意用pydantic来定义能力描述和执行计划的数据结构原因是它能做参数校验能在路由层就把格式错误挡掉而不是等执行层调用失败才发现。这一步省下来的是后面 Debug 的时间。目录结构我也贴一下这套结构我用了很久扩充能力时很顺agent_reach/ registry/ # 能力目录每个能力一个描述文件 router/ # 候选召回 精排决策 executor/ # 调用与异常捕获 memory/ # 短期缓存 长期存储 schemas/ # 所有数据结构的定义3.2 能力注册把你的工具挂到 Reach 上能力注册是整套东西的地基。我给每个能力定义一个统一描述字段不多但都要紧from pydantic import BaseModel, Field from typing import Any class CapabilitySpec(BaseModel): name: str # 能力唯一名路由靠它 description: str # 给模型看的语义描述要写清楚干什么 keywords: list[str] [] # 用于候选召回的关键词 params_schema: dict[str, Any] # 参数结构用于校验 timeout_s: int 15 # 单次调用超时 retry: int 1 # 重试次数 side_effect: bool False # 是否有副作用写操作这里有几个字段是踩坑加出来的。keywords直接决定了候选召回准不准我一般会写上同义词业务黑话常见误写。side_effect特别重要——凡是带写操作的能力路由时我会强制它走串行、且必须经过确认避免 agent 并发地把数据库改乱。timeout_s和retry则决定了执行层遇事是硬扛还是快速放弃。注册本身很简单就是把描述文件丢进registry/启动时加载进内存再建好倒排索引。我在现场记录里写过一句话能力目录的质量等于整个 Agent-Reach 的上限。目录里描述写得含糊后面路由再聪明也救不回来。注意别把粒度切太细。我一开始给查用户和查用户订单拆成两个能力结果候选召回时它俩老打架。后来合并成查询带 resource 参数路由一下子就清楚了。能力粒度以路由时能明确区分为准。3.3 路由与执行一次完整调用链现在把一次真实调用串起来。用户输入帮我把上个月销售报表拉出来按地区汇总并生成图。第一步入口层标准化。收拢成一个请求对象带上用户身份、时间范围等上下文。身份很关键后面执行层做权限校验要用。第二步候选召回。用请求里的关键词去倒排索引里捞同时叠加历史命中召回 8 个候选能力拉数据、按维度汇总、绘图、发邮件、查缓存……等等。这里不要求精确宁滥勿缺。第三步精排决策。把请求和候选集交给模型要求它输出结构化执行计划。计划长这样{ plan: [ {step: 1, capability: fetch_report, params: {period: last_month}}, {step: 2, capability: aggregate, params: {by: region, from: step1}}, {step: 3, capability: render_chart, params: {data: step2, type: bar}} ] }注意from: step1这种引用写法它让步骤间的依赖显式化执行层就能按依赖拓扑排序而不是傻按数组下标跑。第四步校验。执行前拿每个参数去params_schema里校验。类型不对、必填缺失、越权访问全在这一步挡掉。这一步是我加得最值的一次重构它把线上执行到一半才报错的问题前移成了计划阶段就拒绝。第五步执行与回传。按拓扑序执行每一步的结果塞回上下文供下一步引用。任何一步失败按retry策略重试超了就走异常分支。执行层无状态所以整条链可以安全重放。第六步写记忆。把这次请求类型 → 能力组合 → 结果状态的摘要写进记忆层。下次同类请求候选召回的命中会更快更准。整套跑下来最慢的是模型精排那一下实测在秒级其余环节都是毫秒级。这也是为什么我把候选召回和精排分开——把昂贵的模型调用限制在极小的候选集上整体延迟和稳定性都好看。3.4 多 agent 协作下的 Reach 扩展单 agent 跑通之后很自然会想做多 agent 协作。这时候 Agent-Reach 的价值会更明显因为它天然把能力和主体解耦了。我的做法是让每个 agent 有自己的一份能力子目录同时共享一份公共能力目录。当 agent A 需要的能力不在自己目录里、而在 agent B 的目录里时路由节点不会直接去调而是生成一个委托步骤——把请求转发给 B 的入口B 用自己那份 Reach 去执行再把结果回传给 A。这套机制有三个好处。第一权限天然隔离A 够不着 B 的私有能力除非 B 显式开放。第二能力可以复用公共能力只维护一份。第三出问题好定位委托链上每一跳都有独立日志。热词里的多 agent 协作和agent 编排落到工程上核心其实就这一件事把谁能触达什么这件事变成一份显式的、可查的契约而不是靠 agent 之间互相猜。提示多 agent 委托容易形成死循环A 委托 BB 又委托回 A。我的兜底是给每个委托链打一个跳数计数超过阈值直接终止并报错别让它无限转下去。4. 踩坑实录常见报错与排查方法这一节全是血泪。我把线上真实撞到的问题整理成速查表遇到报错先对着找。4.1 agent execution terminated due to error 在说什么这是被问得最多的一条报错也是信息量最少、最气人的一条。它本身只说明执行被中断了具体原因埋在下面。我按从外到内的顺序给你一条排查链先看是不是超时。最常见。某个外部能力响应慢超过了timeout_s执行层直接中断整条链。解决要么调大超时要么给该能力单独设更长的超时并加降级。再看是不是参数校验失败。路由给的参数过不了params_schema执行前就被拒。这种错误信息通常在上一条日志里。然后看模型输出是不是格式坏了。精排阶段模型偶尔会输出不合法的执行计划比如引用了不存在的 step。校验环节没拦住就传到执行层了。最后看外部依赖。被调服务挂了、鉴权过期、限流。这类要在执行层把原始错误完整记录并向上抛别吞掉。4.2 排查速查表现象最可能的原因快速处置execution terminated能力超时调超时或加降级模型调了不存在的能力候选召回没限制住检查能力目录与召回上限步骤顺序错乱依赖没显式化强制用 step 引用而非下标偶发调用失败、重试就好限流或瞬时抖动加退避重试结果串味拿到别人的数据身份没透传执行层强制带 identity 校验计划阶段就报错参数校验过严或过松校准 params_schema4.3 几个从实践里抠出来的避坑经验第一永远不要把模型当成路由的唯一依据。候选召回、格式校验、依赖检查这些能用规则做的就别交给模型。模型负责在有限集合里做语义选择这是它的强项让它去保证格式和顺序就是强人所难。第二错误信息要留全。我早期为了日志干净把外部错误截断成一句调用失败结果排查时两眼一抹黑。后来改成保留原始错误栈加一层语义包装排查效率翻倍。第三给所有写操作上锁。凡是side_effect为真的能力路由时强制串行执行前要求确认。这不是过度设计而是我亲眼见过 agent 并发地把一批数据改了两次。第四超时和重试要成对出现。只设超时不设重试网络抖动就会让请求白跑只设重试不设超时异常能力会拖垮整条链。两者搭配再配一个退避策略才稳。5. 进阶话题安全边界、测试流程与学习路线搭完能跑只是第一步。要真敢用在生产里还得补上安全、测试和持续学习这三块。5.1 Agent-Reach 的安全边界怎么划agent 安全是个大话题但落到 Reach 这层核心就四条边界。能力边界agent 能触达的能力是白名单目录外的一律拒绝。这条把模型编造能力从根上堵死。权限边界每个请求带身份执行层逐次校验谁能调什么、能调多少写死在配置里而不是提示词里。数据边界跨 agent、跨租户的数据不能串所有结果回传都带归属标记。操作边界写操作、删除操作、对外发送类操作一律需要二次确认或人工审批环节。我自己的经验是安全不能靠提醒模型注意,而要靠结构化约束。你把边界做成代码里的硬性校验模型再聪明也越不过去你把它写成提示词里的一句请不要做危险操作那迟早出事。5.2 测试流程与方法agent 的测试和普通软件不一样因为输出是不确定的。我的测试分四层跑。单元层能力本身怎么测就怎么测输入输出确定和 agent 无关。路由层给定请求检查候选召回和精排出的执行计划是否合理这一层用固定用例回归防止改一处坏一片。链路层端到端跑真实请求重点看不该触达的能力有没有被触达、该串行的有没有串行。对抗层故意给模糊、诱导、越权的输入看 agent 会不会越界。关于agent 测试流程与方法我特别想强调一点别只测成功路径。真实线上绝大多数事故出在异常分支——超时怎么处理、限流怎么退避、部分成功怎么回滚。把异常路径的用例补起来比多测一百个成功案例有用得多。5.3 从零到能上手的 agent 学习路线最后聊学习路线这也是热词里问得密集的一块。结合 agent 开发学习路线和面试常问的点我给一条我自己走过的顺序。先补基础概念把 agent 是什么、agent 架构、路由识别节点这几个词搞清楚能说出一个请求大概怎么流转。再动手写一个最小 agent只接一个大模型加两个工具先建立手感。然后专门吃透能力注册 路由这一层也就是 Agent-Reach 的核心这一步是从会写 demo 到能做项目的分水岭。接着补记忆和异常处理让 agent 稳下来。最后再碰多 agent 协作、安全、测试这些工程化话题。如果你是前端转 agent 开发我建议把输入标准化和状态管理当切入点因为你本来对数据流转就敏感。如果你在准备 agent 面试把框架和 harness 的区别agent 和 skill 的区别路由为什么不能用模型一把梭这几个能讲透基本就能接住大部分追问。我个人在实际操作里的体会是Agent-Reach 这类东西听起来抽象但真正做起来最有价值的往往不是那些巧妙的算法而是最开始那份能力目录和那几条硬性边界。把这两样做扎实了后面路由怎么调、记忆怎么加都是顺水推舟的事。踩过几次坑之后你会明白让 agent 变强的从来不是让它想得更野而是把它的手稳稳地、有限地、可观测地伸出去。