做智能体Agent项目最磨人的一件事往往不是大模型不够聪明而是它“说了”却没“做到”。模型很自信地给了你一段行动计划结果实际调工具时参数传错、路径跑偏、任务做到一半卡住最后返回一个看似正确实则没落地的结果。这也是我做 Agent-Reach 这套东西的起点与其再造一个什么都想管的“超能助手”不如先把一件事情的完成率做到可靠。Agent-Reach 本质上是一套面向任务型智能体Task-oriented Agent的落地工程方案核心思路可以概括成一句话让智能体通过更清晰的决策路由、更可控的工具调用和更克制的记忆管理真正“触达”任务目标。这个名字里的 Reach 有两层意思一是指目标可达二是强调“手要够到东西”——也就是实际调用外部系统完成动作而不只是停留在对话里输出建议。文章里我会用一个完整的订单查询助手案例把整套链路从设计到落地拆开讲透适合正在做 Agent 应用、但发现模型能聊却干不成事的开发者参考。1. 项目定位Agent-Reach 要解决的“可达性”问题先说清楚背景。2023 年之后各种 Agent 框架像雨后春笋一样冒出来很多人拿 LangChain、AutoGPT 之类的工具随便一搭就觉得“智能体”已经完工了。但用下来你会发现这类通用型框架在上手 Demo 场景确实快一进真实业务就露馅任务稍微带点约束、工具稍微多一点中间就会出现规划绕圈、上下文爆炸、工具结果解析失败这类问题。Agent-Reach 不是要去替代这些框架而是解决它们没有深入打磨的那一层行为约束与执行可靠性。1.1 从名字说起Reach 的三层含义我给这个自研方案取名叫 Agent-Reach其实是在拆解的时候给自己定三条验收标准。第一层是目标可达。智能体接到一个具体任务比如“查一下昨天买的那个东西到哪了”它必须在有限的步骤内收敛到终态。这个要求听起来很基础但放在真实业务里并不容易——模型经常把一个简单查询拆成七八个步骤中间还穿插着多余的“思考总结”导致迟迟落不到工具调用上。第二层是资源触达。智能体不能只“知道”该用哪个接口还必须具备正确组装参数、处理鉴权、解析返回结果的能力。我用“手要够到东西”来类比就是模型输出一段 JSON 参数最终能否稳定地转换成一次成功的 API 请求。第三层是结果可靠。即使每一步都执行成功智能体还要能够把多轮工具返回的结果归纳成用户真正关心的答案而不是把一堆原始 JSON 原样甩给用户。这个“最后一公里”的归纳恰恰是最容易被忽略的性能损耗点。定义完这三层之后Agent-Reach 的设计目标就变得非常具体我要的不是“看起来聪明”的对话机器人而是一个高完成率、可观测、能快速定位失败环节的任务执行系统。1.2 为什么不自研框架也不直接用现成框架说实话我自己也试过几套主流框架。它们的共同优势是抽象层次高、上手快但劣势恰恰藏在抽象里框架为了通用性会把规划Planning、记忆Memory、工具Tool都做成高度灵活的组件。灵活性高意味着约束少而约束少对应到执行端就是各种“自由发挥”带来的不确定性。印象最深的一个例子某个开源框架默认会吧用户问题先“反思”一遍再决定调什么工具。在我测试的订单场景里模型在反思步骤里大段分析用户意图分析完之后仍然选错了订单查询接口——因为那批订单分别存在两个不同状态的存储表里规则上明确规定要先根据订单状态路由到对应表但通用框架根本不知道这条业务规则。所以后来我彻底放弃了“让模型自觉”这条路转向在系统层面加约束。Agent-Reach 的设计思路也是从这里开始成型先把业务规则变成代码和结构化配置而不是全指望 prompt 里的几句叮嘱。2. 核心设计决策链路、记忆机制与工具调用整套 Agent-Reach 的逻辑可以压缩成三个模块三层路由、结构化记忆、工具翻译层。这三块各管一摊互相之间不耦合所以调试的时候很舒服哪里出了问题直接看哪个模块。2.1 三层路由让每一步决策都有依据第一层是意图识别。这一步做的是“用户到底想让我干什么”的分类。很多人一上来就喜欢用大模型做自由意图判断但在 Agent-Reach 里我选择了“轻量规则 少量示例”的混合方式。规则负责覆盖高频确定场景比如“查订单”“退货运费”“修改地址”这几类都有明确的关键词和句式模板模型只负责兜底处理那些没匹配上规则的情况。这么设计的原因很实际规则命中成本几乎为零而且不会出现“模型把查询意图理解成了闲聊”这种低级错误。第二层是能力匹配。意图确定之后系统拿到一张候选工具表。这里我用的是向量检索加硬约束过滤向量负责找相似工具硬约束负责排除不满足业务条件的选项。举个例子用户说“查订单”向量检索可能同时给出search_orders和search_historical_orders但硬约束条件会检查订单时间范围和当前订单状态如果订单是三个月前的历史订单就直接过滤掉前一个工具。这个设计看起来多此一举其实避免了智能体“聪明反被聪明误”的典型问题。第三层是路径规划。这一步不是让模型自由发挥而是把常见任务固化成了 DAG有向无环图。比如“查物流”的路径就是固定三步先定位订单、再拉物流轨迹、最后归纳状态。每一步之间有明确的输入输出关系。遇到新任务组合时再由模型在高层次规划一次但规划出来的步骤仍然要匹配到已有的工具节点上不允许“发明”不存在的操作。三层路由最大的好处是可解释。用户问为什么查错了单我可以直接看到是卡在意图层还是能力匹配层而不用去翻模型的一大段思维链。2.2 记忆设计别把聊天记录当记忆记忆设计是我在这个项目里踩坑最多的地方。最早我直接把完整对话历史全部丢给模型结果 token 消耗爆炸不说模型还经常被早期错误的中间步骤带偏。Agent-Reach 里把记忆拆成了一个结构化槽位集合包含四个固定字段goal存用户最终目标、completed_steps存已完成步骤、current_step存当前执行节点、facts存从历史中提取的关键事实比如订单号、收件地址、物流状态。这四个字段在每轮执行后都会被重写只保留对后续任务真正有影响的上下文。比如订单号一经提取就直接放进facts后面每一轮都不需要再从对话里重新翻。对于更长的历史信息我使用了“滚动摘要”策略每完成几个节点就召一次模型把已完成部分浓缩成三到五句话的摘要放进completed_steps。这样既不会丢掉关键进展又避免了让模型反复阅读大量原始对话。我还专门给“上下文预算”设了硬上限。单轮传给模型的上下文除系统提示外原则上是“结构化记忆槽 当前步骤相关的工具描述 最近一轮工具返回”。超出了就直接截断用摘要替代。这个约束非常反直觉但实测效果却出奇地好——因为模型在短上下文里做决策的准确率远高于它在长上下文里“大海捞针”式的搜索。2.3 工具调用接口与自然语言的翻译层工具调用是 Agent-Reach 的“手”也是翻车重灾区。现实中的后端接口千奇百怪有的要传嵌套结构有的返回字段名和业务叫法不一致还有的鉴权逻辑藏在请求头里。我的处理方式是把每个工具都包装成一个标准模块对外只暴露四个部分{ tool_name: search_orders, description: 按订单状态和时间范围查询订单列表, input_schema: { order_status: {type: string, enum: [pending, shipped, completed, canceled]}, start_time: {type: string, format: date}, end_time: {type: string, format: date} }, validate: check_start_before_end(check_required(auth_token)), execute: call_order_service.map_status_to_table_name(order_status) }模型要做的只是根据input_schema产出填好参数的 JSON但真正脏活累活在execute里面。比如order_status为pending时实际数据存放在orders_pending表completed存放在orders_done表——这一段路由逻辑完全由代码接管模型不需要知道表名也就杜绝了它“自由发挥”传错表名的可能。工具输出的归一剑也很关键。后端返回可能是{data: {list: [...], total: 100}}也可能直接返回一个数组Agent-Reach 里每个工具的execute最后都会把结果统一成一种结构{status: success|error|no_result, summary: ..., data: {...}}。这里的summary是由规则或小模型提前生成的自然语言概述主模型在后续推理时优先读summary而不是原始 JSON既省 token 又防信息淹没。3. 实操用一个订单查询助手跑通 Agent-Reach理论拆完直接上实战。我拿最常见的“订单查询助手”场景来做全流程演示这个场景覆盖面广而且任何牵涉到业务系统的开发者都能快速类比到自己项目上。3.1 场景定义与业务规则梳理订单查询看起来简单里面藏着的规则比想象中多。这个场景下用户常见指令有单笔查询、列表查询、附带物流追踪、附带售后状态。我先梳理出四条硬业务规则三个月内的订单走search_orders接口三个月以上走search_historical_orders规则会作为过滤条件写进能力匹配层。用户说“昨天/前天/最近”这类相对时间词必须先归一化为具体日期范围。这一步我放在意图识别之后、能力匹配之前专门用一个轻量时间解析函数处理。查询物流时必须先拿到订单号如果用户没提供单号系统必须先主动向用户索要不得自行猜测。最终回复必须用口语化中文合并订单状态和物流轨迹不可以输出表格或原始报文。这些规则看起来零碎但正是它们让 Agent 具备了真正的“业务触达能力”。把所有规则都塞进 prompt 其实并不现实——因为模型对长列表的遵守率会随着条目增加快速下降。Agent-Reach 的做法是把规则拆进代码分支和结构化配置里模型只保留最核心的行为约束。3.2 核心代码实现意图识别、工具注册与路径规划我用 Python 实现了一个最小可运行版本不依赖大型框架只有几个关键类和函数。先看意图识别部分def detect_intent(user_input: str, llm_client) - str: # 优先走规则命中高频场景 rule_patterns { query_order: [查.*订单, 订单.*到哪, 物流, 配送], query_refund: [退款, 退货, 售后], update_address: [改地址, 修改地址] } for intent, patterns in rule_patterns.items(): for p in patterns: if re.search(p, user_input): return intent # 规则未命中时再交给 LLM 兜底 return llm_client.classify(user_input, candidate_intents[ query_order, query_refund, update_address, other ])然后是工具注册和路径规划。路径规划我用了简单但有效的模式先查模板没有再现场生成。订单查询的常见路径已经固化好直接返回一个节点列表。PLAN_TEMPLATES { query_order: [ {step: 1, tool: resolve_order_params, inputs: []}, {step: 2, tool: search_orders, inputs: [order_time_range, order_status]}, {step: 3, tool: get_logistics, inputs: [order_id]}, {step: 4, tool: generate_final_answer, inputs: [order_info, logistics_info]} ] } def plan_task(intent: str, params: dict): if intent in PLAN_TEMPLATES: return PLAN_TEMPLATES[intent] # 新场景交给模型生成路径但只允许使用已注册工具集中含有的工具 tools get_registered_tool_names() plan llm_client.generate_plan(intent, params, allowed_toolstools) return validate_plan(plan, allowed_toolstools) # 校验每个节点工具名是否合法这个设计的奥妙在于固化模板能保证高频任务 100% 稳定而模型生成路径只作为应对冷门任务的弹窗方案。校验函数validate_plan是关键防线它会检查每一步的工具名是否存在于注册表不存在就直接拒绝整条规划并回退到人工提示。接下来看工具模块是怎么封装的。我以search_orders为例register_tool(search_orders) class SearchOrdersTool: def validate_params(self, params): required [order_time_range, order_status] for r in required: if r not in params: raise ToolParamError(f缺失参数 {r}) if params[order_time_range][0] params[order_time_range][1]: raise ToolParamError(开始时间不能晚于结束时间) return True def execute(self, params, context): range_start, range_end params[order_time_range] # 三个月内的订单走主表 current_table orders_latest order_list db.query( fSELECT * FROM {current_table} fWHERE status {params[order_status]} fAND create_time BETWEEN {range_start} AND {range_end} ) if not order_list: return {status: no_result, summary: 该时间段内没有符合条件的订单, data: []} return {status: success, summary: f找到 {len(order_list)} 笔订单状态为 {params[order_status]} f最早订单创建于 {order_list[0][create_time]}, data: order_list}注意execute返回的summary就是上一节提到的归一化设计主模型在下一轮能直接基于这段自然语言继续决策。最后是主循环。Agent-Reach 的执行器会按计划节点逐个执行并维护结构化记忆槽def run_task(user_input, user_id): intent detect_intent(user_input, llm_client) params extract_params(user_input) # 这里调时间解析、实体抽取 plan plan_task(intent, params) memory { goal: user_input, completed_steps: [], current_step: None, facts: {user_id: user_id, intent: intent} } for step in plan: memory[current_step] step tool get_tool_by_name(step[tool]) tool_inputs {inp: memory[facts].get(inp, params.get(inp)) for inp in step[inputs]} result tool.execute(tool_inputs, memorymemory) if result[status] error: return {status: failed, node: step[tool], message: result.get(error)} # 把关键信息写进记忆槽避免下一轮重新翻上下文 merge_facts(memory[facts], result.get(facts, {})) final_answer generate_final_answer(memory) return {status: success, answer: final_answer}主循环做了一次非常关键的“目标收敛”每一轮执行都在往memory[facts]里填充下一步需要的输入。比如第一步resolve_order_params把用户说的“昨天”转换成具体时间范围并写入 facts后面search_orders再取参数时就不需要看原始对话了。3.3 效果评估与参数调整很多人做完 Agent 就不管了但我建议至少要盯三个指标任务完成率Completion Rate、平均执行步数、工具调用失败分布。这三个指标能直接反映规划质量和工具层稳定性。在订单助手这个案例里我用了一组基线参数反复调优最终调的是一组很保守的数值模型温度0.2。任务型 Agent 不需要创造性温度越低工具调用参数越规整。我实测过从 0.7 降到 0.2工具参数 JSON 语法错误率下降了差不多六成。最大规划步数4。订单查询模板本身就是 4 步超过这个步数说明模型在绕路直接终止并进入兜底人工处理。工具执行超时10 秒。超过 10 秒的后端调用大概率是连不上或死锁没有必要让模型等待更久。上下文最大 token1200。超出部分全部压缩进摘要。这个上限在开发者看来非常“抠门”但它逼着记忆槽去识别关键信息而不是把什么痕迹都当宝贝留着。调优前后的对比我也记录过。调优前同一个测试集跑了 100 条用户指令完成率只有 68%平均走了 7.2 步其中search_orders因为参数缺失失败 11 次。调优之后完成率到了 92%平均步数降到 4.1工具层失败次数降到 2 次。剩下的 8% 失败案例大多数属于用户给了非常模糊的表述比如只发了一个“哦”连意图层都无法稳定判断。4. 常见问题与排查实录实践过程中我踩过的坑是真的多。挑几个典型问题讲讲排查思路也算给后来者留一份经验笔记。4.1 智能体在一个环节反复打转这是最常见的“循环病”。模型在执行某个步骤时如果工具返回了非预期结果它不会换个思路而是在原地反复调用同一个工具或者反复生成“让我重新确认一下”这类空转内容。我的排查从两个层面入手。第一层是给主循环加去重检测记录最近三步的工具名和参数哈希如果出现两轮完全相同的调用直接判定为循环强制终止任务并提示用户补充信息。第二层是在 prompt 里增加一条强约束“如果在连续两个回合内调用了相同工具且结果未发生变化你应当停止操作并如实汇报。”这条约束虽然简单但降循环的效果比加一大堆复杂推理指令要明显得多。另外还要检查是不是规划时要求了过大的自由度。如果任务本身已经走模板路径就不要在 prompt 里让模型“灵活调整顺序”因为模板内的顺序是经过人工验证的。4.2 上下文越长模型越笨这个问题在 Agent 早期版本里表现得非常明显。只要对话轮次超过 10 轮模型就开始“失忆”甚至会把前面已经确认的订单号给改掉。我后来想明白问题的关键不是模型记不住而是它在混乱的上下文里无法区分哪些信息可信。旧上下文里有用户的原始表述、有模型的中间猜测、有工具返回的原始数据一旦这些信息互相冲突模型就不知道以谁为准。解决办法就是回到结构化记忆槽设计既然业务系统连数据库都分表存储了为什么给模型的记忆不也做成分表呢我在facts中对每类信息设置来源优先级工具返回信息的优先级永远高于模型猜测用户的明确纠正优先级最高。执行过程中所有被写入facts的字段都带一个source标记后续决策只读取最高优先级的来源不看冲突的杂音。4.3 工具调用经常返回无效结果这个问题多发在早期实验阶段。模型产出的 JSON 参数确实符合 schema但调用接口时仍然报错。最典型的情况是字段格式不匹配用户说“今天”模型把时间解析成了日期但接口要求的是带时区的时间戳用户说“取消订单”模型顺手填了order_statuscanceled但业务规则要求取消操作必须走独立接口不能改订单状态字段。排查办法是靠两层校验。第一层是在validate_params中做业务级校验比如时间范围必须转换成YYYY-MM-DD HH:MM:SS再传给后端。第二层是增加一个“参数后处理”函数翻译模型输出中的业务概念。比如模型传进来order_statuscanceled后处理函数会识别出这其实是一个动作意图于是自动路由到cancel_order工具而不是search_orders。这个后处理可以让工具调用的成功率明显提升。4.4 常用问题速查表这里给出我日常排障常用的速查表可以直接“抄作业”现象可能原因排查方法解决方案任务执行步数异常多规划层没有使用模板被模型自由发挥打印规划结果检查plan_task返回节点数将高频任务固化进PLAN_TEMPLATES禁止模型改序同一步骤反复执行工具返回结果没进入facts每轮都在原地重算观察 memory 中facts是否更新调整merge_facts优先写入工具返回值模型把订单状态改错上下文过长导致关键信息被淹没统计单轮上下文 token 数压缩记忆槽只保留当前进度和最终目标工具参数格式报错模型未按 input_schema 生成 JSON开启参数后处理打印模型原始输出增加格式转换函数统一时间、枚举字段格式最终回复像原始报文缺少结果归纳环节检查generate_final_answer是否使用 summary在工具返回时生成 summary主模型基于摘要作答用户说换一种说法就识别不了规则覆盖率不够查看意图识别日志中命中情况扩充规则模式增加冷启动示例让 LLM 兜底更稳5. 收尾一点个人体会这个项目做到最后我最大的感悟不是某个算法多精妙而是“工程约束比模型聪明更重要”。大模型给智能体带来的能力边界当然重要但在真实业务里让它在固定的轨道上稳定运行往往比挖掘更多能力更迫切。Agent-Reach 这个名字一直在提醒我自己目标是“够到”那个结果而不是生成一段漂亮的思考过程。如果让我给正在做类似项目的人一个建议我会说先不要追求“全能助手”挑一个最小但真实的业务场景把 20 条用户指令跑通再跑 100 条把所有失败原因逐个拆开。你会惊讶地发现大部分失败并不是模型不行而是规则没梳理清楚、工具没封装好、上下文没控制住。把这三件事做扎实你的 Agent 就已经能领先市面上大半演示级项目了。最后再分享一个小技巧在系统提示词的最末尾我加了一句“如果工具执行返回失败优先检查参数格式其次检查是否有更合适的工具不要重复原样重试。”这一句话就让失败后的行为从“原地打转”变成了“尝试修正”单这一项就把任务完成率拉高了将近 10%。这类细节很难在文档里找到但恰恰是它们决定了 Agent 到底是玩具还是工具。
做智能体Agent项目最磨人的一件事往往不是大模型不够聪明而是它“说了”却没“做到”。模型很自信地给了你一段行动计划结果实际调工具时参数传错、路径跑偏、任务做到一半卡住最后返回一个看似正确实则没落地的结果。这也是我做 Agent-Reach 这套东西的起点与其再造一个什么都想管的“超能助手”不如先把一件事情的完成率做到可靠。Agent-Reach 本质上是一套面向任务型智能体Task-oriented Agent的落地工程方案核心思路可以概括成一句话让智能体通过更清晰的决策路由、更可控的工具调用和更克制的记忆管理真正“触达”任务目标。这个名字里的 Reach 有两层意思一是指目标可达二是强调“手要够到东西”——也就是实际调用外部系统完成动作而不只是停留在对话里输出建议。文章里我会用一个完整的订单查询助手案例把整套链路从设计到落地拆开讲透适合正在做 Agent 应用、但发现模型能聊却干不成事的开发者参考。1. 项目定位Agent-Reach 要解决的“可达性”问题先说清楚背景。2023 年之后各种 Agent 框架像雨后春笋一样冒出来很多人拿 LangChain、AutoGPT 之类的工具随便一搭就觉得“智能体”已经完工了。但用下来你会发现这类通用型框架在上手 Demo 场景确实快一进真实业务就露馅任务稍微带点约束、工具稍微多一点中间就会出现规划绕圈、上下文爆炸、工具结果解析失败这类问题。Agent-Reach 不是要去替代这些框架而是解决它们没有深入打磨的那一层行为约束与执行可靠性。1.1 从名字说起Reach 的三层含义我给这个自研方案取名叫 Agent-Reach其实是在拆解的时候给自己定三条验收标准。第一层是目标可达。智能体接到一个具体任务比如“查一下昨天买的那个东西到哪了”它必须在有限的步骤内收敛到终态。这个要求听起来很基础但放在真实业务里并不容易——模型经常把一个简单查询拆成七八个步骤中间还穿插着多余的“思考总结”导致迟迟落不到工具调用上。第二层是资源触达。智能体不能只“知道”该用哪个接口还必须具备正确组装参数、处理鉴权、解析返回结果的能力。我用“手要够到东西”来类比就是模型输出一段 JSON 参数最终能否稳定地转换成一次成功的 API 请求。第三层是结果可靠。即使每一步都执行成功智能体还要能够把多轮工具返回的结果归纳成用户真正关心的答案而不是把一堆原始 JSON 原样甩给用户。这个“最后一公里”的归纳恰恰是最容易被忽略的性能损耗点。定义完这三层之后Agent-Reach 的设计目标就变得非常具体我要的不是“看起来聪明”的对话机器人而是一个高完成率、可观测、能快速定位失败环节的任务执行系统。1.2 为什么不自研框架也不直接用现成框架说实话我自己也试过几套主流框架。它们的共同优势是抽象层次高、上手快但劣势恰恰藏在抽象里框架为了通用性会把规划Planning、记忆Memory、工具Tool都做成高度灵活的组件。灵活性高意味着约束少而约束少对应到执行端就是各种“自由发挥”带来的不确定性。印象最深的一个例子某个开源框架默认会吧用户问题先“反思”一遍再决定调什么工具。在我测试的订单场景里模型在反思步骤里大段分析用户意图分析完之后仍然选错了订单查询接口——因为那批订单分别存在两个不同状态的存储表里规则上明确规定要先根据订单状态路由到对应表但通用框架根本不知道这条业务规则。所以后来我彻底放弃了“让模型自觉”这条路转向在系统层面加约束。Agent-Reach 的设计思路也是从这里开始成型先把业务规则变成代码和结构化配置而不是全指望 prompt 里的几句叮嘱。2. 核心设计决策链路、记忆机制与工具调用整套 Agent-Reach 的逻辑可以压缩成三个模块三层路由、结构化记忆、工具翻译层。这三块各管一摊互相之间不耦合所以调试的时候很舒服哪里出了问题直接看哪个模块。2.1 三层路由让每一步决策都有依据第一层是意图识别。这一步做的是“用户到底想让我干什么”的分类。很多人一上来就喜欢用大模型做自由意图判断但在 Agent-Reach 里我选择了“轻量规则 少量示例”的混合方式。规则负责覆盖高频确定场景比如“查订单”“退货运费”“修改地址”这几类都有明确的关键词和句式模板模型只负责兜底处理那些没匹配上规则的情况。这么设计的原因很实际规则命中成本几乎为零而且不会出现“模型把查询意图理解成了闲聊”这种低级错误。第二层是能力匹配。意图确定之后系统拿到一张候选工具表。这里我用的是向量检索加硬约束过滤向量负责找相似工具硬约束负责排除不满足业务条件的选项。举个例子用户说“查订单”向量检索可能同时给出search_orders和search_historical_orders但硬约束条件会检查订单时间范围和当前订单状态如果订单是三个月前的历史订单就直接过滤掉前一个工具。这个设计看起来多此一举其实避免了智能体“聪明反被聪明误”的典型问题。第三层是路径规划。这一步不是让模型自由发挥而是把常见任务固化成了 DAG有向无环图。比如“查物流”的路径就是固定三步先定位订单、再拉物流轨迹、最后归纳状态。每一步之间有明确的输入输出关系。遇到新任务组合时再由模型在高层次规划一次但规划出来的步骤仍然要匹配到已有的工具节点上不允许“发明”不存在的操作。三层路由最大的好处是可解释。用户问为什么查错了单我可以直接看到是卡在意图层还是能力匹配层而不用去翻模型的一大段思维链。2.2 记忆设计别把聊天记录当记忆记忆设计是我在这个项目里踩坑最多的地方。最早我直接把完整对话历史全部丢给模型结果 token 消耗爆炸不说模型还经常被早期错误的中间步骤带偏。Agent-Reach 里把记忆拆成了一个结构化槽位集合包含四个固定字段goal存用户最终目标、completed_steps存已完成步骤、current_step存当前执行节点、facts存从历史中提取的关键事实比如订单号、收件地址、物流状态。这四个字段在每轮执行后都会被重写只保留对后续任务真正有影响的上下文。比如订单号一经提取就直接放进facts后面每一轮都不需要再从对话里重新翻。对于更长的历史信息我使用了“滚动摘要”策略每完成几个节点就召一次模型把已完成部分浓缩成三到五句话的摘要放进completed_steps。这样既不会丢掉关键进展又避免了让模型反复阅读大量原始对话。我还专门给“上下文预算”设了硬上限。单轮传给模型的上下文除系统提示外原则上是“结构化记忆槽 当前步骤相关的工具描述 最近一轮工具返回”。超出了就直接截断用摘要替代。这个约束非常反直觉但实测效果却出奇地好——因为模型在短上下文里做决策的准确率远高于它在长上下文里“大海捞针”式的搜索。2.3 工具调用接口与自然语言的翻译层工具调用是 Agent-Reach 的“手”也是翻车重灾区。现实中的后端接口千奇百怪有的要传嵌套结构有的返回字段名和业务叫法不一致还有的鉴权逻辑藏在请求头里。我的处理方式是把每个工具都包装成一个标准模块对外只暴露四个部分{ tool_name: search_orders, description: 按订单状态和时间范围查询订单列表, input_schema: { order_status: {type: string, enum: [pending, shipped, completed, canceled]}, start_time: {type: string, format: date}, end_time: {type: string, format: date} }, validate: check_start_before_end(check_required(auth_token)), execute: call_order_service.map_status_to_table_name(order_status) }模型要做的只是根据input_schema产出填好参数的 JSON但真正脏活累活在execute里面。比如order_status为pending时实际数据存放在orders_pending表completed存放在orders_done表——这一段路由逻辑完全由代码接管模型不需要知道表名也就杜绝了它“自由发挥”传错表名的可能。工具输出的归一剑也很关键。后端返回可能是{data: {list: [...], total: 100}}也可能直接返回一个数组Agent-Reach 里每个工具的execute最后都会把结果统一成一种结构{status: success|error|no_result, summary: ..., data: {...}}。这里的summary是由规则或小模型提前生成的自然语言概述主模型在后续推理时优先读summary而不是原始 JSON既省 token 又防信息淹没。3. 实操用一个订单查询助手跑通 Agent-Reach理论拆完直接上实战。我拿最常见的“订单查询助手”场景来做全流程演示这个场景覆盖面广而且任何牵涉到业务系统的开发者都能快速类比到自己项目上。3.1 场景定义与业务规则梳理订单查询看起来简单里面藏着的规则比想象中多。这个场景下用户常见指令有单笔查询、列表查询、附带物流追踪、附带售后状态。我先梳理出四条硬业务规则三个月内的订单走search_orders接口三个月以上走search_historical_orders规则会作为过滤条件写进能力匹配层。用户说“昨天/前天/最近”这类相对时间词必须先归一化为具体日期范围。这一步我放在意图识别之后、能力匹配之前专门用一个轻量时间解析函数处理。查询物流时必须先拿到订单号如果用户没提供单号系统必须先主动向用户索要不得自行猜测。最终回复必须用口语化中文合并订单状态和物流轨迹不可以输出表格或原始报文。这些规则看起来零碎但正是它们让 Agent 具备了真正的“业务触达能力”。把所有规则都塞进 prompt 其实并不现实——因为模型对长列表的遵守率会随着条目增加快速下降。Agent-Reach 的做法是把规则拆进代码分支和结构化配置里模型只保留最核心的行为约束。3.2 核心代码实现意图识别、工具注册与路径规划我用 Python 实现了一个最小可运行版本不依赖大型框架只有几个关键类和函数。先看意图识别部分def detect_intent(user_input: str, llm_client) - str: # 优先走规则命中高频场景 rule_patterns { query_order: [查.*订单, 订单.*到哪, 物流, 配送], query_refund: [退款, 退货, 售后], update_address: [改地址, 修改地址] } for intent, patterns in rule_patterns.items(): for p in patterns: if re.search(p, user_input): return intent # 规则未命中时再交给 LLM 兜底 return llm_client.classify(user_input, candidate_intents[ query_order, query_refund, update_address, other ])然后是工具注册和路径规划。路径规划我用了简单但有效的模式先查模板没有再现场生成。订单查询的常见路径已经固化好直接返回一个节点列表。PLAN_TEMPLATES { query_order: [ {step: 1, tool: resolve_order_params, inputs: []}, {step: 2, tool: search_orders, inputs: [order_time_range, order_status]}, {step: 3, tool: get_logistics, inputs: [order_id]}, {step: 4, tool: generate_final_answer, inputs: [order_info, logistics_info]} ] } def plan_task(intent: str, params: dict): if intent in PLAN_TEMPLATES: return PLAN_TEMPLATES[intent] # 新场景交给模型生成路径但只允许使用已注册工具集中含有的工具 tools get_registered_tool_names() plan llm_client.generate_plan(intent, params, allowed_toolstools) return validate_plan(plan, allowed_toolstools) # 校验每个节点工具名是否合法这个设计的奥妙在于固化模板能保证高频任务 100% 稳定而模型生成路径只作为应对冷门任务的弹窗方案。校验函数validate_plan是关键防线它会检查每一步的工具名是否存在于注册表不存在就直接拒绝整条规划并回退到人工提示。接下来看工具模块是怎么封装的。我以search_orders为例register_tool(search_orders) class SearchOrdersTool: def validate_params(self, params): required [order_time_range, order_status] for r in required: if r not in params: raise ToolParamError(f缺失参数 {r}) if params[order_time_range][0] params[order_time_range][1]: raise ToolParamError(开始时间不能晚于结束时间) return True def execute(self, params, context): range_start, range_end params[order_time_range] # 三个月内的订单走主表 current_table orders_latest order_list db.query( fSELECT * FROM {current_table} fWHERE status {params[order_status]} fAND create_time BETWEEN {range_start} AND {range_end} ) if not order_list: return {status: no_result, summary: 该时间段内没有符合条件的订单, data: []} return {status: success, summary: f找到 {len(order_list)} 笔订单状态为 {params[order_status]} f最早订单创建于 {order_list[0][create_time]}, data: order_list}注意execute返回的summary就是上一节提到的归一化设计主模型在下一轮能直接基于这段自然语言继续决策。最后是主循环。Agent-Reach 的执行器会按计划节点逐个执行并维护结构化记忆槽def run_task(user_input, user_id): intent detect_intent(user_input, llm_client) params extract_params(user_input) # 这里调时间解析、实体抽取 plan plan_task(intent, params) memory { goal: user_input, completed_steps: [], current_step: None, facts: {user_id: user_id, intent: intent} } for step in plan: memory[current_step] step tool get_tool_by_name(step[tool]) tool_inputs {inp: memory[facts].get(inp, params.get(inp)) for inp in step[inputs]} result tool.execute(tool_inputs, memorymemory) if result[status] error: return {status: failed, node: step[tool], message: result.get(error)} # 把关键信息写进记忆槽避免下一轮重新翻上下文 merge_facts(memory[facts], result.get(facts, {})) final_answer generate_final_answer(memory) return {status: success, answer: final_answer}主循环做了一次非常关键的“目标收敛”每一轮执行都在往memory[facts]里填充下一步需要的输入。比如第一步resolve_order_params把用户说的“昨天”转换成具体时间范围并写入 facts后面search_orders再取参数时就不需要看原始对话了。3.3 效果评估与参数调整很多人做完 Agent 就不管了但我建议至少要盯三个指标任务完成率Completion Rate、平均执行步数、工具调用失败分布。这三个指标能直接反映规划质量和工具层稳定性。在订单助手这个案例里我用了一组基线参数反复调优最终调的是一组很保守的数值模型温度0.2。任务型 Agent 不需要创造性温度越低工具调用参数越规整。我实测过从 0.7 降到 0.2工具参数 JSON 语法错误率下降了差不多六成。最大规划步数4。订单查询模板本身就是 4 步超过这个步数说明模型在绕路直接终止并进入兜底人工处理。工具执行超时10 秒。超过 10 秒的后端调用大概率是连不上或死锁没有必要让模型等待更久。上下文最大 token1200。超出部分全部压缩进摘要。这个上限在开发者看来非常“抠门”但它逼着记忆槽去识别关键信息而不是把什么痕迹都当宝贝留着。调优前后的对比我也记录过。调优前同一个测试集跑了 100 条用户指令完成率只有 68%平均走了 7.2 步其中search_orders因为参数缺失失败 11 次。调优之后完成率到了 92%平均步数降到 4.1工具层失败次数降到 2 次。剩下的 8% 失败案例大多数属于用户给了非常模糊的表述比如只发了一个“哦”连意图层都无法稳定判断。4. 常见问题与排查实录实践过程中我踩过的坑是真的多。挑几个典型问题讲讲排查思路也算给后来者留一份经验笔记。4.1 智能体在一个环节反复打转这是最常见的“循环病”。模型在执行某个步骤时如果工具返回了非预期结果它不会换个思路而是在原地反复调用同一个工具或者反复生成“让我重新确认一下”这类空转内容。我的排查从两个层面入手。第一层是给主循环加去重检测记录最近三步的工具名和参数哈希如果出现两轮完全相同的调用直接判定为循环强制终止任务并提示用户补充信息。第二层是在 prompt 里增加一条强约束“如果在连续两个回合内调用了相同工具且结果未发生变化你应当停止操作并如实汇报。”这条约束虽然简单但降循环的效果比加一大堆复杂推理指令要明显得多。另外还要检查是不是规划时要求了过大的自由度。如果任务本身已经走模板路径就不要在 prompt 里让模型“灵活调整顺序”因为模板内的顺序是经过人工验证的。4.2 上下文越长模型越笨这个问题在 Agent 早期版本里表现得非常明显。只要对话轮次超过 10 轮模型就开始“失忆”甚至会把前面已经确认的订单号给改掉。我后来想明白问题的关键不是模型记不住而是它在混乱的上下文里无法区分哪些信息可信。旧上下文里有用户的原始表述、有模型的中间猜测、有工具返回的原始数据一旦这些信息互相冲突模型就不知道以谁为准。解决办法就是回到结构化记忆槽设计既然业务系统连数据库都分表存储了为什么给模型的记忆不也做成分表呢我在facts中对每类信息设置来源优先级工具返回信息的优先级永远高于模型猜测用户的明确纠正优先级最高。执行过程中所有被写入facts的字段都带一个source标记后续决策只读取最高优先级的来源不看冲突的杂音。4.3 工具调用经常返回无效结果这个问题多发在早期实验阶段。模型产出的 JSON 参数确实符合 schema但调用接口时仍然报错。最典型的情况是字段格式不匹配用户说“今天”模型把时间解析成了日期但接口要求的是带时区的时间戳用户说“取消订单”模型顺手填了order_statuscanceled但业务规则要求取消操作必须走独立接口不能改订单状态字段。排查办法是靠两层校验。第一层是在validate_params中做业务级校验比如时间范围必须转换成YYYY-MM-DD HH:MM:SS再传给后端。第二层是增加一个“参数后处理”函数翻译模型输出中的业务概念。比如模型传进来order_statuscanceled后处理函数会识别出这其实是一个动作意图于是自动路由到cancel_order工具而不是search_orders。这个后处理可以让工具调用的成功率明显提升。4.4 常用问题速查表这里给出我日常排障常用的速查表可以直接“抄作业”现象可能原因排查方法解决方案任务执行步数异常多规划层没有使用模板被模型自由发挥打印规划结果检查plan_task返回节点数将高频任务固化进PLAN_TEMPLATES禁止模型改序同一步骤反复执行工具返回结果没进入facts每轮都在原地重算观察 memory 中facts是否更新调整merge_facts优先写入工具返回值模型把订单状态改错上下文过长导致关键信息被淹没统计单轮上下文 token 数压缩记忆槽只保留当前进度和最终目标工具参数格式报错模型未按 input_schema 生成 JSON开启参数后处理打印模型原始输出增加格式转换函数统一时间、枚举字段格式最终回复像原始报文缺少结果归纳环节检查generate_final_answer是否使用 summary在工具返回时生成 summary主模型基于摘要作答用户说换一种说法就识别不了规则覆盖率不够查看意图识别日志中命中情况扩充规则模式增加冷启动示例让 LLM 兜底更稳5. 收尾一点个人体会这个项目做到最后我最大的感悟不是某个算法多精妙而是“工程约束比模型聪明更重要”。大模型给智能体带来的能力边界当然重要但在真实业务里让它在固定的轨道上稳定运行往往比挖掘更多能力更迫切。Agent-Reach 这个名字一直在提醒我自己目标是“够到”那个结果而不是生成一段漂亮的思考过程。如果让我给正在做类似项目的人一个建议我会说先不要追求“全能助手”挑一个最小但真实的业务场景把 20 条用户指令跑通再跑 100 条把所有失败原因逐个拆开。你会惊讶地发现大部分失败并不是模型不行而是规则没梳理清楚、工具没封装好、上下文没控制住。把这三件事做扎实你的 Agent 就已经能领先市面上大半演示级项目了。最后再分享一个小技巧在系统提示词的最末尾我加了一句“如果工具执行返回失败优先检查参数格式其次检查是否有更合适的工具不要重复原样重试。”这一句话就让失败后的行为从“原地打转”变成了“尝试修正”单这一项就把任务完成率拉高了将近 10%。这类细节很难在文档里找到但恰恰是它们决定了 Agent 到底是玩具还是工具。
