做AI应用这一年多我最大的感触是模型能力早就不是瓶颈了瓶颈在于Agent能不能“够到”它该够到的东西。你给模型配了工具它未必知道什么时候用你把一堆文档塞进上下文它可能在第三轮对话就把最关键的指令给忘了你让它访问一个服务结果接口参数映射错了整个链路崩掉。这些问题听起来五花八门本质只有一个——智能体的触达范围不够。Agent-Reach就是我在这个背景下折腾出来的一个小项目核心做一件事把“Agent能触达什么、触达得怎么样”变成可度量的工程指标而不是靠感觉和运气。这个项目用了大概两周时间跑通包含一套触达能力评估框架、一个轻量级的工具注册中心以及一个能直接跑起来的Demo。适合两类人看一类是做Agent落地、天天被工具调用和上下文管理折磨的应用开发者另一类是刚入行、对“Agent到底能做多大事”还没有体感的同学。看完之后你能获得一套可直接复现的方案以及几个我踩过之后特别疼的坑。1. Agent-Reach先想清楚触达范围到底由什么决定1.1 从“会聊天”到“会办事”触达能力是分水岭几乎每个做Agent的人都会经历一个阶段模型聊得好好的一接真实任务就露馅。不是理解能力问题而是Agent和真实世界之间隔着一层“够不着”。你让它查订单它不知道订单系统在哪儿你让它写 Python 脚本处理文件它不知道当前环境装了哪些库你让它从三个数据库里汇总数据它连哪个库连哪个端口都说不清。我把这套问题统一归因为“触达范围”不足。Agent-Reach 这个名字就是这么来的——Reach 就是触达你不仅要看模型能不能推理还要看模型能不能拿到工具、拿对参数、在上下文里保住关键信息、在目标偏移时拉回来。这四个维度缺一个Agent 在真实场景里就会像一个人只长了一只手还是断了半截那种。基础模型本身已经具备了很强的语义理解能力这和人类用工具的场景很像。一个人知道怎么写代码但如果电脑上没有装编译器他写再多也跑不起来一个模型知道怎么调用函数但如果函数的描述写得含糊参数类型对不上返回值格式和预期不符它就很难完成任务。Agent-Reach 要做的就是把“电脑上的编译器”和“人对编译器的理解”之间的裂缝填平。1.2 触达边界的四个层次我可以把触达拆成四层这套分层是 Agent-Reach 整个设计的骨架。第一层是上下文触达。模型每一轮能看到的 token 是有限的上下文就是一个“工作台”你往上面摆的东西决定了它能干什么。很多项目失败在这一点把几千页的资料全塞进去结果模型在处理任务时指令、示例、当前状态都被挤到上下文窗口边缘模型“忘了”最初的目标。上下文触达不是“塞得越多越好”而是“每一个 token 都要为达成任务服务”。第二层是工具触达。Agent 使用外部能力的通道就是工具调用。工具触达的问题通常是两种一是工具“存在但没有被发现”——模型不知道有这个工具或者工具描述写得差模型无法把它和当前任务关联起来二是工具“被找到了但不会用”——参数名不匹配、类型错误、必填项缺失这种问题在实际调试中占掉了我一半以上的时间。第三层是状态触达。Agent 在执行多步任务时需要知道“我现在走到哪一步了”。如果每一步之间没有状态同步模型就会像闭着眼睛走路每一步都靠猜。状态触达解决的是“Agent对自己所处位置的感知”它需要在上下文中显式地维护一份任务状态包括已完成步骤、当前步骤、遇到阻塞的原因、下一步候选动作。第四层是目标触达。这是最容易被忽略的一层。Agent 执行任务时经过几轮工具调用之后经常发生“目标漂移”——一开始要总结订单中途变成调取用户信息最后变成分析用户画像。Agent-Reach 里我用了一个强制措施每轮调用之前都让模型先复述当前目标再决定下一步动作用这种方式把目标钉在上下文里。这四个层次也不是并列关系而是递进关系。上下文触达是做减法工具触达是做连接状态触达是做追踪目标触达是做对齐。一个触达完整的 Agent应该是“该看到的都看到该调用的都调用该记住的都记住该达成的都达成”。2. Agent-Reach的核心机制工具注册与上下文预算2.1 工具注册表让模型“看见”能用的手Agent-Reach 里最关键的一个组件是工具注册表。它不是简单地把函数列表丢给模型而是为每一个工具建立一张“可检索、可评估、可限流”的元信息卡。我给了三个字段功能和适用场景、参数结构、调用示例。功能和适用场景决定了模型在什么情况下想起这个工具。参数结构决定了模型能不能正确组装一次调用。调用示例是给模型看的“标准答案”因为大多数模型对“文字描述的工具”理解得还行但对“泛型参数”经常不理解。我见过很多模型把email: string参数传成email: { address: xxx }这样的嵌套结构就是因为缺少一个简单的示例告诉它“这里直接填字符串就好”。工具注册表还有一个不太起眼但很实用的设计健康检查。每个工具注册时需要声明timeout、rate_limit和idempotent三个属性。这里的timeout是超时时间防止模型调用外部服务时卡死rate_limit是单位时间最大调用次数idempotent声明这个工具是否幂等也就是连续调用两次结果是否一样。这个设计是从支付系统里借鉴过来的在 Agent 场景下格外重要——模型在某一步失败后往往会重试同一个工具如果这个工具本身不是幂等的就会产生严重副作用。一个注册表条目的完整样子是这样的{ name: query_inventory, description: 查询指定SKU的实时库存数量适用于订单处理、补货建议、库存预警等场景, parameters: { type: object, properties: { sku_id: {type: string, description: 商品唯一编码如 BP-1001}, warehouse: {type: string, enum: [华东, 华北, 华南], default: 华东} }, required: [sku_id] }, examples: [ {input: {sku_id: BP-1001}, output: {available: 356, location: 华东-03-07}} ], timeout: 3.0, rate_limit: 10, idempotent: True }这段描述看起来简单但里面的门道不少。examples里我放的是完整输入和输出而不是单独放一两行参数说明。这样模型可以把“输入长什么样”和“输出长什么样”对应起来在后面的任务里能够准确地根据输出判断下一步。enum约束了参数取值范围避免模型传一个“南方仓”出来。description里写的不是“库存查询接口”而是写明“适用于订单处理、补货建议、库存预警等场景”这个场景提示非常重要它直接决定了模型在复杂任务中是否会把当前子任务和这个工具匹配上。我第一个版本的工具描述写得太简略导致模型在任务决策时经常跳过可用工具最后只会用大模型自己的“常识”假装完成任务——比如我问它库存够不够它直接回答“库存充足请放心”但实际上它根本没有查过。加上场景描述和示例之后这种“幻觉式完成任务”的情况大幅减少。2.2 上下文预算把 token 当作钱来花上下文触达这一层我把它做成了一套“预算管理”机制起名就叫做上下文预算。每次接收任务时先把整条上下文分成五个优先级区域系统指令区、目标区、状态区、数据区、历史区。系统指令区是整个上下文的骨架不能动。目标区存放当前任务的顶层目标和最近一次子目标每轮工具调用前都要重写一次。状态区记录已完成步骤和当前步骤数据区放工具返回的最新结果历史区放之前的对话过程。这样分区的核心逻辑是当上下文快满时压缩顺序从优先级低的往高走。先压缩历史区把多轮对话压缩成一句话摘要再压缩数据区把旧的工具返回结果替换成“上一步已完成结果为类型X”系统指令区和目标区要保证始终完整。我在 Agent-Reach 里写了一个简单的预算计算器def allocate_budget(system_ctx, target, state, data, history, max_tokens8000): fixed len(system_ctx) len(target) len(state) remaining max_tokens - fixed data_budget int(remaining * 0.7) history_budget remaining - data_budget return { system: len(system_ctx), target_fixed: len(target), state_fixed: len(state), data_max: data_budget, history_max: history_budget }这个分配逻辑背后有一个经验值工具返回的数据几乎总是比历史对话更重要。大多数 Agent 跑偏不是因为历史太多而是因为关键的当前状态被挤掉了。所以我把 data 区域的预算放大到 70%历史区压缩成一两句摘要。这个比例不是拍脑袋定的我在实际任务里测过当数据区低于总预算 50% 时Agent 经常出现“拿着旧数据做新决策”的问题提到 70% 后正确执行率明显上升。2.3 触达失效的三种典型模式有了分层和预算之后对触达失效的模式诊断也变简单了。我归纳出三种最常见的模式每种都有对应的处理策略。第一种是遗忘型失效。任务开始后第三四轮模型忽然不再按照最初工具链走了它开口直接回答用户的问题。比如用户问“我的订单什么时候到”Agent 查了一次物流接口第三步本应查询各节点时间它却开始凭常识推测“通常需要3-5天”。这个问题几乎都能归到上下文触达上——目标区没有每轮重写模型逐渐看不到最初的目标和任务链路。处理办法是把目标复述做成强制节点每一步之前都必须重新载入目标文本。第二种是迷路型失效。模型调用了工具但是调错了工具。比如用户要查库存模型却调用了商品信息接口。这说明工具触达的 description 写得不清楚或者是候选工具太多导致选择困难。我的办法是减少工具曝光数量把二十个工具按业务场景分组一次只给模型暴露三到五个。第三种是原地转圈型失效。模型反复调用同一个工具每次结果都一样但问题没解决。我见过一次最典型的情况模型连续五次调用query_weather查询天气却完全没有推进到“根据天气安排活动”这个目标。这种多半是状态触达缺失——模型不知道自己的状态已经停在重复动作上。处理办法是加一个状态检查器如果连续两次工具调用完全相同且结果未变化就强制切换策略。3. 手把手搭一个最小可用的Agent-Reach3.1 环境准备与目录结构Agent-Reach 的代码我全部用 Python 写的项目运行时只需要一个基础模型API和 Python 3.10。我建议在自己的项目里复用时保持这个目录结构agent_reach/ ├── core/ │ ├── registry.py # 工具注册中心 │ ├── budget.py # 上下文预算分配 │ ├── state.py # 任务状态追踪 │ └── planner.py # 目标维持与步骤规划 ├── tools/ │ ├── inventory.py │ └── order.py ├── eval/ │ ├── cases.py # 测试用例集 │ └── metrics.py # 覆盖矩阵计算 └── main.py # 主流程入口不建议把东西写在一个单文件里即使 Demo 也一样。因为 Agent-Reach 后期的核心工作是评估和调优你需要分模块观察是哪一个环节出了问题。单文件虽然跑得快但一旦出现触达失效排查起来全靠猜效率极低。3.2 主流程规划、执行、评估的闭环Agent-Reach 的主流程我设计成四段式解析任务、规划步骤、执行调用、评估结果。每一段都有对应的触达检查点。def run_task(task, registry, context): # 1. 解析并写入目标区 target extract_target(task) context context.set_target(target) # 2. 规划第一步动作 plan planner.plan(target, context.current_state(), registry.list_all()) if not plan: return {status: blocked, reason: no viable tool} # 3. 执行工具调用 for action in plan: result registry.invoke(action[tool], action[params]) context context.update_state(stepaction[tool], resultresult) if result[code] ! 0: context context.append_error(result[message]) # 4. 评估触达结果 metrics evaluate_reach(target, context, registry) return {status: done, metrics: metrics, result: context.last_result()}这里的核心是planner.plan()这个函数。它不是简单地“把任务拆成三步”而是先检查当前已有状态再决定下一步调哪个工具。我第一次实现时让模型自由发挥结果它经常跳步第一步还没完成就去执行第三步的逻辑。后来加了一个规则每次最多规划两步执行完第一步后必须重新规划这样模型每一步都有机会根据真实工具返回结果调整策略。3.3 一个完整的业务场景库存补货助手为了让这套东西能跑通我做了一个库存补货助手。场景是这样用户发来一个商品SKUAgent 需要查询当前库存、判断是否需要补货、如果需要则生成一条采购申请单。我在工具库里注册了两个工具一个是query_inventory一个是create_purchase_order。跑一遍的完整过程如下# 配置工具 registry ToolRegistry() registry.register(query_inventory_schema) registry.register(create_purchase_order_schema) # 配置上下文 ctx AgentContext(max_tokens8000) ctx.set_system(open(prompts/system.md).read()) # 执行任务 result run_task(BP-1001需要补货吗如果库存低于200就创建采购单, registry, ctx)这个场景的完整执行流转如下Agent 先调用query_inventory查到库存数量假设返回是 156然后判断 156 ≥ 阈值 200 不成立于是调用create_purchase_order生成采购单。两步之间有一个关键点目标区必须保留“库存低于200就创建采购单”这个条件否则模型可能在查询到 156 之后直接答复用户“库存不足请考虑补货”而不是真正生成采购单。实测过程中我发现一个高频问题模型在拿到query_inventory的返回后第二步生成采购单时经常漏传sku_id或者把仓库写错。后来在注册表里给create_purchase_order增加了引用说明“仓库参数必须与 query_inventory 返回的 location 字段一致”这个问题就明显减少了。这个细节很有价值很多 Agent 框架只关注“工具能不能调”却没有关注“工具返回值和下一个工具入参之间的衔接”。3.4 让状态可见调试触达问题的第一抓手我强烈建议在早期就把状态可视化做出来。Agent-Reach 里我写了一个简单的print_state函数每次工具调用后都打印出当前目标、当前状态、最近工具返回结果。状态可视化的价值在排查问题时最明显。有一次我从日志里看到模型连续三步都在调用query_inventory但每一步传入的sku_id都一样。看起来像是“死循环”实际上是因为第三步之后状态区显示“已查询库存未生成采购单”模型不知道下一步该做什么于是选了最熟悉的动作重试。把这个状态打印出来之后一眼就能看出问题出在planner没有把“生成采购单”列入候选动作。修复方案也很简单在规划限制里增加一条规则目标区出现“采购单”关键词时模型必须把create_purchase_order纳入下一步候选。状态可视化不用做得多复杂就是一个文本输出但要保证每次都打印。做 Agent 调试最大的痛点就是“看不到内部过程”模型在中间做了什么几乎全黑。有了状态输出你至少能区分是哪一层的触达出了问题。4. 用覆盖矩阵把Agent触达能力测出来4.1 Reach Case一套任务导向的测试集前面两章介绍了 Agent-Reach 的架构和实现但真正支撑整个体系的是它的评估部分。没有评估所有设计都只是“我觉得这样会更好”有了评估你才能知道改动是否真的有效。我给 Agent-Reach 设计了一套 Reach Case也就是“触达测试用例”。每条用例不是简单的问答而是包含五要素任务描述、目标工具集合、关键数据条件、预期执行路径、可接受结果。举个例子case_id: RC-001 task: SKU BP-1001当前库存是否满足未来3天的销售需求如果不满足请创建补货单 required_tools: [query_inventory, query_sales_forecast, create_purchase_order] critical_data: - sku_id: BP-1001 expected_path: [query_inventory, query_sales_forecast, create_purchase_order] acceptable_result: 创建一条采购单或明确说明库存充足这套测试集按业务场景分组每个场景里既有“完整链路”用例也有“故意缺少信息”的用例。后者更重要。故意缺少信息的用例比如不给 warehouse 参数看看 Agent 是会主动询问用户还是默认选一个还是直接报错。这三种行为对应三种不同的触达策略没有测试集的话你根本发现不了差异。4.2 覆盖矩阵一眼看出哪只手够不着有了 Reach Case 之后我设计了一个最简单的覆盖矩阵以“任务 × 能力层”为轴把每条用例的表现记录在矩阵里。矩阵的每一行是一个任务每一列是一层触达能力。完成情况分三个等级PPass、FFail、NNot Executed。P 表示该层在任务中表现正常F 表示该层导致任务失败N 表示该层在任务中不需要被触达。用例上下文触达工具触达状态触达目标触达整体结果RC-001PPPP完成RC-002PFPP失败工具调用参数错误RC-003PPFP失败重复查询无推进RC-004FPPP失败关键数据被截断这个输出方式很朴素但价值非常大。横着看矩阵你能知道每个任务卡在哪儿竖着看矩阵你能知道这个 Agent 整体的弱项在哪一层。我见过最典型的例子一个 Agent 在 20 条测试用例里12 条失败都是工具触达层的问题说明问题不在模型策略而是工具描述和注册方式本身有问题。集中修复工具注册表之后成功率立刻提升了 40% 以上。如果你连这一层都没有度量你大概率会在错误的层面调优。比如疯狂改 Prompt但问题明明出在工具描述上改 Prompt 基本是白费劲。4.3 度量的三个关键指标为了把触达能力量化到可对比的程度我用了三个核心指标任务完成率、工具调用正确率、目标保持率。任务完成率是整个流程的最终体现。它衡量的是“Agent 能否从任务 A 到达结果 B”如果这个数字低说明触达体系存在明显断点。工具调用正确率是“工具调用成功且参数合法且返回被正确使用”的次数除以总调用次数。这个指标在调试中最敏感往往注册表描述里一个微小的措辞改动就能带来 10% 左右的提升。目标保持率的定义是“整个执行过程中顶层目标未被覆盖的次数比例”。这三个指标之间也有关系需要关注。工具调用正确率很高但目标保持率很低说明 Agent “很会干活但经常干错活”——每一步的工具调用来看都对但整体方向早就偏了。反过来目标保持率很高但工具调用正确率低说明 Agent “清醒但手笨”知道要干什么但总是用错工具或传错参数。这两种情况需要的修复策略完全不同所以光看一个综合指标是不够的。我给每轮评测至少跑三次取中位数而不是平均值。因为大模型有随机性一次跑通过只能说明运气好跑三次取中位更接近真实水平。5. 现场实录Agent-Reach跑崩与修复的那些瞬间5.1 问题速查表五个高频故障我在开发 Agent-Reach 和用它测其他 Agent 时积累了一批高频问题。这里做了一个速查表标注了现象和解决思路。现象根因解决思路所在触达层模型跳过可用工具直接回答工具描述缺少场景提示在 description 中补充适用场景关键词工具触达工具返回后模型重复调用同一参数状态区未记录“该参数已查询”状态区及时写入已完成的查询记录状态触达长时间任务后目标偏移目标区没有每轮重写每一步强制载入目标摘要目标触达上下文超长后关键指令被截断历史区占用过多预算使用分区预算并限制历史区摘要长度上下文触达工具参数拼接错误但发起调用时不会报错缺少一个“参数推理”环节增加工具调用前的参数校验步骤工具触达这个表不是理论推演是我在调试过程中实际遇到的案例。尤其是第一行“模型跳过可用工具直接回答”在早期的版本里出现频率非常高。有一次我测试一个查库存的任务模型在没有任何工具调用的情况下直接回答“该商品库存正常建议保持现状”这个问题非常危险因为用户完全无法察觉模型在造假。加入场景描述之后的工具注册表这个问题基本被解决了——模型能看到匹配当前任务的工具描述就不会轻易靠惯性编造答案。5.2 模型拒调工具一个被低估的隐性坑调用工具失败还不算最麻烦的最麻烦的是模型“根本不愿意调”。大模型在对话场景里被调教得太像人了碰到模糊任务时它倾向于直接回答而不是先调用工具确认信息。我修复这个问题的方法是在系统指令里加了一条强约束“当存在可用工具且该工具能够为回答提供事实依据时必须先调用工具禁止直接作答。”这条起到了效果因为系统指令区永远保留这条规则模型每次决策时都能看到。但是加完这条约束后又出现了另一个问题模型会“过度调用工具”。用户问“今天天气怎么样”系统里有天气工具模型调用了问“你好”它也调用了天气工具。这就是把“先调用工具”变成了“每次都调用工具”。后来我在系统指令里补了一句限制“仅当当前问题需要外部事实数据支撑时才调用工具对于问候、闲聊、通用知识问题不需要调用工具。”两条指令放在一起行为才达到平衡。这说明触达能力不是越大越好而是越准越好。Agent-Reach 这套方案从一开始就没有追求“能调的工具越多越好”而是追求“该调的时候一定调不该调的时候坚决不调”。5.3 上下文压缩导致指令丢失一个典型事故这个事故我想特别写出来因为它是 Agent 开发中一个很隐蔽的坑。有一次我测试一个多步骤任务需要 Agent 先查两个 SKU 的库存再分别比较最后生成采购订单。跑第一遍时一切正常第二遍却在第三步出现了“模型忘记对两个 SKU 进行比较”的问题。查日志发现上下文在第二步时因为长度接近预算上限触发了压缩逻辑把目标区里“比较两个 SKU 的库存”这个子目标给压缩掉了。压缩逻辑本身没有错但这个事故暴露出一个问题当上下文压缩发生时我没有保护目标区。在那之后我改进了压缩规则——五层区域里系统指令区和目标区是固定碎片不参与压缩能压缩的只有历史区和部分旧数据区。这个改动看起来小但效果巨大保证了长任务中目标不丢失。这个事故也提醒了我一个重要的经验Agent 和普通函数调用不同它的上下文是动态变化的你在开发时写得再完善的指令也可能在运行中途被其他内容挤掉。因此所有关键指令不仅要写进系统提示还要在代码层面做强制保护。所谓“强制保护”就是把目标写入代码控制的数据结构而不是只放在文本提示里。5.4 让工具返回“说人话”强化状态触达最后一个小经验也是最容易被忽略的。工具返回值的格式直接影响 Agent 后续决策的质量。很多现有 API 返回的是数据库原样字段比如status: 1、flag: N对机器来说没问题但对大模型来说非常不友好。模型要去猜1代表什么、N代表什么。而另一个更大的问题在于如果这个状态码在模型预训练语料里不常见它就会产生各种奇怪的解读。Agent-Reach 里我加了一层“工具出口翻译层”。每个工具调用完成后把返回结果转换成自然语言摘要。query_inventory返回原始 JSON{available: 156}时出口翻译层把它转成一句话“SKU BP-1001 在华东仓当前可用库存为 156 件低于补货阈值 200 件建议补充采购。”这样模型下一步决策的质量就明显地提升了。这个改动甚至不需要大改框架就是在工具注册表里加一个response_summarizer字段每个工具注册时配套写一个摘要函数。算是我在 Agent-Reach 里投入产出比最高的一个优化了。6. 关于Agent-Reach我的最终建议如果你准备在自己的项目里用这套思路我的建议是不要一开始就追求完整的框架先搭一个最小版本跑通三个核心能力点工具注册表、上下文预算、Reach Case 评估。这三个点串联起来你就有了一个能度量、能诊断、能迭代的 Agent 开发闭环。我在使用中发现定期跑一遍 Reach Case 非常有用尤其是每次调整 Prompt、工具描述或上下文管理逻辑后都跑一遍。它能让你在问题恶化之前就发现而不是等到线上用户反馈了才手忙脚乱地查日志。你不需要一开始就准备几十上百条用例五条核心用例就够用了覆盖你产品最主要的三到五个场景。再分享一个小技巧把每一轮的“目标区”和“状态区”打印出来存档。这些数据是后续调优最重要的依据比对话记录本身更有价值因为它记录了模型在每个决策点的“出发点”和“当前位置”。有了这些数据很多质量问题都能立刻定位到具体触达层而不是在模型能力上做无用功。Agent-Reach 这个项目本身不算复杂但它的价值在于把“Agent 能力边界”从一个模糊的形容词变成了一组可操作的结构。希望这篇文章能帮你在做 Agent 落地时少走一些弯路。