很多人以为 Agent 项目最难的是模型选型我做了 Agent-Reach 这个项目以后才明白真正卡住落地的是“触达”——让 Agent 真正够得着工具、数据、系统并在安全可控的范围内完成动作。这是个围绕智能体触达能力设计的工程实践项目主要解决 Agent 从“会聊天”到“会干活”的过程中工具接入混乱、权限失控、调用不可观测、上下文被撑爆这一类问题。适合正在做 Agent 落地的工程师、技术负责人以及被工具调用链路折腾过的人。Agent 在这里指 AI Agent也就是智能体Reach 是触达半径的意思。我希望通过这套设计把 Agent 的行动边界做得既宽又稳宽到能覆盖业务系统稳到每次触达都有授权、有记录、有兜底。1. 为什么要做 Agent-Reach1.1 从“会聊天”到“会干活”的最后一公里大模型真的很能聊但你让它“帮我从销售系统导一下昨天的数据按区域汇总后发到群里”它大概率只能给你一段 SQL 或者一份操作说明而不是真的把数据拉出来。原因是模型本身不连接业务系统它没有工号没有门禁卡不知道你的报表服务地址是什么。我见过太多团队把 Agent 做成“带工具的高级聊天框”接了 Function Calling注册了十几个函数demo 时看起来很惊艳一上生产就翻车。为什么因为工具调用不是简单地给模型加几个函数。模型要完成一次真实任务至少要走通这条链路理解用户请求、找到可用工具、填对参数、通过权限校验、调用真实接口、处理返回结果、把结果转成用户能理解的回答。每一环都是一个触点任何一个触点断了整个任务就废了。Agent-Reach 这个项目要解决的正是这条链路的工程化问题。不碰模型训练不碰业务流程改造只做连接这一层。你可以理解为模型是大脑Reach 是手脚和感官。没有手脚的 Agent再聪明也只能停留在建议阶段。1.2 现有方案为什么不够用市面上常见的做法有几类我都试过各有各的坑。直接用 Function Calling 接工具最省事但工具数量一多模型就开始糊涂。你塞给它 30 个函数定义它经常挑错、漏参甚至编造一个不存在的函数名。RAG 能解决“知识触达”让 Agent 能引用文档内容但它解决不了“动作触达”——查完文档之后还是要调接口、点按钮、发消息这一步 RAG 帮不上忙。RPA 能模拟人工操作但它本质是固定流程的自动化缺一个“根据上下文灵活决策”的前端。Agent-Reach 的思路是把触达能力本身当成一个独立工程域来做而不是散落在 prompt 和业务代码里的边角料。具体来说Agent-Reach 做了四层设计接入层负责对接模型和用户入口触达层维护一套统一工具协议路由层决定“这次任务该用哪些工具”治理层管权限、审计、熔断和可观测。每一层各管一摊互不越界。1.3 我给这个项目定的目标和边界动手之前我先定了三个原则后面所有设计都是围绕这三条展开的。第一模型做主。具体选择哪个工具、怎么组织参数交给模型决策不硬编码业务流程。第二框架做边界。工具注册、协议校验、权限强制检查都在框架层完成不能依赖模型自觉。第三平台做审计。每一次触达行为都要留痕能回放、能复盘、能追溯。这三条看起来简单但越往后做越发现边界感是 Agent 工程化最容易出问题的地方。另外我也划了清晰的边界不训练微调模型不改造现有业务系统的内部逻辑不替代现有权限系统。Agent-Reach 的目标是当一个合格的“连接总线”而不是什么都往里装。2. 整体设计与核心机制2.1 “工牌、门禁、监控”三层设计我给 Agent-Reach 定下的架构你可以想象成一个园区。模型是员工业务系统是园区里的一间间办公室Agent-Reach 负责发工牌、设门禁、装监控。工牌对应工具注册中心。每个工具进来的时候都要登记登记内容包括工具名称、功能描述、参数 Schema、所需权限、超时时间、执行方式。没有工牌的工具模型再想用也调不动。门禁对应当路由与权限服务。模型提交“我想用哪个工具、带什么参数”之后门禁先查权限再查参数合法性最后才放行。这个顺序不能乱。监控对应当审计与追踪服务负责记录每一次触达的完整上下文包括模型决策依据、执行耗时、返回结果、错误信息。这套架构最大的好处是模型、工具、权限三者解耦。模型只管“决定做什么”至于“能不能做、做了会有什么影响”由 Reach 层来判断。这样即使换了模型工具侧完全不用动。2.2 触达的四种类型在实际项目里Agent 需要触达的目标五花八门。我把它们归成四类分别对应不同的风险等级和权限策略。触达类型典型动作风险级别权限策略读操作查销售数据、检索订单、拉取报表低L1 只读授权写操作发通知、创建工单、修改配置中L2 写操作授权流程操作启动审批流、调用 RPA 执行脚本高L3 高危授权 人工确认协同操作把任务转给另一个 Agent 或人工处理中L2 授权 明确交接记录分类看起来简单但直接影响后面的权限模型设计。比如读操作可以走自动授权写操作要看数据影响范围流程操作最好加一道人工确认。这个分类不是拍脑袋定的而是根据“一次错误触达造成的最大损失”来划分的。2.3 为什么用“语义路由 候选精排”而不是全靠模型最早的版本我把所有工具描述直接塞进 system prompt让模型自由选择。工具在 15 个以内时效果还行超过 20 个就开始翻车。后来我把工具描述换成 OpenAPI 格式精简版情况好一点但模型仍然会在冷门工具上产生幻觉甚至出现“明明该用 A 工具却因为 A 描述排在后面选了 B”的情况。Agent-Reach 最终采用的是“两步走”路由第一步用语义检索召回候选工具把几十个工具缩小到五六个第二步把候选工具的描述交给模型由模型精排决定最终使用哪个、参数是什么。这个过程像查地图先通过语义缩小范围再在局部做精细导航。关于候选数量 top_k 怎么定我做过一组对比实验。top_k 取 3 的时候召回率明显偏低经常漏掉正确工具取 8 或 10准确率几乎没有提升但 prompt 长度增加了约 40%模型决策延迟多了 300 毫秒左右。最后定在 6兼顾准确率和响应速度。相似度阈值则不是拍脑袋定的我拿 300 条真实用户语句跑了一遍统计“正确工具”的相似度分布取 P25 分位的值作为默认阈值大概是 0.3低于这个值的召回结果宁可不要也不能误导模型。2.4 权限模型最小权限、按需授权、动态回收权限是 Agent 项目里最不能省的一环。我在 Agent-Reach 里做了三级权限L1 只读L2 写操作L3 高危操作。每个工具注册时绑定所需级别执行器调用前强制校验。L3 操作必须走二次确认。比如 Agent 打算执行“批量删除过期订单”系统会先把参数回显给用户用户确认后才真正执行。这个确认不能做成 prompt 里的“你确定吗”因为模型可能替用户回答“确定”。正确做法是中断执行流把控制权交还给前端等用户在界面上点了确认按钮再继续。动态回收也值得提一嘴。有些工具授权是一次性的有些是会话级的。如果是“查询今日库存”这种低风险工具会话内第一次授权后后续可以直接放行但“修改价格”这种操作每次都要重新校验即使同一会话内也一样。这个策略我在权限服务里做了可配置项按工具粒度控制。3. 触达层协议与核心代码实现3.1 工具描述协议让模型看得懂、填得对我建议工具描述统一用 JSON Schema主要原因是模型对结构化描述的理解能力远好于自然语言而且 OpenAPI 生态可以直接复用。一个查询销售数据的工具描述长这样name: query_sales_data description: 查询指定时间范围的销售数据按区域汇总。适合“销量怎么样”“营收多少”这类需求。 parameters: type: object properties: start_date: type: string description: 开始日期格式 YYYY-MM-DD end_date: type: string description: 结束日期格式 YYYY-MM-DD region: type: string enum: [华东, 华南, 华北, 西南] description: 区域名称不传则全部区域 required: [start_date, end_date]这里有个很容易忽视的细节description 字段不要只写“查询销售数据”要写清楚“什么时候该用这个工具、什么时候不该用”。比如这个工具的描述里加了“适合‘销量怎么样营收多少’这类需求”模型在做语义匹配时就有了锚点。我对比过加了使用场景描述之后工具选择准确率提升了大概 12 个百分点。3.2 工具注册中心基础数据结构与检索注册中心是 Agent-Reach 的核心。所有工具进来先注册注册完自动建索引。索引的目的是给语义检索用轻量方案直接用 FAISS工具量在几百个以内完全够用没必要一上来就上向量数据库。# tool_registry.py from dataclasses import dataclass, field from typing import Optional dataclass class ToolSpec: name: str description: str parameters: dict permission_level: int executor: str timeout_ms: int 5000 need_confirm: bool False class ToolRegistry: def __init__(self, embedder): self._tools: dict[str, ToolSpec] {} self._embeddings {} self._embedder embedder def register(self, tool: ToolSpec): self._tools[tool.name] tool self._embeddings[tool.name] self._embedder.embed(tool.description) def retrieve(self, query: str, top_k: int 6) - list[ToolSpec]: query_vec self._embedder.embed(query) scored [] for name, vec in self._embeddings.items(): score cosine_similarity(query_vec, vec) scored.append((score, name)) scored.sort(reverseTrue) return [self._tools[name] for _, name in scored[:top_k]]retrieve 返回的是候选列表不是最终决定。最终决定交给模型去做注册中心只负责缩小范围。这一步很重要因为注册中心不该有“决策”逻辑它一旦介入决策就又把业务逻辑耦合进来了。3.3 语义路由 精排决策路由决策服务是整个项目里改动最频繁的模块。它做的事分三步召回候选工具、构建候选工具提示、让模型输出结构化决策。async def route(user_request: str, session_id: str) - ToolDecision: candidates registry.retrieve(user_request, top_k6) schemas [c.to_json_schema() for c in candidates] messages [ {role: system, content: 你是工具调度助手。根据用户请求从候选工具中选择一个最合适的工具并给出参数。如果候选工具都不合适返回 tool_namenull。只使用提供的工具不要虚构工具名。}, {role: user, content: f用户请求{user_request}\n候选工具{json.dumps(schemas, ensure_asciiFalse)}} ] resp await llm.chat(messages, response_format{type: json_object}) decision json.loads(resp) return ToolDecision(**decision)这里有一个我踩过坑的地方如果没有“tool_name 可以为 null”这个约束模型在候选工具全不合适时也会强行挑一个最接近的导致错误触达。加上之后模型更愿意“承认自己找不到合适的工具”这时系统会走兜底对话流程而不是硬调。3.4 执行器统一抽象参数校验、结果化简、错误标准化工具真正执行时不能直接让模型去调 HTTP 接口。中间要加一层执行器统一处理参数校验、权限检查、超时控制、结果化简和错误标准化。class BaseExecutor: def __init__(self, registry, permission_service): self.registry registry self.permission_service permission_service async def execute(self, tool_name: str, params: dict, user_ctx: UserContext): spec self.registry.get(tool_name) self.permission_service.enforce(user_ctx, spec) validate(spec.parameters, params) raw await self._call(spec, params) return self._simplify(raw)单个方法挺好理解大部分团队都会写。关键在于结果化简这一步直接决定 Agent 后续对话的质量。工具返回的原始结果可能是很大的 JSON比如一次销售报表查询能返回 800KB 数据。模型上下文窗口是有限的把原始 JSON 塞进上下文轻则浪费 token重则直接触发窗口溢出。执行器应该把原始结果先做摘要只把“模型需要知道”的部分放进上下文。我通常的做法是保留三个部分核心结论、关键明细、原始数据的查询入口。比如销售数据查询化简后就留下总营收、Top 区域列表、明细报表的下载链接。模型拿这些信息足以回答用户用户想深入看明细再走一次检索式工具拉取。4. 权限、审计与可观测4.1 权限校验绝不能只写在 prompt 里这是 Agent 项目最容易踩的坑而且是致命的坑。很多人做演示版时把“只有管理员才能删除数据”这句话写进 system prompt看起来没问题但生产环境里这根本挡不住。原因有两点。第一prompt 本身可以被对话内容污染用户可以通过一系列话术让模型忽略之前的规则这在业界已经有大量案例。第二即便模型遵守了规则也无法防止模型在工具参数上传入越权数据比如传了不属于当前用户权限范围的订单 ID。权限判断必须落在代码层在工具调用真正发生之前强制执行。def enforce_permission(user, tool_name, params): spec registry.get(tool_name) required spec.permission_level allowed permission_service.check(user.uid, required, params) if not allowed: raise PermissionDenied( f当前账号缺少权限{required}需要联系管理员开通 )任何绕过权限服务直接执行工具的做法都应该被视为 bug。我在项目里加了一个强制约束所有 Executor 必须继承 BaseExecutor权限检查在父类里完成子类无法跳过。4.2 全链路追踪每次触达都要留痕Agent 出问题不可怕可怕的是出了问题不知道是哪一环导致的。Agent-Reach 从第一版开始就要求全链路追踪。每条会话有一个 session_id每次工具调用生成一个 request_id所有日志都要带上这两个 ID再配合时间戳和 trace_id形成一次触达事件的完整脉络。我用 OpenTelemetry 做底层的 trace 管理同时在应用层额外落一份结构化 JSON 日志方便直接用日志检索排障。日志字段大致是这样def log_reach(session_id, request_id, tool_name, params, status, latency_ms, model_decision): logger.info(json.dumps({ event: agent_reach, session_id: session_id, request_id: request_id, tool: tool_name, params: sanitize(params), status: status, latency_ms: latency_ms, model_decision: model_decision }, ensure_asciiFalse))日志里必须要脱敏。params 里的手机号、身份证、token 等敏感字段在写入日志前要做掩码处理否则审计系统本身就变成了一个数据泄露出口。4.3 审计回放出问题时能还原现场全链路追踪解决了“知道发生了”审计回放解决的是“知道为什么发生”。除了请求日志之外Agent-Reach 还会记录每一个关键决策节点的上下文快照包括系统提示词、候选工具列表、模型原始输出、最终执行参数。有一次生产事故让我印象很深用户投诉 Agent 误发了一封全员邮件。通过审计回放发现模型决策层选择了 send_notification 工具参数里的收件人分组被模型填成了“all_members”而实际上用户只提到了“通知一下项目群”。根因是工具描述里没有说清楚收件人分组字段应该从通讯录服务获取而不是让模型自由填。后来我在工具描述里加了一条约束“recipients_group 必须调用通讯录服务解析禁止模型自行推断”问题就消失了。复盘时我们把日志分成了三个分析层次排障效率提高了不少分析层次观察内容典型结论模型决策层用户输入、模型输出的 tool_name 与参数模型选错了工具 / 参数理解有偏差框架校验层权限校验结果、参数校验结果、拦截原因权限配置不当 / 参数 Schema 定义不全执行层外部系统响应状态、耗时、返回数据上游系统超时 / 返回结构变化导致解析失败这个三层日志体系也是每个新同事上手排障时的第一份参考资料比哪份文档都管用。5. 实操中的典型问题与排查技巧5.1 工具数量膨胀导致决策漂移项目上线两个月后注册工具从 12 个涨到了 47 个模型开始频繁选错工具。症状挺迷惑的单看每一次决策都像模像样但整体准确率掉了快 15 个百分点。排查后定位到两个原因。一是工具描述同质化比如“查询订单”“查询退款”“查询售后单”这三个工具的描述都包含“查询”“订单”这类词语义向量距离很近召回阶段经常混在一起。二是模型精排阶段一次要看的候选变多了注意力分散。解决办法有两个。第一个是增加“业务域路由”先按域分组比如交易域、库存域、营销域语义路由先定域再在域内召回工具这样每次实际送入模型的工具不会超过 4 个。第二个是合并同类工具把“查询订单”“查询退款”“查询售后单”合并成一个“查询交易数据”的能力入口由执行器根据参数内部再路由。两招组合下来准确率不仅恢复了还比早期版本高了一截。5.2 工具调用超时会话挂起外部系统响应慢Agent 干等用户端看起来就是“卡死了”。这个问题第一版就出现了。报表系统偶尔要跑十几秒Agent 又设置了 60 秒超时结果就是用户对着对话框干瞪眼。后来我按触达类型分别设了超时读操作默认 5 秒写操作默认 10 秒流程类操作 30 秒全部可配置。更关键的是超时后的处理逻辑。超时不能简单地给模型返回“调用失败”模型收到失败后会尝试重试连续几次失败又触发新的超时体验更糟。现在超时后返回一段结构化信息比如“系统响应超时建议先让用户确认数据是否需要实时获取或者主动降级为缓存数据”。写操作超时的处理是最麻烦的因为请求可能已经发出去了只是响应没回来。这种情况我会把状态标记为“执行结果未知”不会直接告诉用户“失败”而是提示“命令已发出确认结果需要等待”。这个细节虽然小但在金融对账场景里能避免很大的麻烦。5.3 权限校验被串联调用绕过有个测试场景让我警觉了用户让 Agent“先查一下订单详情然后把订单状态改为已取消”。Agent 先调用了查询工具又调用了取消工具。查询工具的权限是 L1取消工具的权限是 L3按设计应该触发二次确认但测试中发现如果前一个工具调用刚刚成功第二个工具可能被某些实现绕过校验。根因是我第一版把“会话内已通过更高权限”错误地缓存了。修复方案每个工具独立校验L3 操作每次都要校验并强制二次确认不设置会话级缓存。高危操作连参数里的“订单号”范围也要校验防止模型把用户 A 的订单取消指令作用到用户 B 的订单上。权限校验最安全的策略就是宁可每次多查一次也不要在边缘场景留下一个口子。5.4 上下文被工具返回结果塞满这个坑几乎每个 Agent 项目都会遇到。有一次用户让 Agent 汇总上个月所有渠道的广告投放数据工具返回了一个 2MB 的 JSON直接塞进了上下文后面的对话质量立刻崩了。模型的注意力被海量原始数据稀释连用户最初的意图都快忘了。解决链路有三层。第一层是在执行器里做结果摘要只保留结论和关键指标细节进仓库。第二层是上下文管理加滑动窗口旧消息逐步压缩只保留摘要和决策链。第三层是给用户提供“继续追问”的入口用户想看明细时Agent 通过专门的检索工具按需拉取而不是一次性把全部数据加载进上下文。打个比方项目里的上下文机制就像人处理信息的方式——记住结论细节放在笔记本里需要再翻。这个方向也是 Agent 项目从 demo 走向生产的必经之路。5.5 模型编造工具名生产环境里出现过一次“工具不存在”的调用模型输出一个 tool_name但注册中心里根本没有这个工具。发生这种情况的原因是模型在候选工具都不匹配时强行编造了一个“看起来合理”的工具名。这跟大模型的幻觉机制有关被追问时它会倾向于给一个答案而不是承认自己不知道。处理办法是三层防御。首先注册中心在收到未知工具名时返回“未注册工具”并附带当前可用工具的候选列表其次路由决策阶段允许 tool_name 为 null不给模型“硬选”的机会最后把错误信息原样返回给模型让它基于真实反馈做自我纠正。实测下来加上这套机制之后模型编造工具名的次数从大约每 20 次出现 1 次降到了几乎为零。6. 踩坑之后留下的体会Agent-Reach 做到现在我最深的体会是Agent 项目的复杂度和工具数量不是线性关系而是指数关系。工具 10 个以内怎么设计都顺到 30 个以上协议、权限、路由、可观测全部得重新审视一遍。如果你是刚开始做类似项目我强烈建议不要一上来就上微服务、消息队列、向量数据库全家桶。第一版就用单进程把注册中心、路由、执行器、日志串起来先把链路跑通把工具协议定好再逐步拆模块。工具协议这件事越早定越好它像 API 规范后面改起来成本极高。还有一点是关于 prompt 的。工程项目里不要指望一条写得很完美的 prompt 解决所有问题更不要指望模型“自觉遵守规则”。规则类约束一定要落进代码prompt 只负责表达意图不负责执行安全。每次做 Agent 排障我会先问三个问题这个动作模型有能力做吗框架允许它做吗做了之后能追踪到吗三个问题都是肯定回答系统才算是真正可控。如果以后扩展我会把 Agent-Reach 往多 Agent 协作的方向推。当一个 Agent 的能力不够用时它需要把任务交给另一个 Agent这套触达协议同样可以当作 Agent 之间的协作总线。另外把工具调用结果加上统计反馈持续优化语义路由的召回效果这个方向也值得深耕。模型决定 Agent 能想到什么触达层决定 Agent 能做到什么。把触达这件事做扎实Agent 才真正从玩具变成生产力。
