我前阵子接手了一个内部项目代号就叫 Agent-Reach。名字听着挺唬人拆开看其实就俩词Agent 和 Reach。Agent 是智能体Reach 是触达、覆盖。合起来就是一件事——让智能体真正触达业务干成事。说白了现在大模型聊天已经不算新鲜事了真正难的是让 AI 从“会说话”变成“会办事”。Agent-Reach 这个项目要解决的就是这最后一公里让 AI 能调用内部系统、查询业务数据、执行操作流程并且在真实生产环境里稳定跑起来而不是停留在 Demo 层面玩个两三轮就断线。这篇文章我会把这阵子从零搭建 Agent-Reach 的完整过程做个复盘包含架构思路、技术选型、实操步骤、踩坑记录。如果你也在搞智能体落地或者正头疼 AI 怎么跟现有系统打通这篇内容应该能帮你少走不少弯路。我会尽量把关键细节和决策背后的理由讲透让不同基础的读者都能拿去参考。1. 项目整体设计思路拆解1.1 为什么一定要做智能体触达当时立项的时候我们内部已经有一个挺成熟的对话机器人能回答一些常见业务问题比如查个订单状态、看下库存数量之类。但那个机器人本质是“检索式问答”——用户问一句系统从知识库里找出差不多的答案返回。遇到复杂一点的需求比如“帮我统计一下华东区这个月所有逾期订单并且按原因分类列出”它就完全抓瞎。后来我们试过把大模型接进来直接在 Prompt 里堆上下文。第一批测试效果确实惊艳模型什么都能聊但要真让它执行操作——比如把一条订单标记为异常、生成一个业务报表并推送给人——它就只会“讲道理”不会“动手”。模型生成的回答像一篇作文而不是可执行的动作。Agent-Reach 的出发点就在这里把大模型的能力从“文本生成”延伸到“行动执行”。核心是把大模型的推理能力拆解成一条可执行链路——它理解用户意图拆解成任务清单然后通过工具调用的方式去真正操作业务系统最后把结果整理反馈给用户。这看起来像是给 AI 接了几个 API 就能搞定的活实际上牵扯到权限管理、上下文控制、异常恢复、执行监控等一系列问题。Agent-Reach 本质上是一个薄薄的“行动层”夹在大模型与业务系统中间让模型既能指挥又不至于乱来。1.2 架构选型背后的关键权衡早期做方案的时候我们纠结过两条路线。第一条路子比较“野”直接用 LangChain 这类框架把工具全挂上让大模型自主决定怎么调用。好处是上手快一个脚本几百行就能跑通坏处是失控风险高——模型可能按错误顺序调用工具可能传错参数可能在一个已经失败的操作上反复重试。我们在测试阶段就碰到过模型自作主张把“查询库存”和“锁定库存”两个操作串联执行的情况生产上这属于事故级别的问题。第二条路子比较“保守”把能做的操作预先编排成固定流程然后让大模型去匹配哪个流程适用。这样稳定可控但灵活性很弱。业务上稍有点变化就要重新改流程定义模型跟个“选择按钮”差不多谈不上智能。Agent-Reach 最终选择的是中间路线工具是可自由组合的“积木”但模型不能直接搭积木必须经过一层“执行规划器”做任务拆解与动作排序。规划器会先向模型收集足够的上下文信息再根据业务规则校验每一步动作的合法性与依赖关系通过后才允许执行。为了让不同基础的人能直观理解这套架构打个比方——这就像给一个刚拿驾照的司机配了个教练坐在副驾驶上。方向盘和油门是模型在操作但教练负责看路况、决定变道时机、踩刹车。路线规划允许灵活但安全边界一点都不能让。1.3 Agent 的三层能力模型设计过程中我们把 Agent-Reach 拆成了三个能力层级对应不同的业务价值。这个划分后来也被团队用简洁的方式写进了项目文档第一层叫“知晓层”。这一层解决的是信息触达问题——用户问什么Agent 能从知识库、业务系统里找到答案。核心技术上主要靠检索增强生成加上结构化数据查询知识来源包括内部工单库、产品文档、运维手册。成效上咨询类的问题七八成可以自动覆盖不需要人工介入。第二层叫“行动层”。这一层让 Agent 能调操作类工具比如创建工单、更新记录、发起审批。核心是把“自然语言指令”翻译成“系统操作指令”并安全执行。这块占了整个项目接近七成的开发量也是后续文章想重点展开的部分。第三层叫“协同层”。当单个 Agent 完不成任务时可以把它拆给多个子 Agent 协作或者由主 Agent 编排长链路任务过程中持续跟踪进展、对人进行进度反馈。这一层我们只做了初步探索但架构上预留了接口后续要上也不费劲。三层能力听起来简单真正做起来其实是从“能用”到“好用”再到“智能”的三重门。Agent-Reach 目前完整实现了第一层和第二层第三层跑通了一个最小可行版本。这个规划给团队一个很清晰的路标——知道项目在哪、要去哪、还有多远心里不慌。2. 核心环节实现与实操要点2.1 工具调用的标准化封装Agent-Reach 里最基础的功能模块是“工具”。每个工具代表一个可以被大模型感知和调用的外部能力单元。实际项目里工具可能对应一个后端接口、一个数据库查询、一个消息推送动作甚至是一段内部脚本。而工具要能被模型安全地调用就需要一套统一的信息描述结构。我实际使用的工具描述信息包含四大板块工具名称、功能说明、输入参数定义、输出结果说明。先说名字工具名必须一眼能看出它干什么并且全系统唯一。像query_order_status这种大模型一眼就能理解后续排查日志也方便。功能说明要用“这个工具用于……”句式尽量把触发条件和适用范围写清楚模糊的描述会让模型误用。输入参数这块是最关键也最容易出错的。每个参数要定义类型、是否必填、取值范围或枚举值并且提供一两个示例值。模型会参考这些示例来填充参数示例越贴近真实业务参数生成准确率越高。输出说明描述工具的返回值结构例如返回的是订单状态、操作是否成功还是失败原因。为了形象说明这个结构我放一段配置示例这里用 YAML 做示范实际项目里用 JSON Schema 描述效果也一样tools: - name: update_order_status description: 用于更新指定订单的处理状态适用于售后改单、异常标记等操作。 parameters: - name: order_id type: string required: true description: 订单编号形如 ORD20250001 - name: status type: string required: true enum: [pending, processing, completed, cancelled] description: 目标状态只能从枚举值中选择 - name: reason type: string required: false description: 改单原因备注字数不超过200字 output: success: 更新成功的订单号与当前状态 failure: 失败原因如订单不存在或状态不合法这个配置本身不复杂但有一个细节值得注意说明文字里一定要写清楚工具的限制。比如“只能由客服角色调用”“逾期订单不可修改状态”这些业务规则能让大模型在意图阶段就过滤掉不少高风险请求。我自己吃过亏——一开始没写任何限制模型在测试中非常流畅地把一个已完成的订单改成了已取消状态生产上这就是严重事故。2.2 大模型原生函数调用机制的应用既然要和模型对接就绕不开大模型怎么知道该调用哪个工具。现在市面上的主流大模型基本都支持“函数调用”或“工具调用”能力大模型会分析用户的自然语言输入结合可用工具的说明输出一个结构化的调用意图。简单说就是模型“觉得自己该调用工具时”会在回复里携带一段特殊格式的数据而开发者拿到这段数据再转到实际代码去执行。在 Agent-Reach 里我用了主流模型里常见的tools参数把工具配置发给模型推理接口让模型输出符合调用格式的结构from openai import OpenAI client OpenAI(api_keyyour-api-key) tools [ { type: function, function: { name: update_order_status, description: 更新指定订单的处理状态, parameters: { type: object, properties: { order_id: {type: string}, status: {type: string, enum: [pending, processing, completed, cancelled]} }, required: [order_id, status] } } } ] response client.chat.completions.create( modelyour-model-name, messages[ {role: system, content: 你是业务助手根据用户指令选择合适的工具。}, {role: user, content: 把订单 ORD20250001 置为已完成} ], toolstools, tool_choiceauto )这段代码只是最基础的链路真正放生产里还需要叠加一层“工具调用结果回填”。大模型在完成工具调用后会把执行结果作为新的消息内容继续推理然后决定是调用下一个工具还是把最终结果整理成自然语言返回给用户。这个“思考-行动-观察”的循环是整个 Agent-Reach 能连续处理多步任务的核心机制。这块流程对没接触过的朋友可能稍微绕一点但可以记住一个简单的概括模型先“想”再“动”然后看到结果再决定下一步干什么。每一步都是一次请求-响应只不过多带了一份工具调用信息罢了。这串循环能不能稳定跑下去很大程度取决于前面两节说的工具定义清不清楚、上下文有没有管住。2.3 上下文管理窗口里只留有用的第一版做出来以后最常见的故障就是“聊着聊着模型变傻了”。比如用户连续对话多轮前面问过的一些信息会一直挂在上下文中再加上中间工具调用返回的大段 JSON 结果很快就逼近模型上下文窗口上限。一旦窗口满了超出的历史就会被截断通常截掉的还是最关键的最新内容模型就开始答非所问甚至干脆报错。后来我们定了三条取舍原则实测下来很稳第一历史对话只保留最近三到五轮更早的内容总结成一段摘要放进去第二工具调用结果不回填原始全文只提取关键字段并压缩成简洁文本第三模型内部的“思考过程”不允许写进最终上下文只保留最终动作指令防止中间推理内容挤占窗口。def compress_tool_result(result: dict) - str: # 只提取关键字段压缩长度 keys [status, order_id, success, message] compressed {k: result.get(k) for k in keys if k in result} return json.dumps(compressed, ensure_asciiFalse)这个压缩动作看起来很小作用却非常大。有一回线上处理一个长流程的售后改单任务没压缩前上下文消耗了大概 4000 多个 token压缩以后直接降到不到 400模型推理速度和准确性都提升了一大截。做 Agent 项目的朋友真的建议从一开始就把上下文管理当一等公民对待后面跟多轮任务较劲时会省心很多。3. 实操过程与核心流程跑通记录3.1 技术栈选型与实践清单Agent-Reach 在正式写业务代码之前先把技术栈定了下来。这个选型决定花了不少时间我把最终用下来的组合以及选择理由整理在下面方便后面做类似项目的朋友直接参考模型接入层优先使用支持函数调用的主流大模型国内国外模型都试过最终业务场景里选了对中文理解更稳的一个。关键是确认模型厂商的接口是否支持tools参数不支持的老模型可以直接排除。Agent 框架没有重度依赖 LangChain 这类重量级框架而是自研了轻量的执行规划器。原因是业务团队对可控性要求很高框架封装太多反而看不清每一步在干什么。自研一个核心循环控制在几百行代码内后续排查问题极其方便也更容易按我们的安全要求做定制。工具注册与发现每个工具启动时自动注册到一个统一工具中心工具中心提供名称、描述、参数的索引模型每次发起调用前先从这里拉取最新工具列表。做到“工具即插即用”新工具上线不需要改主流程。业务系统对接走标准 REST API 为主少量老系统用数据库直查加只读账号不允许 Agent 直接执行写操作数据库语句。历史上吃过一次数据库直连乱更新的亏以后这个边界执行得非常严格。权限模型每个工具绑定一个角色标签用户在会话开始时获得角色身份Agent 只能调用该角色权限范围内的工具。用户在上下文里拥有的操作边界不会因为提问方式绕过去。技术栈定下来以后实际开发的节奏比预想顺利很多。主要是前期把工具描述和权限模型这些模棱两可的地方抠清楚了后面写代码反而很快大部分时间都花在面对新边界场景设计防御策略上。这也印证了一件事AI 项目的复杂度往往不在模型能力而在模型与真实世界交互时那些边界情况的处理。3.2 第一个工具从零到上线的完整过程我们拿“工单状态更新”这个场景作为第一个打通闭环的实验对象。这个场景选得很有代表性——它涉及只读查询和写操作两类工具要加入权限校验产出结果也能直观看到非常适合验证链路是否通。第一步是配置工具描述。我把更新工单状态的工具写成了符合模型调用格式的参数定义枚举值提前和业务方确认好。实际上光是整理那些状态枚举值就花了一个下午——因为业务方自己都没想清楚“处理中”和“进行中”到底是不是一个意思这类业务口径问题提前对齐后面测试才不会莫名其妙飘红。第二步是写工具执行函数。函数体本身很普通本质就是调后端接口、捕获异常、返回统一结构的结果。但有一个细节值得强调——无论工具执行成功还是失败返回给模型的结果结构必须稳定。失败时要明确返回“失败原因代码”和“可读的失败说明”模型才能据此向用户解释或者决定是否换一种方式重试。def execute_update_order_status(order_id: str, status: str) - dict: try: resp requests.post( f{BASE_URL}/api/orders/{order_id}/status, json{status: status}, timeout10 ) resp.raise_for_status() return { success: True, order_id: order_id, status: status, message: 订单状态更新成功 } except requests.exceptions.Timeout: return { success: False, order_id: order_id, status: status, message: 调用超时请稍后重试 } except requests.exceptions.HTTPError as e: return { success: False, order_id: order_id, status: status, message: f接口返回错误{e.response.status_code} }第三步是做脱敏与权限注入。在工具真正调用前拦截器会把当前用户的角色、工单归属等信息注入到执行上下文。比如普通客服只能看到本人创建的工单主管能看到所辖团队的全部工单角色之外的一律拒绝访问。这和传统后端系统的权限设计逻辑一脉相承只是多了一个模型层需要防止它“绕过”限制——毕竟模型可能会用奇怪的话术尝试越权。整个实验从开始到线上试用大概用了不到两周。两周里有一半时间花在准备测试用例上——我们整理了近百条真实业务场景的用户问法覆盖正常指令、模糊指令、缺参数指令、恶意越权指令。每一个用例跑完都记录模型的调用选择、参数填充和执行结果这个测试集后来成了整个项目回归测试的基础每次迭代都必须全量通过。3.3 多工具组合的编排与执行策略单个工具跑通之后立刻面临一个新的问题真实业务很少只调一个工具。比如“处理异常订单”这个场景光是查询环节就要查订单库、查库存、查客户历史记录然后才谈得上操作。模型如果没有章法地把这些工具调用一遍不仅慢还容易出错。Agent-Reach 的解法是引入“任务编排层”。这个层不直接调用工具而是把模型生成的动作意图解析成一张依赖图。以“处理异常订单”为例编排层会强制先执行订单信息查询再执行库存扣减检查最后执行订单状态变更。顺序不对就不允许执行有依赖关系没满足就等待执行。def plan_execution(intent: dict) - list[dict]: steps [] if intent.get(need_stock_check): steps.append({tool: check_stock, depends_on: [check_order]}) if intent.get(need_update_status): steps.append({tool: update_order_status, depends_on: [check_order, check_stock]}) return steps这个编排层解决了两个麻烦一个是模型同时发起多个工具请求时顺序不可控另一个是任务中途某一步失败时后续步骤怎么办。我们会约定每一步执行完成后要把结果摘要回填给模型让模型知道当前状态再由编排层决定是继续下一步、中止整个任务还是让模型换一种方案。说句实在话这个“预定义依赖图模型动态决策”的混合模式比起纯让模型自由发挥要可靠太多了。纯自由发挥在演示环境看起来很爽但在生产环境稳定性基本没法保证。4. 常见问题与排查技巧实录4.1 模型错误调用工具的排查方法Agent-Reach 上线测试后大量的“模型用错工具”类问题占了 bug 清单最多比例。常见的错误调用类型有三种参数格式不合法、选择了不相关的工具、以及多个工具之间的执行顺序颠倒。当然参数格式不合法这件事是可以通过严格执行 JSON Schema 校验提前过滤掉的剩下的问题要从模型侧找原因。排查这类问题有一个标准思路先把实际发给模型的系统提示词、工具描述和上下文历史完整打印出来复现一次错误调用然后对比“模型实际调用”和“期望调用”的差异在哪里。绝大多数情况下问题出在工具描述写得不够精确。比如把check_order和check_order_status两个工具名写得太像模型就会乱选。解决方法是把工具名区分度拉高或者合并成一个工具并在参数里加细分字段。另有一类情况是模型在上下文里看到用户提过某个旧订单号下一个无关的问题它也会自作主张带上这个订单号造成参数误填。这类属于上下文噪声污染——明明无关的旧信息影响了当前意图判断。碰到这种情况尽快收紧历史保留轮数并且对每轮对话做意图边界识别超出当前话题的信息及时剪掉错误率就会明显下降。4.2 工具执行失败后的恢复策略以前我们把工具执行失败当成“对话终止信号”——要么直接报错要么让模型重新问用户。后来发现这两条路都不好用。直接报错太生硬用户体验差让模型重新问用户又浪费一轮因为很多失败其实是可以自动恢复的。以调用一个内部查询接口超时为例最简单的恢复策略就是重试一次。我们加了一个带次数限制的重试机制第一次失败后自动重发重试间隔递增最多重试三次。如果还是失败再把错误信息交给模型让它结合上下文给用户一个解释然后推荐备用方案。遇到有依赖链的多步任务时重试逻辑还要区分到底重试哪一步避免重复执行已经成功的前序步骤免得造成重复操作。这里想特别叮嘱一句写操作类工具比如转账、改单、发布内容一定不要自动重试幂等性没做好之前一次重复执行可能产生不可逆影响。Agent-Reach 的做法是对所有写操作强制要求调用方传入一个全局唯一的请求 ID后端根据这个 ID 做去重这样即使因为网络问题重发多次后端也只会处理一次。这个细节是上线前最后补上的但它是整个项目里最有价值的安全设计之一。4.3 评估指标与稳定性观测Agent-Reach 做完以后团队最经常问的问题是“这玩意儿到底行不行”。只靠感觉肯定不行得建立一套指标来度量。我们最后定了四个关键指标作为每一次版本迭代的衡量基准工具调用成功率模型调用工具的请求中成功执行并返回有效结果的比例。低于 80% 基本属于不可用状态需要回去查描述或参数问题。任务完成率从用户提出一个完整任务到 Agent 完成所有子步骤并给出最终答复的比例。这个指标衡量的是端到端效果比单看调用成功率更贴近业务价值。无效调用率模型调用了一个工具但参数明显不合理或命中了权限拦截或跟用户意图完全无关的比例。这个指标能暴露模型理解偏差的问题。用户反馈满意度从用户侧收集的简单打分或评价对话结束弹出一个按钮收集一下即可。这四个指标的分析结果会汇总到一张看板上每次升级模型版本或者调整工具描述以后跑一批线上的影子日志数据把原来的用户对话回放一遍但不真正执行写操作对比新旧版本的效果差异。这套流程让我们每一次改动都有数据支撑“拍脑袋优化”从此再没出现过。5. 实战中的避坑经验与后续扩展思考5.1 六个踩坑记录和对应解法实际跑下来这段时间整理了六个在别的地方不太容易看到的坑先记下来方便以后回看。第一工具描述里的“必填参数”如果太少模型就爱偷懒不填。比如更新工单状态只要求订单号模型就会每次都漏填备注原因。后来把“原因”改成必填并声明“必须说明修改理由”模型立刻老实了。其实这是 prompt 设计的问题工具描述本质上也是一种 prompt约束得越细模型行为越可控。第二工具数量超过十几个以后模型选错工具的概率飙升。解决方法是给工具按业务域分组先让模型选域再选工具相当于把一个大选择拆成了两级小选择准确率提升很明显。第三会话中断或超时后恢复对话很难做到无缝衔接。后来实现了会话快照机制——每条任务的关键状态都会持久化保存用户回来以后可以从上次中断的位置继续而不是一切从头开始使用体验好了很多。第四直接拿生产日志跑测试集不够用。正样本多负样本少导致模型对异常请求的抵抗力很差。这个问题的解法是人工构造负样本比如恶意口令、绕过指令、矛盾要求全部加进回归集里每次迭代都跑一遍确保没有越权漏洞。第五模型对某些专用名词的识别能力有限。比如业务内部说的“超卖”模型不知道是什么。后来我们在系统提示词里加了一份术语表预先把业务黑话全列出来模型识别准确率瞬间上去了。第六最开始日志打得太少出了问题以后根本无法回溯模型为什么做出某个决策。后来给每次工具调用都打印完整的上下文、意图识别结果、模型返回的参数和最终执行结果而且要保证结构化的日志格式统一。这看起来增加了一些日志量但对排查问题的帮助是几何级的强烈建议所有做类似项目的人都别省这一步。5.2 从单 Agent 到多 Agent 协同的展望Agent-Reach 目前的形态还主要是单 Agent 完成任务。但真实业务里很多工作天然需要分工。比如处理一笔客户投诉涉及客户画像、订单记录、物流信息、售后政策等多个方面。一个 Agent 要了解所有领域模型上下文压力会非常大工具列表也会膨胀到让模型难以选择。我们的规划是走多 Agent 路线一个主 Agent 负责接收用户请求、理解意图、拆分任务然后把子任务分派给多个专业 Agent每个专业 Agent 只处理自己领域内的那一摊事。各个子 Agent 之间通过一份共享任务状态表进行信息交换而不是把所有上下文塞给同一个模型去记。这个架构的难点在于任务如何在多个 Agent 之间流转、结果如何汇总、以及冲突如何仲裁。我们目前只做到了两个子 Agent 协同的最小验证一个管通用信息检索一个管订单业务操作主 Agent 做最终判断。实测下来上下文消耗明显降低工具选择准确率也有所提升。接下来要解决的是子 Agent 执行结果如何同步给主 Agent 做决策的问题可能要给每个子 Agent 加一个摘要生成环节把执行结果尽量压成一句话再上报。这条路还有不少细节要磨但是方向应该是没问题。5.3 提升模型稳定性的两个小技巧最后补充两个亲测有效的稳定性优化技巧都是很小但很实用的改动。第一个是固定系统提示词的输出格式要求。我们在系统提示词里明确写了“如果需要调用工具请严格按照工具定义输出调用参数不要输出额外解释文字。如果用户提问中缺少必填参数请先向用户询问补全。”就这么简单的一句模型在缺参数场景下的表现直接从“瞎猜一个值硬调”变成了“客气地找用户确认”体验提升很明显。第二个技巧叫做“参数值归一化”。用户表达里可能存在大量口语化描述比如“把那张单子转给老王”这儿的“王”在系统数据里可能对应着姓名、工号好几套标识。直接让模型填参数很容易填成口语文本工具执行端接不住。解法的思路很粗暴但有效提供一个小型实体解析步骤在参数进入工具之前先做一次匹配——用模糊搜索把口语描述映射到系统内的标准标识映射不到了再找用户确认。做完了这一步以后那类因别名、简称导致的调用失败率直线下降。Agent-Reach 这个项目最让我感慨的一点是它没有用什么天顶星科技全部构建在已有的大模型函数调用能力之上核心代码量也不夸张。真正的难点是在确定性要求很高的业务系统里怎么给一个天生带着随机性的模型套上足够多的规则和安全边界。整个工程过程其实是在“模型自由度”和“系统稳定性”之间不断找平衡。希望这篇文章的总结能帮你少踩几个我已经踩过的坑。 
长河君 · 2026/10/8 11:47:01 · 阅读 1.2k 智能体落地最后一公里：Agent-Reach的架构设计与踩坑实录
我前阵子接手了一个内部项目代号就叫 Agent-Reach。名字听着挺唬人拆开看其实就俩词Agent 和 Reach。Agent 是智能体Reach 是触达、覆盖。合起来就是一件事——让智能体真正触达业务干成事。说白了现在大模型聊天已经不算新鲜事了真正难的是让 AI 从“会说话”变成“会办事”。Agent-Reach 这个项目要解决的就是这最后一公里让 AI 能调用内部系统、查询业务数据、执行操作流程并且在真实生产环境里稳定跑起来而不是停留在 Demo 层面玩个两三轮就断线。这篇文章我会把这阵子从零搭建 Agent-Reach 的完整过程做个复盘包含架构思路、技术选型、实操步骤、踩坑记录。如果你也在搞智能体落地或者正头疼 AI 怎么跟现有系统打通这篇内容应该能帮你少走不少弯路。我会尽量把关键细节和决策背后的理由讲透让不同基础的读者都能拿去参考。1. 项目整体设计思路拆解1.1 为什么一定要做智能体触达当时立项的时候我们内部已经有一个挺成熟的对话机器人能回答一些常见业务问题比如查个订单状态、看下库存数量之类。但那个机器人本质是“检索式问答”——用户问一句系统从知识库里找出差不多的答案返回。遇到复杂一点的需求比如“帮我统计一下华东区这个月所有逾期订单并且按原因分类列出”它就完全抓瞎。后来我们试过把大模型接进来直接在 Prompt 里堆上下文。第一批测试效果确实惊艳模型什么都能聊但要真让它执行操作——比如把一条订单标记为异常、生成一个业务报表并推送给人——它就只会“讲道理”不会“动手”。模型生成的回答像一篇作文而不是可执行的动作。Agent-Reach 的出发点就在这里把大模型的能力从“文本生成”延伸到“行动执行”。核心是把大模型的推理能力拆解成一条可执行链路——它理解用户意图拆解成任务清单然后通过工具调用的方式去真正操作业务系统最后把结果整理反馈给用户。这看起来像是给 AI 接了几个 API 就能搞定的活实际上牵扯到权限管理、上下文控制、异常恢复、执行监控等一系列问题。Agent-Reach 本质上是一个薄薄的“行动层”夹在大模型与业务系统中间让模型既能指挥又不至于乱来。1.2 架构选型背后的关键权衡早期做方案的时候我们纠结过两条路线。第一条路子比较“野”直接用 LangChain 这类框架把工具全挂上让大模型自主决定怎么调用。好处是上手快一个脚本几百行就能跑通坏处是失控风险高——模型可能按错误顺序调用工具可能传错参数可能在一个已经失败的操作上反复重试。我们在测试阶段就碰到过模型自作主张把“查询库存”和“锁定库存”两个操作串联执行的情况生产上这属于事故级别的问题。第二条路子比较“保守”把能做的操作预先编排成固定流程然后让大模型去匹配哪个流程适用。这样稳定可控但灵活性很弱。业务上稍有点变化就要重新改流程定义模型跟个“选择按钮”差不多谈不上智能。Agent-Reach 最终选择的是中间路线工具是可自由组合的“积木”但模型不能直接搭积木必须经过一层“执行规划器”做任务拆解与动作排序。规划器会先向模型收集足够的上下文信息再根据业务规则校验每一步动作的合法性与依赖关系通过后才允许执行。为了让不同基础的人能直观理解这套架构打个比方——这就像给一个刚拿驾照的司机配了个教练坐在副驾驶上。方向盘和油门是模型在操作但教练负责看路况、决定变道时机、踩刹车。路线规划允许灵活但安全边界一点都不能让。1.3 Agent 的三层能力模型设计过程中我们把 Agent-Reach 拆成了三个能力层级对应不同的业务价值。这个划分后来也被团队用简洁的方式写进了项目文档第一层叫“知晓层”。这一层解决的是信息触达问题——用户问什么Agent 能从知识库、业务系统里找到答案。核心技术上主要靠检索增强生成加上结构化数据查询知识来源包括内部工单库、产品文档、运维手册。成效上咨询类的问题七八成可以自动覆盖不需要人工介入。第二层叫“行动层”。这一层让 Agent 能调操作类工具比如创建工单、更新记录、发起审批。核心是把“自然语言指令”翻译成“系统操作指令”并安全执行。这块占了整个项目接近七成的开发量也是后续文章想重点展开的部分。第三层叫“协同层”。当单个 Agent 完不成任务时可以把它拆给多个子 Agent 协作或者由主 Agent 编排长链路任务过程中持续跟踪进展、对人进行进度反馈。这一层我们只做了初步探索但架构上预留了接口后续要上也不费劲。三层能力听起来简单真正做起来其实是从“能用”到“好用”再到“智能”的三重门。Agent-Reach 目前完整实现了第一层和第二层第三层跑通了一个最小可行版本。这个规划给团队一个很清晰的路标——知道项目在哪、要去哪、还有多远心里不慌。2. 核心环节实现与实操要点2.1 工具调用的标准化封装Agent-Reach 里最基础的功能模块是“工具”。每个工具代表一个可以被大模型感知和调用的外部能力单元。实际项目里工具可能对应一个后端接口、一个数据库查询、一个消息推送动作甚至是一段内部脚本。而工具要能被模型安全地调用就需要一套统一的信息描述结构。我实际使用的工具描述信息包含四大板块工具名称、功能说明、输入参数定义、输出结果说明。先说名字工具名必须一眼能看出它干什么并且全系统唯一。像query_order_status这种大模型一眼就能理解后续排查日志也方便。功能说明要用“这个工具用于……”句式尽量把触发条件和适用范围写清楚模糊的描述会让模型误用。输入参数这块是最关键也最容易出错的。每个参数要定义类型、是否必填、取值范围或枚举值并且提供一两个示例值。模型会参考这些示例来填充参数示例越贴近真实业务参数生成准确率越高。输出说明描述工具的返回值结构例如返回的是订单状态、操作是否成功还是失败原因。为了形象说明这个结构我放一段配置示例这里用 YAML 做示范实际项目里用 JSON Schema 描述效果也一样tools: - name: update_order_status description: 用于更新指定订单的处理状态适用于售后改单、异常标记等操作。 parameters: - name: order_id type: string required: true description: 订单编号形如 ORD20250001 - name: status type: string required: true enum: [pending, processing, completed, cancelled] description: 目标状态只能从枚举值中选择 - name: reason type: string required: false description: 改单原因备注字数不超过200字 output: success: 更新成功的订单号与当前状态 failure: 失败原因如订单不存在或状态不合法这个配置本身不复杂但有一个细节值得注意说明文字里一定要写清楚工具的限制。比如“只能由客服角色调用”“逾期订单不可修改状态”这些业务规则能让大模型在意图阶段就过滤掉不少高风险请求。我自己吃过亏——一开始没写任何限制模型在测试中非常流畅地把一个已完成的订单改成了已取消状态生产上这就是严重事故。2.2 大模型原生函数调用机制的应用既然要和模型对接就绕不开大模型怎么知道该调用哪个工具。现在市面上的主流大模型基本都支持“函数调用”或“工具调用”能力大模型会分析用户的自然语言输入结合可用工具的说明输出一个结构化的调用意图。简单说就是模型“觉得自己该调用工具时”会在回复里携带一段特殊格式的数据而开发者拿到这段数据再转到实际代码去执行。在 Agent-Reach 里我用了主流模型里常见的tools参数把工具配置发给模型推理接口让模型输出符合调用格式的结构from openai import OpenAI client OpenAI(api_keyyour-api-key) tools [ { type: function, function: { name: update_order_status, description: 更新指定订单的处理状态, parameters: { type: object, properties: { order_id: {type: string}, status: {type: string, enum: [pending, processing, completed, cancelled]} }, required: [order_id, status] } } } ] response client.chat.completions.create( modelyour-model-name, messages[ {role: system, content: 你是业务助手根据用户指令选择合适的工具。}, {role: user, content: 把订单 ORD20250001 置为已完成} ], toolstools, tool_choiceauto )这段代码只是最基础的链路真正放生产里还需要叠加一层“工具调用结果回填”。大模型在完成工具调用后会把执行结果作为新的消息内容继续推理然后决定是调用下一个工具还是把最终结果整理成自然语言返回给用户。这个“思考-行动-观察”的循环是整个 Agent-Reach 能连续处理多步任务的核心机制。这块流程对没接触过的朋友可能稍微绕一点但可以记住一个简单的概括模型先“想”再“动”然后看到结果再决定下一步干什么。每一步都是一次请求-响应只不过多带了一份工具调用信息罢了。这串循环能不能稳定跑下去很大程度取决于前面两节说的工具定义清不清楚、上下文有没有管住。2.3 上下文管理窗口里只留有用的第一版做出来以后最常见的故障就是“聊着聊着模型变傻了”。比如用户连续对话多轮前面问过的一些信息会一直挂在上下文中再加上中间工具调用返回的大段 JSON 结果很快就逼近模型上下文窗口上限。一旦窗口满了超出的历史就会被截断通常截掉的还是最关键的最新内容模型就开始答非所问甚至干脆报错。后来我们定了三条取舍原则实测下来很稳第一历史对话只保留最近三到五轮更早的内容总结成一段摘要放进去第二工具调用结果不回填原始全文只提取关键字段并压缩成简洁文本第三模型内部的“思考过程”不允许写进最终上下文只保留最终动作指令防止中间推理内容挤占窗口。def compress_tool_result(result: dict) - str: # 只提取关键字段压缩长度 keys [status, order_id, success, message] compressed {k: result.get(k) for k in keys if k in result} return json.dumps(compressed, ensure_asciiFalse)这个压缩动作看起来很小作用却非常大。有一回线上处理一个长流程的售后改单任务没压缩前上下文消耗了大概 4000 多个 token压缩以后直接降到不到 400模型推理速度和准确性都提升了一大截。做 Agent 项目的朋友真的建议从一开始就把上下文管理当一等公民对待后面跟多轮任务较劲时会省心很多。3. 实操过程与核心流程跑通记录3.1 技术栈选型与实践清单Agent-Reach 在正式写业务代码之前先把技术栈定了下来。这个选型决定花了不少时间我把最终用下来的组合以及选择理由整理在下面方便后面做类似项目的朋友直接参考模型接入层优先使用支持函数调用的主流大模型国内国外模型都试过最终业务场景里选了对中文理解更稳的一个。关键是确认模型厂商的接口是否支持tools参数不支持的老模型可以直接排除。Agent 框架没有重度依赖 LangChain 这类重量级框架而是自研了轻量的执行规划器。原因是业务团队对可控性要求很高框架封装太多反而看不清每一步在干什么。自研一个核心循环控制在几百行代码内后续排查问题极其方便也更容易按我们的安全要求做定制。工具注册与发现每个工具启动时自动注册到一个统一工具中心工具中心提供名称、描述、参数的索引模型每次发起调用前先从这里拉取最新工具列表。做到“工具即插即用”新工具上线不需要改主流程。业务系统对接走标准 REST API 为主少量老系统用数据库直查加只读账号不允许 Agent 直接执行写操作数据库语句。历史上吃过一次数据库直连乱更新的亏以后这个边界执行得非常严格。权限模型每个工具绑定一个角色标签用户在会话开始时获得角色身份Agent 只能调用该角色权限范围内的工具。用户在上下文里拥有的操作边界不会因为提问方式绕过去。技术栈定下来以后实际开发的节奏比预想顺利很多。主要是前期把工具描述和权限模型这些模棱两可的地方抠清楚了后面写代码反而很快大部分时间都花在面对新边界场景设计防御策略上。这也印证了一件事AI 项目的复杂度往往不在模型能力而在模型与真实世界交互时那些边界情况的处理。3.2 第一个工具从零到上线的完整过程我们拿“工单状态更新”这个场景作为第一个打通闭环的实验对象。这个场景选得很有代表性——它涉及只读查询和写操作两类工具要加入权限校验产出结果也能直观看到非常适合验证链路是否通。第一步是配置工具描述。我把更新工单状态的工具写成了符合模型调用格式的参数定义枚举值提前和业务方确认好。实际上光是整理那些状态枚举值就花了一个下午——因为业务方自己都没想清楚“处理中”和“进行中”到底是不是一个意思这类业务口径问题提前对齐后面测试才不会莫名其妙飘红。第二步是写工具执行函数。函数体本身很普通本质就是调后端接口、捕获异常、返回统一结构的结果。但有一个细节值得强调——无论工具执行成功还是失败返回给模型的结果结构必须稳定。失败时要明确返回“失败原因代码”和“可读的失败说明”模型才能据此向用户解释或者决定是否换一种方式重试。def execute_update_order_status(order_id: str, status: str) - dict: try: resp requests.post( f{BASE_URL}/api/orders/{order_id}/status, json{status: status}, timeout10 ) resp.raise_for_status() return { success: True, order_id: order_id, status: status, message: 订单状态更新成功 } except requests.exceptions.Timeout: return { success: False, order_id: order_id, status: status, message: 调用超时请稍后重试 } except requests.exceptions.HTTPError as e: return { success: False, order_id: order_id, status: status, message: f接口返回错误{e.response.status_code} }第三步是做脱敏与权限注入。在工具真正调用前拦截器会把当前用户的角色、工单归属等信息注入到执行上下文。比如普通客服只能看到本人创建的工单主管能看到所辖团队的全部工单角色之外的一律拒绝访问。这和传统后端系统的权限设计逻辑一脉相承只是多了一个模型层需要防止它“绕过”限制——毕竟模型可能会用奇怪的话术尝试越权。整个实验从开始到线上试用大概用了不到两周。两周里有一半时间花在准备测试用例上——我们整理了近百条真实业务场景的用户问法覆盖正常指令、模糊指令、缺参数指令、恶意越权指令。每一个用例跑完都记录模型的调用选择、参数填充和执行结果这个测试集后来成了整个项目回归测试的基础每次迭代都必须全量通过。3.3 多工具组合的编排与执行策略单个工具跑通之后立刻面临一个新的问题真实业务很少只调一个工具。比如“处理异常订单”这个场景光是查询环节就要查订单库、查库存、查客户历史记录然后才谈得上操作。模型如果没有章法地把这些工具调用一遍不仅慢还容易出错。Agent-Reach 的解法是引入“任务编排层”。这个层不直接调用工具而是把模型生成的动作意图解析成一张依赖图。以“处理异常订单”为例编排层会强制先执行订单信息查询再执行库存扣减检查最后执行订单状态变更。顺序不对就不允许执行有依赖关系没满足就等待执行。def plan_execution(intent: dict) - list[dict]: steps [] if intent.get(need_stock_check): steps.append({tool: check_stock, depends_on: [check_order]}) if intent.get(need_update_status): steps.append({tool: update_order_status, depends_on: [check_order, check_stock]}) return steps这个编排层解决了两个麻烦一个是模型同时发起多个工具请求时顺序不可控另一个是任务中途某一步失败时后续步骤怎么办。我们会约定每一步执行完成后要把结果摘要回填给模型让模型知道当前状态再由编排层决定是继续下一步、中止整个任务还是让模型换一种方案。说句实在话这个“预定义依赖图模型动态决策”的混合模式比起纯让模型自由发挥要可靠太多了。纯自由发挥在演示环境看起来很爽但在生产环境稳定性基本没法保证。4. 常见问题与排查技巧实录4.1 模型错误调用工具的排查方法Agent-Reach 上线测试后大量的“模型用错工具”类问题占了 bug 清单最多比例。常见的错误调用类型有三种参数格式不合法、选择了不相关的工具、以及多个工具之间的执行顺序颠倒。当然参数格式不合法这件事是可以通过严格执行 JSON Schema 校验提前过滤掉的剩下的问题要从模型侧找原因。排查这类问题有一个标准思路先把实际发给模型的系统提示词、工具描述和上下文历史完整打印出来复现一次错误调用然后对比“模型实际调用”和“期望调用”的差异在哪里。绝大多数情况下问题出在工具描述写得不够精确。比如把check_order和check_order_status两个工具名写得太像模型就会乱选。解决方法是把工具名区分度拉高或者合并成一个工具并在参数里加细分字段。另有一类情况是模型在上下文里看到用户提过某个旧订单号下一个无关的问题它也会自作主张带上这个订单号造成参数误填。这类属于上下文噪声污染——明明无关的旧信息影响了当前意图判断。碰到这种情况尽快收紧历史保留轮数并且对每轮对话做意图边界识别超出当前话题的信息及时剪掉错误率就会明显下降。4.2 工具执行失败后的恢复策略以前我们把工具执行失败当成“对话终止信号”——要么直接报错要么让模型重新问用户。后来发现这两条路都不好用。直接报错太生硬用户体验差让模型重新问用户又浪费一轮因为很多失败其实是可以自动恢复的。以调用一个内部查询接口超时为例最简单的恢复策略就是重试一次。我们加了一个带次数限制的重试机制第一次失败后自动重发重试间隔递增最多重试三次。如果还是失败再把错误信息交给模型让它结合上下文给用户一个解释然后推荐备用方案。遇到有依赖链的多步任务时重试逻辑还要区分到底重试哪一步避免重复执行已经成功的前序步骤免得造成重复操作。这里想特别叮嘱一句写操作类工具比如转账、改单、发布内容一定不要自动重试幂等性没做好之前一次重复执行可能产生不可逆影响。Agent-Reach 的做法是对所有写操作强制要求调用方传入一个全局唯一的请求 ID后端根据这个 ID 做去重这样即使因为网络问题重发多次后端也只会处理一次。这个细节是上线前最后补上的但它是整个项目里最有价值的安全设计之一。4.3 评估指标与稳定性观测Agent-Reach 做完以后团队最经常问的问题是“这玩意儿到底行不行”。只靠感觉肯定不行得建立一套指标来度量。我们最后定了四个关键指标作为每一次版本迭代的衡量基准工具调用成功率模型调用工具的请求中成功执行并返回有效结果的比例。低于 80% 基本属于不可用状态需要回去查描述或参数问题。任务完成率从用户提出一个完整任务到 Agent 完成所有子步骤并给出最终答复的比例。这个指标衡量的是端到端效果比单看调用成功率更贴近业务价值。无效调用率模型调用了一个工具但参数明显不合理或命中了权限拦截或跟用户意图完全无关的比例。这个指标能暴露模型理解偏差的问题。用户反馈满意度从用户侧收集的简单打分或评价对话结束弹出一个按钮收集一下即可。这四个指标的分析结果会汇总到一张看板上每次升级模型版本或者调整工具描述以后跑一批线上的影子日志数据把原来的用户对话回放一遍但不真正执行写操作对比新旧版本的效果差异。这套流程让我们每一次改动都有数据支撑“拍脑袋优化”从此再没出现过。5. 实战中的避坑经验与后续扩展思考5.1 六个踩坑记录和对应解法实际跑下来这段时间整理了六个在别的地方不太容易看到的坑先记下来方便以后回看。第一工具描述里的“必填参数”如果太少模型就爱偷懒不填。比如更新工单状态只要求订单号模型就会每次都漏填备注原因。后来把“原因”改成必填并声明“必须说明修改理由”模型立刻老实了。其实这是 prompt 设计的问题工具描述本质上也是一种 prompt约束得越细模型行为越可控。第二工具数量超过十几个以后模型选错工具的概率飙升。解决方法是给工具按业务域分组先让模型选域再选工具相当于把一个大选择拆成了两级小选择准确率提升很明显。第三会话中断或超时后恢复对话很难做到无缝衔接。后来实现了会话快照机制——每条任务的关键状态都会持久化保存用户回来以后可以从上次中断的位置继续而不是一切从头开始使用体验好了很多。第四直接拿生产日志跑测试集不够用。正样本多负样本少导致模型对异常请求的抵抗力很差。这个问题的解法是人工构造负样本比如恶意口令、绕过指令、矛盾要求全部加进回归集里每次迭代都跑一遍确保没有越权漏洞。第五模型对某些专用名词的识别能力有限。比如业务内部说的“超卖”模型不知道是什么。后来我们在系统提示词里加了一份术语表预先把业务黑话全列出来模型识别准确率瞬间上去了。第六最开始日志打得太少出了问题以后根本无法回溯模型为什么做出某个决策。后来给每次工具调用都打印完整的上下文、意图识别结果、模型返回的参数和最终执行结果而且要保证结构化的日志格式统一。这看起来增加了一些日志量但对排查问题的帮助是几何级的强烈建议所有做类似项目的人都别省这一步。5.2 从单 Agent 到多 Agent 协同的展望Agent-Reach 目前的形态还主要是单 Agent 完成任务。但真实业务里很多工作天然需要分工。比如处理一笔客户投诉涉及客户画像、订单记录、物流信息、售后政策等多个方面。一个 Agent 要了解所有领域模型上下文压力会非常大工具列表也会膨胀到让模型难以选择。我们的规划是走多 Agent 路线一个主 Agent 负责接收用户请求、理解意图、拆分任务然后把子任务分派给多个专业 Agent每个专业 Agent 只处理自己领域内的那一摊事。各个子 Agent 之间通过一份共享任务状态表进行信息交换而不是把所有上下文塞给同一个模型去记。这个架构的难点在于任务如何在多个 Agent 之间流转、结果如何汇总、以及冲突如何仲裁。我们目前只做到了两个子 Agent 协同的最小验证一个管通用信息检索一个管订单业务操作主 Agent 做最终判断。实测下来上下文消耗明显降低工具选择准确率也有所提升。接下来要解决的是子 Agent 执行结果如何同步给主 Agent 做决策的问题可能要给每个子 Agent 加一个摘要生成环节把执行结果尽量压成一句话再上报。这条路还有不少细节要磨但是方向应该是没问题。5.3 提升模型稳定性的两个小技巧最后补充两个亲测有效的稳定性优化技巧都是很小但很实用的改动。第一个是固定系统提示词的输出格式要求。我们在系统提示词里明确写了“如果需要调用工具请严格按照工具定义输出调用参数不要输出额外解释文字。如果用户提问中缺少必填参数请先向用户询问补全。”就这么简单的一句模型在缺参数场景下的表现直接从“瞎猜一个值硬调”变成了“客气地找用户确认”体验提升很明显。第二个技巧叫做“参数值归一化”。用户表达里可能存在大量口语化描述比如“把那张单子转给老王”这儿的“王”在系统数据里可能对应着姓名、工号好几套标识。直接让模型填参数很容易填成口语文本工具执行端接不住。解法的思路很粗暴但有效提供一个小型实体解析步骤在参数进入工具之前先做一次匹配——用模糊搜索把口语描述映射到系统内的标准标识映射不到了再找用户确认。做完了这一步以后那类因别名、简称导致的调用失败率直线下降。Agent-Reach 这个项目最让我感慨的一点是它没有用什么天顶星科技全部构建在已有的大模型函数调用能力之上核心代码量也不夸张。真正的难点是在确定性要求很高的业务系统里怎么给一个天生带着随机性的模型套上足够多的规则和安全边界。整个工程过程其实是在“模型自由度”和“系统稳定性”之间不断找平衡。希望这篇文章的总结能帮你少踩几个我已经踩过的坑。