1. 项目缘起Agent-Reach 到底想解决什么问题做 AI Agent 开发的朋友应该都有过这种体会单机版的 Agent 跑得再顺一旦想把能力真正放进业务里就会遇到一堆让人头疼的问题。你训练了一个很会写 SQL 的 Agent但业务方问的是“帮我看看上个月华东区哪个品类的退货率涨得最凶”你做了一个能调内部 API 的工具型 Agent结果它连外部系统的数据都摸不到你辛辛苦苦编排了三个 Agent 协作结果它们互相等对方响应活活能把一个查询流程拖成五分钟。我做的这个 Agent-Reach 项目核心要解决的就是 Agent 的“触达”问题。这里的 Reach 有两层含义一是 Agent 对工具、数据、外部系统的触达能力二是多个 Agent 之间互相协作时的触达效率。说得直白点就是让 Agent 不再是一个个孤岛而是能真正把手伸到该伸的地方并且伸手的速度足够快。这个项目适合三类人参考正在做 Agent 应用落地的工程师、需要在系统里接入 AI 能力的后端开发者以及想把实验性 Agent 工程化、产品化的技术负责人。文章里的所有思路都经过了实际项目验证我会把我踩过的坑、反复调过的参数、最后留下的方案都写清楚。如果你正准备上手可以直接把里面的框架拿过去改改再用。先说结论Agent-Reach 不是一个具体的框架而是一套“扩展 Agent 能力边界的方法论配套实现方案”。整个项目围绕三个核心展开能力编排层、运行时协议、协作治理机制。这篇博文会完整拆解这套方案的每一个关键环节。2. 整体设计思路把 Agent 当“可编排的微服务”来设计2.1 核心思路能力网关化我最早做 Agent 集成的时候犯过一个典型的错误把 Agent 当成一个“黑盒函数”来调用传 prompt 进去等字符串出来。这在小规模演示时没问题一旦到了生产环境就崩了——你没法监控它调了什么工具、没法控制它的权限边界、出了问题也没法定位是模型的问题还是工具的问题。后来我换了个思路把 Agent 的能力做网关化处理。也就是说不直接暴露 Agent 本身而是把 Agent 能做的事抽象成一组“能力条目”每条能力都有清晰的入参、出参和权限声明。外部的业务系统、其他 Agent、甚至前端应用都只通过这个能力网关来访问 Agent。这样做的好处非常直接。首先是可控性每一个能力请求都可以做鉴权、频控、审计其次是复用性同一套 Agent 能力可以被不同业务场景调用不用每个场景单独拉一个新 Agent最关键的是让“Agent 间互相调用”变成了一个标准化动作——它们之间不再是“传一句话”这种模糊交互而是像微服务之间那样有明确的接口契约。这个设计思路的转变是我做 Agent-Reach 收获最大的一点。如果你现在正要规划多 Agent 系统第一件事不是选框架而是先把“能力边界”画清楚。2.2 领域建模Agent 的“地图”怎么画能力网关化之后紧接着的问题就是能力条目怎么定义这一步做不好后面全是坑。我把 Agent 的能力建模分成四层第一层是领域层。比如一个电商运营 Agent它的领域是“商品”“订单”“用户”“营销”这四块。划分领域的原则是看业务归属而不是看实现方式。订单查询和订单修改都属于“订单”领域但改价这种操作实际上应该归到“营销”或“风控”领域因为它涉及权限级别完全不同。这个划分直接影响后面的权限设计建议早期就多和业务方对齐。第二层是意图层。每个领域下面挂若干意图比如“订单”领域下可以有“查询订单状态”“批量导出订单”“修改订单备注”等。意图的粒度控制在能对应到一个明确的工具调用别把意图定义得太粗。我见过有人把一个“处理售后”定义成一个意图结果里面包含了退款、换货、补偿、催物流四类操作Agent 每次都得猜你要干什么猜错的概率非常高。第三层是工具层。每个意图背后挂的具体执行能力比如“查询订单状态”对应一个查订单 API“修改订单备注”对应一个更新接口。工具层的重点是定义清楚入参约束哪些字段必填、哪些可空、取值范围是什么都要用 JSON Schema 写死。第四层是权限层。谁可以调用哪个领域的哪个意图调用时需要满足什么条件。我做了一个简单的规则引擎用策略表来管理这个映射关系比硬编码在代码里灵活得多。2.3 协议与工具链选型为什么选标准协议而不是自己造轮子在协议层我最初纠结过要不要用原生的 function calling 格式后来还是决定做一层抽象用标准化的 JSON-RPC 风格协议来封装所有工具调用。原因很简单团队里不可能只有我一个人维护这个系统大家都会往里面接新工具。如果协议是私有的每个新工具接入都要改主代码如果协议是标准的新工具只需要写一个适配器就能挂进来。具体到实现上我定义了一个统一的能力描述结构tool_id、description、parametersJSON Schema、required_roles、timeout_ms、rate_limit。系统加载工具时会先把描述文本和参数 Schema 一起拼进系统提示词里这样模型能够理解什么时候该调这个工具。描述文本的写法很有讲究不能写“查询订单”得写“当用户询问订单物流状态、预计送达时间、订单是否已发货时调用本工具获取订单详情”。描述写得越具体模型选错工具的概率越低。传输层我直接用了 MCP 的简化变体没有用完整实现。倒不是说完整版不好而是我们这阶段的场景用不到那么重的基础设施。简化版的好处是工具列表可以动态下发、参数校验走标准 JSON Schema、调用结果统一返回结构化 JSON后续真需要切到完整 MCP协议层可以平滑迁移。这个决定帮我省了大量维护成本新工具接入的时间从原来的半天缩短到了半小时。3. 核心细节与实操要点五个关键设计3.1 工具描述的“翻译”功力工具描述不是写文档是在给模型“翻译”你的接口。我举个具体的例子。数据库里有个字段叫return_rate_by_region你要让 Agent 理解它的用途不能直接写“返回各区域退货率”而要写成“给定时间范围和区域编码列表时返回退货率数据用于分析各地区商品质量问题或物流异常。”模型看到这种描述才能在用户问“哪个地方退货最严重”时想起调用它。还有一种情况多个工具的语义很像。比如“更新订单地址”和“重发订单”是两个完全不同的工具但在用户嘴里可能都是“帮我改一下收货地址”。这时候描述里要主动写出边界“更新订单地址仅修改当前待发货订单的收货信息已发货订单请使用售后退货流程不可直接调用本工具。”给模型划定禁区比让它自由发挥要靠谱得多。工具描述的另一个注意点是控制长度。我统计过线上日志工具描述总字数超过 3000 字之后模型的理解准确率会明显下降。所以我现在要求每个工具描述控制在 100~150 字以内多余的细节放到参数约束里让字段名和枚举值自己说明。3.2 状态管理与上下文传递Agent 的 Reach 范围越大状态管理的复杂度就越高。一个最基本的单 Agent 流程还好一旦涉及多轮对话工具调用跨会话状态很多人会直接把所有上下文全塞进 prompt。我自己也在早期这么干过结果 token 消耗爆炸响应变慢模型还容易被无关信息干扰。我的经验是给每个会话建立一个轻量级的“状态快照”里面只保存四类信息当前意图、已确认的关键参数、待确认的参数列表、最近一次工具调用的结果。每一轮对话开始时把状态快照和当前用户输入一起送给模型每轮对话结束时更新这个快照。那些历史对话原文我不保存在上下文里只是当做可追溯的日志落盘。这里有一个细节值得说状态快照里的“已确认参数”最好用结构化的 JSON 存储这样在需要调用工具时不需要让模型自己去“回忆”——直接从快照里提取就行。我在实践中发现让模型从一大段对话里推理出参数出错率比直接给它填好的 JSON 高不少。状态快照本质上是把“记忆”从模型推理过程里剥离出来变成显式的数据这样既省 token又更可靠。3.3 工具调用跨系统时的数据兼容Agent 要触达的能力往往分布在不同的系统里有的返回 JSON有的返回 XML有的返回一个分页结构还有的根本不是标准格式。这里最容易出的问题是模型以为它拿到的数据就是最后答案直接拿去回答了但实际上这个数据还需要后处理。我加了一个“结果后处理”层在工具返回结果之后、送回给模型之前做一次标准化统一把数据转成 JSON 结构、把金额和日期统一单位、把字段名映射成模型更熟悉的中文语义。这样模型拿到的数据已经是“干净”的它只需要做最终的总结和输出。还有一类问题是流式返回。有些业务系统是流式接口比如日志查询、实时监控数据。传统工具调用里模型发了请求就等着完整返回碰到流式接口就会卡住。我在 Agent-Reach 里做了一个流式适配器把流式响应先按时间窗口聚合成一批批的小数据块每个数据块作为一个独立的消息送回到模型模型可以边看边回答。实测下来这种模式在处理长耗时查询时体验提升明显而且可以边生成边出结果不会让用户干等。3.4 缓存策略让 Agent 学会“记住今天查过的东西”Agent 的触达范围广了之后高频重复调用就成了性能瓶颈。比如用户问“今天华东区销量多少”一分钟后又问“华东区今天卖了多少”如果每次都真的去查一遍数据库既慢又浪费资源。我在 Agent-Reach 里加了一层意图级缓存在意图执行之前先用意图分类器算出当前请求属于哪个意图然后把“意图关键参数”的组合做哈希去查缓存。命中就直接返回缓存结果不命中才真实执行。缓存的失效策略很简单按数据类型来定实时性要求高的比如库存设 30 秒日报类数据设 5 分钟不变性数据直接设 24 小时。这个策略在实测中把整体工具调用量降了 40% 左右响应时间也快了很多。但有一个坑需要注意缓存的 key 必须包含参数的全部约束条件。比如查询区域编码区域 A 和区域 B 的结果完全不一样如果 key 里漏了区域这个维度缓存就会串数据。我在代码里做了参数摘要用参数名和值的规范化 JSON 来生成 key确保不会因为顺序不同导致缓存不命中。3.5 异常与兜底Agent 不应该“硬答”Agent 在工具调用失败时最容易出的问题是模型为了“完成任务”会基于不充分的信息编一个答案。比如查订单接口超时了它可能会说“订单正在处理中请稍后查询”——这个答案看起来合理但完全是编的用户真的就会一直等下去。所以我在工具调用层做了一个硬性规定当工具调用失败时不允许模型直接生成解释性回答必须返回一个标准化的错误响应格式是{status: failed, error_code: TOOL_TIMEOUT, message: 订单查询服务响应超时}。模型拿到这个响应后只能原样向用户转达错误信息并提出重试或转人工的选项。另外我给每个工具设了重试策略网络类错误重试最多 2 次每次都加指数退避参数校验类错误不重试直接让模型根据错误信息向用户追问参数。判断依据很简单——参数错误是模型或用户的问题重试多少次都没用只会浪费时间和 token。4. 实操过程从零搭建 Agent-Reach 核心链路4.1 环境准备和基础选型Agent-Reach 的核心链路我用了 Python 3.11 FastAPI 做网关服务模型侧适配了 OpenAI 和本地部署的 Qwen 两套后端。选 FastAPI 主要是因为异步支持好Agent 调用工具时经常会碰到几个工具可以并行调用的场景异步能让整体时延降下来。向量检索部分用了 lightweight 的嵌入式方案跑在内存里因为当前意图分类其实用不到大规模的向量库。我会在下一节详细说意图分类的实现方式。时序数据存放用 SQLite 就够了Agent-Reach 的日志量还没有大到需要专门上时序数据库的程度SQLite 的轻量特性反而让我排查问题时更方便。核心依赖很少fastapi、uvicorn、pydantic、openai、sqlite3 标准库、httpx。不需要引入庞大的编排框架自己写一个轻量的调度模块比硬迁到现成框架要灵活得多。4.2 关键模块意图路由怎么实现意图路由是 Agent-Reach 的“交通枢纽”。用户输入进来之后先不直接进大模型而是先过一层轻量分类器。我用的是 embedding 相似度匹配的方案先把所有已定义的意图做 embedding 并存在内存列表里收到用户输入时也对输入做 embedding然后计算输入和每个意图向量的余弦相似度取 top-1如果相似度低于阈值我设的是 0.72说明没有匹配到合适意图走兜底路由把问题直接交给大模型自由发挥。这套方案的优点是快、可控、省钱。它不需要每次请求都调大模型 API 来理解意图本地算完相似度就直接路由了。实测在四核 CPU 的机器上单次意图分类平均耗时可以控制在 30ms 以内。相似度阈值的调整可以直接影响系统行为这个参数要根据自己的意图列表规模做调优意图太少就降阈值以免过度拒识意图太多就升阈值以免歧义。意图匹配完成之后如果还需要参数抽取我再调一次小模型让模型从用户输入里提取实体的 JSON。比如“帮我查一下华东区上个月的退货率”模型需要抽取出{region: 华东, month: 2025-02}这样的参数。这一步用的是带 function calling 的模型返回结构可以直接校验比正则解析要可靠得多。4.3 核心链路一次完整调用的执行过程我把核心链路拆成九个阶段用一个统一请求 ID 串起来方便事后排查网关接收请求生成 trace_id记录请求摘要。意图路由模块计算相似度确定脑图所属意图。上下文组装拉取会话状态快照拼上本轮输入。参数抽取调用模型从输入中抽参数用 function calling 约束输出结构。参数校验 缓存查询先看缓存命中直接跳到第 8 步。工具调度执行可能需要调用一个或多个工具并行请求。结果标准化接收工具返回统一格式写状态快照。模型生成最终回复模型把工具结果整理成自然语言或表单。响应返回 异步日志落库 更新缓存。每个阶段都有独立的超时控制和重试逻辑。第 6 步的超时我设的是 10 秒超过就终止工具调用并抛错误第 8 步的模型生成超时设 30 秒。整条链路的最长容忍时间是 45 秒超过就返回“查询超时请稍后重试”。这里有一个经验值得强调第 5 步和第 6 步之间的“参数预校验”特别重要。很多 Agent 工程的失败不是模型不行而是模型抽出来的参数根本调不通接口。我在工具适配器里维护了一份规范化的参数检查清单比如“订单 ID 必须是 12 位字母数字组合”“区域编码必须存在于配置表”这样在调用真实接口之前就能拦住一大半无效请求节省了接口侧的压力。4.4 模型参数与 Prompt 模板的取舍Agent-Reach 的模型参数我调了很久最后定下来的组合是temperature0.2、top_p0.7、max_tokens2000。这个组合在“遵循工具调用约束”和“表达自然”之间找到了平衡。太高的 temperature 会让模型“创造性”地绕过工具约束这不是我们想要的。系统提示词模板的写法也很关键。我不会让模型“自由扮演一个智能助手”而是给它一张简化版的“工作说明书”你是业务系统的一个能力执行层只能通过工具完成用户请求。当用户请求涉及工具调用时你必须严格按照工具定义执行。当工具返回错误时直接向用户反馈错误说明不允许自行猜测原因。当信息不足时向用户追问缺失参数不要凭空假设。这段提示词每个字都算过——它实际上是在给模型设定“行为边界”而不是“角色个性”。实测下来这个模板比那种长篇大论的角色设定有效得多模型的工具调用成功率提升了十几个百分点。5. 性能与稳定性让 Agent 真正扛得住业务压力5.1 超时与熔断机制Agent-Reach 触达的外部系统越多整个链路的稳定性风险就越大。一个核心思想是不要让 Agent 的响应时间被最慢的那个工具绑架。我在网关层做了熔断器每个工具维度维护一个滑动窗口统计过去 60 秒内的失败率和平均耗时。当失败率超过 30% 或平均耗时超过 5 秒时熔断器打开后续请求直接走降级逻辑不再尝试真实调用。降级逻辑很有讲究不是简单的“报错”而是给用户一个可接受的折中方案。比如查询订单超时降级逻辑会返回“当前订单系统繁忙您可以查看预约配送时间或联系人工客服”同时触发一条异步任务过一会儿把结果推送给用户。这种模式叫“延迟交付”在业务上比直接失败要友好得多。我在本地用 Locust 做过一次模拟压测场景是模拟 100 个并发用户同时查订单后端设置了两个工具一个接口回应延迟 200ms另一个则在 15% 的概率下随机超时。开了熔断之后整体 p95 耗时从 6.8 秒降到了 2.3 秒因为熔断器识别出超时工具后把请求快速转到了降级路径没有让用户在等待中浪费时间。5.2 成本控制token 预算怎么管Agent 触达范围扩大后token 消耗是很多人忽略的成本黑洞。我按功能线做了 token 预算意图分类走 embedding不计入大模型 token参数抽取用小模型单次消耗控制在 300 token 以内最终回复生成才是大模型这部分预算最高单次控制在 1500 token 以内。还有一个很实用的机制每个会话每天设置 token 上限。当某用户触达上限后优先复用缓存结果工具调用全部走降级核心 Agent 能力保持可用但响应体验降级。这个方法帮我成功避免了好几次“预算爆炸”的问题。5.3 可观测性给自己留一条“后悔药”通道我做 Agent-Reach 时最深刻的体会就是Agent 系统必须要能看到“模型到底是怎么想的”。如果没有过程记录模型给出错误结果时你完全没法排查——是意图分类错了、参数抽错了、还是工具崩了所以在链路里的九个阶段每个阶段都会写一条结构化日志阶段名耗时输入摘要输出摘要是否有异常排查问题时我只需要按 trace_id 聚合日志就能还原一次请求的完整生命周期。这个设计让调试效率提升了不止一个量级。6. 多 Agent 协作从单体走向能力协同6.1 协作编排模式谁说了算Agent-Reach 发展到后期必然面临多 Agent 协作的问题。单体 Agent 的能力边界再宽也有限但多个擅长不同领域的 Agent 组合起来的威力是指数级的。协作模式上我试过两种主流方案第一种是“调度员模式”。一个中心 Agent 负责拆解任务分发给技能各异的子 Agent。这种模式的优点是职责清晰、容易监控缺点是中心 Agent 容易成为瓶颈而且分发的质量完全取决于它是否真正理解每个子 Agent 的能力。第二种是“平等协商模式”。每个 Agent 都有自己的能力描述信息需要别的 Agent 帮忙时直接按能力描述去调用对方的能力接口。这种模式更灵活但如果没有约束很快会出现循环依赖——A 找 BB 找 CC 又回来找 A最后死循环。我实际采用的是混合模式大部分场景走调度员模式由中心 Agent 负责任务编排一些高确定性、低风险的简单任务允许 Agent 间直接调用。核心判断标准是“任务可预测性”——越可预测越允许自治越模糊越需要中心调度。6.2 冲突处理与死锁规避多 Agent 协作最怕的就是互等和冲突。我做了两个机制来规避令牌机制每个 Agent 同一时间只能持有一个“协作令牌”如果你在等待别的 Agent 的响应你不能再发起新的协作请求。这个机制虽然简单但直接消除了多 Agent 互相发起请求造成的混乱状态。仲裁超时一个 Agent 等另一个 Agent默认超时 15 秒。超时后必须放弃等待将问题上报中心调度员。中心调度员可以决定重试、暂缓或者走人工渠道。这个机制专门对付那种“互相以为对方会处理”的典型 Agent 死锁场景。6.3 多 Agent 场景下的“固有好处”能力涌现与故障隔离多 Agent 协作的额外收益是我一开始完全没想到的。把复杂任务拆给多个 Agent 后单个 Agent 的上下文长度压力大幅降低每个 Agent 只需要关注自己领域的细节生成质量反而提升了。同时某类 Agent 的故障会局限于它自己的领域不会波及整个系统。比如商品搜索 Agent 出了问题订单查询 Agent 照样正常服务——这在单体 Agent 时代是不可想象的。但这不等于说多 Agent 系统更稳定。实际上编排层故障的概率比我预想的高尤其是意图分发错误商品搜索 Agent 收到了一个订单查询的意图它可能会自作聪明地给出一个错误答案。所以我给每个 Agent 加了一层“意图自检”收到任务时先检查是否在自己的能力范围内不在直接退回并附上原因。这个做法避免了大量“答非所问”的协作失败。7. 常见问题与排查技巧实录7.1 常见问题速查表实际操作中遇到的典型问题整理成一张速查表方便大家排查现象可能原因排查手段模型调用了错误的工具工具描述含糊、语义重叠检查工具描述是否包含具体场景为描述添加边界说明模型明明拿到了工具结果却不用工具结果格式混乱、字段名陌生检查结果标准化逻辑确认字段命名是否与模型训练语料匹配同一问题反复查数据库缓存未命中检查缓存 key 生成逻辑确认参数是否完整参与哈希Agent 卡在等待另一个 Agent协作超时设置过长缩小仲裁超时窗口增加调度员强制回收机制系统 token 预算飞快耗尽没有设置模型层 token 上限给每个模型请求设置明确的 max_tokens 参数意图路由老是拒识相似度阈值偏高降低相似度阈值或增加“模糊意图”的兜底分支工具调用总是重试参数校验被跳过检查工具适配器是否执行参数预校验查看错误响应码7.2 排查技巧从一瓶“面”到一条“链”排查 Agent 问题时最容易踩的坑就是只看最终回复。模型输出一个错误的自然语言答案你盯着它看半天也不知道错在哪。我的一般流程是第一步查 trace_id还原完整链路日志确定哪个阶段耗时长、哪个阶段报错。第二步检查意图路由结果和参数抽取结果看模型的理解是否正确。第三步检查工具返回的原始数据确认是不是接口侧问题。第四步如果前几步都正常但最终回复仍然不对大概率是模型生成阶段的指令遵循问题。这时候我会微调 prompt 模板而不是盲目调参数。这个“从面到链”的排查顺序帮我处理了几十起线上问题没有一次被带偏过。7.3 案例实录一次意图误判的完整复盘我挑一个最典型的现场来讲。用户问“为什么华东区上个月的订单量环比降了 10%”系统最终回答的是“华东区订单量环比下降了 9.8%建议您检查物流运力配置。”这个回答本身没错但用户真正想要的是“原因分析”而不是“数字确认”。复盘后发现意图分类器把这个请求判成了“查询订单量”而它实际应该属于“经营归因分析”后者会触发另一个 Agent 去关联物流、库存、营销三个数据源做归因。为什么分类错了因为我的“经营归因分析”意图描述里没有覆盖“为什么”“环比下降”这种因果类问法。处理方案是修改意图描述加入“当用户询问指标变化原因、影响因素、深层背景时使用经营归因分析”。改完之后同类请求的准确分类率从 62% 提升到了 89%。这件事给我一个很深的教训意图描述要写“触发词”而不是只写“功能名”。功能名帮不了模型做选择触发场景才能。8. 安全与合规Agent 触达力越强防线越要前置8.1 权限的最小化原则Agent 触达的系统越多权限爆炸的风险越大。我的原则是“触发时授权、用完即回收”。具体来说Agent 要调用某个工具的权限必须先申请权限由一个策略引擎统一管理策略定义用时间窗口、调用次数上限、调用方身份来约束。比如订单导出工具普通用户权限只允许导出 1000 条以内数据且每天最多调用 5 次管理员权限放宽到 5 万条、50 次。这个策略设计值得单独说。我没用传统的静态角色表而是做成了动态策略——每次调用前实时计算“是否允许”。好处是改策略即时生效不需要发布新版本坏处是策略引擎本身需要非常稳定否则会影响线上链路。我额外给策略引擎加了热备和降级开关如果策略引擎不可用默认拒绝高风险工具、放行低风险工具。8.2 上下文隔离Agent 不该知道它不该知道的多用户共用一个 Agent 系统时最大的安全隐患是上下文串数据。某个用户的对话轮次里模型可能会收到另一个用户的缓存结果这在无状态设计里尤其容易发生。我在会话层和缓存层都加了租户隔离会话 ID 绑定租户 ID缓存 key 的生成也必须包含租户 ID。所有工具调用请求都必须携带租户上下文适配器层强制校验。这个设计让我在后续接入多个业务方时省去了大量返工。8.3 透明化与降级预案合规层面还有一个经常被忽略的点用户应该知道自己正在和一个 Agent 系统交互。Agent-Reach 的前端交互里凡是 Agent 自动生成的内容都会明确标注“由智能助手生成”涉及工具调用的数据结果也会标注数据来源和时间。这个做法既是对用户的尊重也能减少业务方的合规风险。降级预案也值得一提。Agent 系统必然会有依赖大模型 API 的时候一旦 API 不可用整个链路就可能瘫痪。我做了两级降级第一级是自动降级模型 API 挂了就走规则引擎用关键词匹配直接打工具能保底完成简单查询第二级是人工接管把用户的请求转入人工客服队列。这种“模型断了业务不断”的设计在两次线上事故里帮我保住了关键路径。9. 关于 Agent-Reach 扩展方向的三点思考做完了 Agent-Reach 这套基础框架后我陆续在思考几个后续扩展方向分享给正在做类似项目的朋友参考。第一个方向是自适应能力发现。现在的工具接入还是靠人工维护描述和适配器我计划让系统支持半自动化的工具发现当引入一个新的 API 文档时自动生成能力的初版描述再由人工校准。这是把“翻译接口给模型”这件事部分自动化能大幅降低接入新系统的人力成本。第二个方向是记忆分层。当前的会话状态快照本质上是一种短期记忆但 Agent 的触达能力越强越应该沉淀长期记忆——比如用户的操作偏好、业务的常见归因模式、甚至历史工具的调用习惯。我打算做一个两层记忆架构短期快照服务当前会话长期记忆用于跨会话的个性化策略。第三个方向是更细粒度的可观测性。目前的日志能定位“哪个阶段有问题”但还做不到“为什么模型在那个阶段做了那个决定”。接下来的计划是在每个工具调用的关键决策点引入概率标注让模型输出其决策依据。这更像一个实验性功能但它对排除复杂问题会很有价值。如果你正在构建自己的 Agent 系统我建议你优先把本文里的“能力网关化”和“意图分类”两件事落地。它们看似基础却是后续一切扩展的地基。其他的“协作、缓存、熔断、安全治理”可以说都是在这两层之上生长出来的能力。地基打得稳Agent 的触达力才能真正变成业务价值而不是变成系统复杂度。