做AI应用这一年多，我越来越强烈地感觉到一个矛盾：大模型的智商越来越高，但每个Agent真正能“摸到”的东西却少得可怜。你给它一个任务，它的大脑确实足够聪明，可手边只有一把螺丝刀，再聪明也只能反复拧螺丝。所谓Agent-Reach，说白了就是研究怎么把这只“手”伸得足够远、足够准——让Agent能触达它需要的工具、数据和协作对象。这个项目我前后迭代了三轮，从最开始只能调两三个API的小玩具，做到现在能同时调度几十个工具、跨多个数据源取数、还能在出错时自己换方案的工程化系统。这篇文章把完整的设计思路、踩过的坑、以及我反复调整后的最终架构都记录下来，给同样在做Agent落地、尤其是被工具调用和上下文管理折磨的朋友一些参考。
我要先说清楚一个容易被忽视的事实：Agent的能力上限，很多时候不是模型决定的，而是它的“触角”决定的。模型再聪明，看不到的数据就是不知道，调不到的工具就是干不了。Agent-Reach的核心工作就三件事：让Agent看得更广（数据接入）、够得更远（工具调用）、记得更牢（记忆管理）。下面我从头到尾拆一遍。
1. 为什么“智能体的触角”决定能力上限
1.1 一个业务员的类比
想象你手底下有个特别能干的业务员，口才一流、脑子转得快、谈判技巧拉满。但如果你只给他一部通讯录，里面就三个号码，他能谈成的生意注定有限。你给他加一个行业人脉库，他能约到更多客户；再给他配一个产品报价系统，他能在现场直接给方案；再让他能随时调用财务、法务、供应链的同事，他就能处理真正复杂的订单。Agent-Rach做的就是这件事——给模型这个“超级业务员”配上足够多的号码、系统和协作通道。
这个类比不是随便打的。我见过太多团队把精力花在调prompt、换更强模型上，结果瓶颈根本不在推理能力，而在Agent的外部接口太少、太脆。你让它写一份行业分析报告，它写得挺好；你让它去查实时行情、调内部数据接口、把结果整理成表格发给指定邮箱，它直接卡死——因为后面这些动作需要“够得着”外部世界。
1.2 我在第一版踩的跟头
我最早做的Agent-Reach原型特别简陋：五个工具，两个数据库查询，一个HTTP请求封装，再加一个文件读写。当时测试效果很不错，模型基本指哪打哪。于是我很膨胀，一口气把工具加到二十多个，结果准确率肉眼可见地往下掉。
当时的表现很典型：模型开始搞混相似工具，比如把“查询用户订单”调成“查询用户资料”；有时候压根不调用工具，直接凭训练记忆瞎编数据；还有的时候它选择了正确的工具，但参数格式传错了。我一开始以为是模型不够聪明，后来排查才发现，是我自己犯了个经典错误——工具一多，选择难度非线性上升，而我没有任何路由机制帮模型做决策。
这个经历让我重新理解了Agent-Reach的真正含义：不是把工具堆得越多越好，而是要建立一套机制，让Agent在庞大的工具集和数据源里，用最低的试错成本找到正确的那一个。单纯的“多”没有意义，“准”才有。
1.3 “Reach”的定义：一个可度量的能力空间
在工程上，我给Agent-Reach下了一个可执行的定义：一个Agent实例能够直接访问、并通过动作影响的外部空间集合。它包含四个维度：
- 工具层：能调用的API、函数、服务，比如订单查询、天气接口、内部工单系统
- 数据层：能读取的数据库、文档库、文件系统、网页内容
- 记忆层：能跨会话保留和检索的历史信息、项目上下文、用户偏好
- 协作层：能触达的其他Agent或人工审核通道
这个定义最大的好处是，它把“这个Agent强不强”从玄学变成了可测量的问题。你可以给每个维度打分，然后精准定位系统短板：如果模型经常答非所问，可能是数据层不够；如果模型推理正确但执行失败，可能是工具层封装有问题；如果同一件事换个时间问它就不记得了，那是记忆层缺失。后续所有优化都是围绕这四个维度展开的。
2. 从“单点Agent”到“网状Reach”：整体架构拆解
2.1 单体Agent为什么扛不住
很多入门教程教你写的Agent其实是单体结构：一个循环，模型思考→调用工具→观察结果→再思考。这种结构在工具少、任务单一的时候完全够用，但一旦Reach范围扩大，就会出三个问题。
第一，决策与执行耦合。模型既要决定“调哪个工具”，又要负责“怎么调”，两步都挤在一个上下文里，容易互相干扰。第二，上下文迅速膨胀。每调用一个工具，结果都要塞回对话历史，多调几次，上下文窗口就满了，早期的关键信息被挤掉。第三，错误无法隔离。一个工具超时或返回脏数据，会污染整个链条，模型接下来的每一步都在错误的基础上做推理。
所以我在第二版直接推倒重来，把架构拆成了清晰的层次。
2.2 Agent-Reach的最终架构
整体分五层，从上往下看：
| 层级 | 职责 | 核心组件 |
|---|---|---|
| 协调层 | 拆解任务、决定下一步行动、判断是否完成 | Planner、Orchestrator |
| 路由层 | 从工具注册中心里选最合适的工具、校验参数 | Router、Tool Registry |
| 执行层 | 真实调用外部API、数据库、脚本 | Tool Executor |
| 数据层 | 统一各种数据源的接入方式，屏蔽差异 | Data Adapter |
| 记忆层 | 分层存储和检索会话、项目、长期知识 | Memory Manager |
数据流的走向是这样的：用户任务进入协调层，Planner先生成一个大致的执行计划；路由层根据当前这一步的需求，去工具注册中心检索候选工具；选定后由执行层真实调用；调用结果经过数据层标准化后，写回记忆层，再返给协调层判断下一步。关键改动在于——模型不再直接面对几十个工具的原始描述，它面对的是路由层筛选后的两三个候选，决策负担大大减轻。
2.3 为什么“决策”和“执行”必须分离
这个设计理念是我踩坑踩出来的。第一版里，模型的prompt里塞了所有工具的JSON Schema，让它自己挑。工具少的时候没事，工具一多，模型的选择准确率急剧下降，而且每次推理都要重新“读”一遍所有工具描述，token消耗也高。
把“选工具”这个动作单独抽出来做成路由层之后，有三个立竿见影的好处。第一，模型上下文里只需要出现“这一步要做什么”，而不是“所有可能的做法”，信息密度更高。第二，路由层可以独立优化，比如用本地小模型做粗筛、用向量检索做召回、再用规则校验兜底，而不用动主模型。第三，路由层可以记录每次选择的命中率，形成反馈数据，慢慢调优工具描述和权重。
三层分离之后，整个系统的可维护性上了个大台阶。以前改一个工具要重新测一整套流程，现在只需要在注册中心改一条元数据。
3. 工具注册与动态路由：让Agent学会“够得远”
这一层是整个Agent-Reach的地基，也是我投入时间最多的部分。工具注册中心看着不起眼，但它直接决定模型能不能在关键时刻选对工具。
3.1 用统一Schema描述工具，拒绝自由发挥
我见过很多团队的工具描述写得特别随意，有的写“这个函数用来获取用户信息”，有的干脆只贴一个函数签名。这在工具少的时候无所谓，工具一多，模型根本分不清“获取用户信息”和“获取用户订单”到底有什么区别，参数也容易传错。
我在Agent-Reach里给每个工具定义了一份结构化元数据，用JSON Schema承载，包含：工具名称、一句话功能摘要、详细描述（什么时候该用、什么时候不该用）、参数定义（类型、必填、枚举值、示例）、返回值结构、错误码表。
TOOL_SCHEMA = { "name": "query_user_orders", "summary": "查询用户的历史订单列表", "description": ( "当需要获取某个用户在某段时间内的订单记录时使用。" "注意：该接口只返回已支付订单，不含未支付或已取消的单。" "如果需要查询订单的物流状态，请使用 query_order_logistics。" ), "parameters": { "type": "object", "properties": { "user_id": {"type": "string", "description": "用户唯一标识"}, "start_date": {"type": "string", "format": "date", "description": "开始日期，如2024-01-01"}, "end_date": {"type": "string", "format": "date", "description": "结束日期，如2024-06-30"} }, "required": ["user_id"] }, "return_schema": { "type": "array", "items": { "type": "object", "properties": { "order_id": {"type": "string"}, "amount": {"type": "number"}, "status": {"type": "string", "enum": ["paid", "refunded", "shipped"]} } } } }这份Schema看起来啰嗦，但它至少解决三个问题：一是给路由层提供了检索和排序的依据；二是给模型提供了足够的语义信息来区分相似工具；三是执行层的参数校验可以直接复用这套定义，不用另写一套。我建议所有工具都按这个模板补齐，特别是“什么时候不该用”和“和相似工具的差异”这两项，能显著减少模型选错工具的概率。
3.2 路由层：先粗筛、再精排、最后兜底
路由层的设计是我调了很久才稳定下来的，目前是三段式流水线。
第一段是粗筛，用关键词匹配加常用工具优先，从注册中心里快速捞出一批候选。这一步不追求精确，只求别漏掉正确工具。第二段是精排，把这一步的任务描述和候选工具的summary、description做向量相似度计算，按分数排序，取Top 3。第三段是规则校验，检查这Top 3里有没有参数明显对不上的，比如任务里根本没有user_id这个字段，而某个工具必填参数就是user_id，那就把分数往下压。
粗筛和精排的代码实现大概是这样的：
def route_tool(task_step_description: str, registry: ToolRegistry, top_k: int = 3): # 第一阶段：粗筛，用关键词和标签缩小范围 candidates = registry.keyword_search(task_step_description) if not candidates: candidates = registry.get_default_tools() # 第二阶段：精排，向量相似度计算 query_embedding = embed(task_step_description) scored = [] for tool in candidates: tool_embedding = embed(tool.summary + " " + tool.description) score = cosine_similarity(query_embedding, tool_embedding) # 第三阶段：规则兜底，参数匹配度作为惩罚项 param_penalty = 0.0 required_params = tool.parameters.get("required", []) for p in required_params: if p not in task_step_description: param_penalty += 0.1 scored.append((tool.name, score - param_penalty)) scored.sort(key=lambda x: x[1], reverse=True) return [name for name, _ in scored[:top_k]]这套三段式方案上线后，工具选择准确率从之前的六成多恢复到九成以上。而且它还有一个好处：每段都可以用不同的模型，粗筛和精排甚至可以用不上大模型的本地算法完成，只有最终把Top 3候选塞进主模型prompt时才需要花钱推理。
3.3 工具描述的艺术：别写说明书，写决策卡
写工具描述的时候，大部分人容易陷入两种极端：要么太简略，比如“获取订单信息”；要么太啰嗦，把实现细节、历史原因全写进去。我的经验是，工具描述本质是给模型看的“决策卡”，它需要的是“什么场景选我、什么场景别选我”，而不是“我内部是怎么实现的”。
举个例子，“查询用户订单”和“查询用户订单详情”这两个工具，如果描述都只写“查订单”，模型完全分不清。我后来把前者写成“返回用户订单列表，只包含订单编号、金额、状态等概要信息，适合展示列表”，把后者写成“基于订单ID返回单个订单的完整详情，包括商品明细、收货地址、支付流水，适合需要完整信息的场景”。改动之后，选择准确率立竿见影。
我还养成了一个习惯：每跑一批任务，就把路由层选错的case收集起来，分析是描述问题还是参数问题。描述问题就改元数据，参数问题就改Schema，积累两个月，工具描述的迭代速度会非常快。
4. 记忆与上下文扩展：越过窗口限制拿数据
4.1 上下文窗口是Agent最硬的物理瓶颈
不管你用哪个模型，上下文窗口都是有限度的。你可以说“无限上下文”是趋势，但在实际工程里，塞得越多，推理越慢、费用越高、准确率反而下降。所以Agent-Reach的第四个重点维度是：让Agent在有限窗口内，拿到它真正需要的信息。
我见过不少项目把整份对话历史一股脑塞给模型，美其名曰“保留上下文”，结果几千个token全是废话。解决这个问题的思路不是无脑堆窗口，而是把记忆分层，每层各司其职。
4.2 三层记忆架构：工作记忆、项目记忆、档案记忆
我最终落地的方案是三层记忆，每一层的存取策略完全不同。
工作记忆（Short-term）：只放当前任务正在处理的中间状态，比如已经执行完哪些工具、当前还差哪些信息、下一步计划是什么。它的特点是短小精悍，每次迭代都会更新，最多不超过当前任务范围。
项目记忆（Project-level）：跨会话保留某个项目的重要决策和约束。比如“这个客户的订单查询必须用V2接口”“这个报表的金额字段单位是分，展示时要转成元”。项目记忆是针对性的，只在下一次会话开始时注入，避免每次都要重新交代背景。
档案记忆（Long-term）：把历史对话、文档、工具调用日志向量化后存入数据库，按需检索，而不是全量注入。这一步本质上是一个小型的检索增强生成（RAG）系统，只不过检索的对象是Agent自己的历史经验。
class MemoryManager: def __init__(self, vector_store): self.working = {} self.project = ProjectMemory.load() self.archive = vector_store def get_prompt_context(self, task_id: str, task_description: str): # 工作记忆：当前任务的执行状态 working_ctx = self.working.get(task_id, {}) # 项目记忆：和当前任务相关的项目约束 project_ctx = self.project.get_relevant(task_description) # 档案记忆：检索历史相似任务的执行经验和结果 archive_ctx = self.archive.search(task_description, top_k=5) return { "working": working_ctx, "project": project_ctx, "archive": archive_ctx } def update_after_step(self, task_id: str, step_result: dict): self.working[task_id]["last_step"] = step_result if self.working[task_id].should_archive(): self.archive.add(self.working[task_id])三层记忆分开管理之后，我发现prompt的体积平均下降了百分之四十以上，而任务完成率反而升了。原因是模型不再被海量无关信息干扰，注意力更集中。
4.3 让Agent“忘记”有时比记住更重要
这里说一个反直觉的经验：记忆系统最难的其实不是“存”,而是“删”。如果你不主动清理，过期的、错误的、重复的信息会像垃圾一样堆积，污染每一次推理。
我踩过一个具体的坑：有一次系统把某客户三个月前的订单状态当成最新状态返回给用户，用户投诉之后我一查，发现是档案记忆里的一条旧记录被检索出来，而且它的相关度分数比新记录还高。问题出在向量检索只比相似度，不比时间新鲜度。修复方案是给每条记忆加了时间字段，检索时把时间衰减系数乘进去。这个改动看起来小，但直接避免了一整类数据新鲜度事故。
所以现在我的记忆层有一条铁律：检索结果必须带时间权重，工作记忆必须高保真，档案记忆必须可丢弃。宁可让模型说“我不知道”，也不能让它拿着过期数据一本正经地胡说。
5. 实战踩坑：工具调用超时、上下文污染与幻觉的排查记录
写这套系统的过程，本质上就是一段接一段的排错史。我觉得把这部分单独拿出来讲，比直接给一个“完美架构”更有价值，因为坑才是这个项目真正的老师。
5.1 工具调用超时：模型为什么会在一个失败点上反复横跳
第一次做Agent-Reach的时候，我给工具调用设了一个很简单的封装：直接调用，等返回结果。有一次一个第三方API响应特别慢，超过了模型的等待阈值，返回的是个超时错误。这里我本来以为模型会换个方案，结果它做了一件特别蠢的事——用一模一样的参数再调一次同一个工具，然后又超时，又调，循环了好几次，白白浪费了几分钟和一堆token。
排查下来，问题不在于模型笨，而在于我没有给它足够的信息来做出“换方案”的判断。超时错误只说了“request timeout”，模型不知道这个超时是暂时的还是永久的，也不知道有没有备用接口可用，它只能机械地重试。
修复分两部分：第一，给所有工具调用包了一层统一的执行器，内置超时控制和重试策略；第二，把异常信息转换成对模型友好的结构化反馈。
import time import concurrent.futures def execute_with_fallback(tool_func, params, timeout=10, max_retries=2): for attempt in range(max_retries): try: with concurrent.futures.ThreadPoolExecutor() as pool: future = pool.submit(tool_func, **params) result = future.result(timeout=timeout) return {"success": True, "result": result} except concurrent.futures.TimeoutError: if attempt < max_retries - 1: time.sleep(2) continue return { "success": False, "error": "TIMEOUT", "suggestion": "接口响应超时。可尝试：1. 缩小查询时间范围；2. 改用batch接口；3. 直接告知用户稍后重试。" } except Exception as e: return {"success": False, "error": str(e)}改动之后，模型看到的是“接口超时，建议缩小查询时间范围”，它就真的会去缩小参数范围再试，而不是原地打转。这个教训让我明白了一件事：给模型反馈错误的时候，一定要带上可执行的下一步建议，否则它只能瞎猜。
5.2 上下文污染：同一个Agent会话里执行风马牛不相及的任务会怎样
第二个大坑和记忆层有关。早期版本里，我把所有任务的中间结果都存在同一个工作记忆区，想着“反正对话是连着的，共享天经地义”。结果有一次，同一个会话里先让Agent分析了一份财务报告，又让它写了一段营销文案。两个任务完全不相关，但写文案的时候，模型居然引用了财务报告里的数据，还煞有介事地编了个用户画像出来。这就是很典型的上下文污染。
排查之后我发现根源在于：工作记忆分区太粗，不同任务的中间状态混在一起。模型的注意力机制天然会去关联最近的信息，一旦它发现“上一个任务提过这个数字”，就可能把它当成当前任务的上下文。
修复方案是把工作记忆按task_id做严格隔离，每次任务切换时清空上一层的工作记忆，只保留项目记忆里明确标记为“全局可用”的约束。此外我在prompt里也加了一条指令：“如果当前任务和之前任务主题不同，不要在推理中引用之前的任何数据”。双重保障之后，类似问题基本绝迹。
5.3 幻觉出一个不存在的工具
这是最让我哭笑不得的一个bug。有段时间模型频繁调用一个我从来没注册过的工具，叫“search_weather_in_city”，而我整个系统里根本没有天气相关接口。
一开始我以为是自己注册遗漏了，翻遍代码也没有。后来问模型为什么选这个工具，它的回答是“根据函数名推断，这个工具应该存在”。这句话一下点醒了我：当工具库里工具数量膨胀、描述又不够清晰时，模型会把“功能名”当成“真实存在的东西”。它在语义上觉得天气查询应该有个工具，于是就在幻觉里生成了一个。
这个坑的修复分三层。第一层，路由层兜底：任何工具调用必须经过工具注册中心验证，名字不在注册表里的直接拒绝，不能放行到执行层。第二层，传递给模型的工具列表只保留Top候选，而不是全部，从源头减少“幻觉空间”。第三层，在系统提示词里加一条硬规则：“只能调用工具列表中明确存在的工具，如果列表中没有合适工具，必须明确说明无法完成，不得臆造工具名。”此后这个问题从频发变成了偶发，再后来基本消失。
我把这三个排查案例放在一起，是想说一个共性：Agent的很多“蠢行为”，根源不在模型，而在系统没有提供足够清晰的边界信息。你把边界划清楚，模型自然就走准了。
6. 性能与成本权衡：扩大Reach的同时别让账单爆炸
6.1 Reach范围扩大后，成本为什么失控
工具越多、记忆越多、路由越复杂，单次任务的token消耗和延迟都会上台阶。我有段时间只盯着功能正确率，完全没管成本，结果月底看账单吓了一跳：一个看起来并不复杂的“用户订单分析”任务，因为反复调用工具、每次把大量历史记录回灌进prompt，一次就要烧掉接近两块钱人民币。这在生产环境是根本跑不起的。
后来我逼着自己把一个完整任务的成本拆开看，才发现大头不在于主模型的推理，而在于三件事：工具调用结果反复注入上下文、路由层的多次向量检索被重复计算、以及失败重试带来的额外轮次。
6.2 实测成本拆解：一次多步骤任务的账单明细
以“查询某个用户的订单，统计每月消费金额，并生成一段总结”这个任务为例，我记录了改造前后的实际token消耗和预估成本（按常见商用模型价格估算，粗略折算）：
| 环节 | 改造前Token消耗 | 改造后Token消耗 | 原因 |
|---|---|---|---|
| 系统提示词+工具列表 | 4200 | 900 | 只注入Top工具，而非全部 |
| 任务规划 | 600 | 600 | 不变 |
| 工具路由 | 1200 | 300 | 路由独立到小模型，不占主模型上下文 |
| 工具调用结果 | 3500 | 1500 | 只保留结构化摘要，不塞完整原始报文 |
| 历史记忆回灌 | 2800 | 700 | 按需检索，搞掂时间衰减 |
| 最终生成 | 800 | 800 | 不变 |
| 合计 | 13100 | 4800 | 约节省63% |
这个对比不是说改造前后功能变了，而是同样的功能，用更聪明的架构省掉了那些“模型不需要看但还是塞进去”的token。
6.3 我用的四个降本手段
第一，提示词缓存。系统提示词和工具Schema基本是常量，用支持缓存的服务端方案后，这部分token不再重复计费。第二，结构化摘要替代原始报文。工具返回的原始数据往往又长又杂，我在执行层过滤一遍，只保留任务相关的字段并压缩成要点，再喂给模型。第三，路由分层。粗筛和精排用本地模型或纯向量计算，只有需要模型决策的最后一步才走大模型。第四，并发与批处理。独立工具调用之间没有依赖关系时，用并发方式一起发出去，既省时间又省重试成本。
这几件事做下来，同样任务的平均成本降了大半，延迟也从七八秒降到三四秒。这里我给一个建议：做Agent项目一定要把token消耗分成“必要消耗”和“浪费消耗”两类。必要消耗是模型真正推理要花的，浪费消耗是信息冗余、重复注入、失败重试造成的。你优化的方向不是让模型“少思考”，而是把该给它的给它，不该给的坚决不给。
6.4 什么情况下值得扩大Reach，什么情况下不应该
最后说一点关于边界的思考。Agent-Reach不是越大越好，它是有边际效应的。我见过有些团队逢接口必接、逢数据必连，结果工具列表几百个，路由层自己都跑不动了。我的判断标准是：一个工具或者一个数据源，如果在可预见的三个月内不会被用到三次以上，就不值得接入。让它作为可动态加载的插件留在仓库里，比塞进在线系统的注册中心要明智得多。
反过来，如果某个数据源是核心业务流程反复依赖的，那就必须接得深一点，包括缓存、监控、降级方案都要配齐。Reach的深度应该跟着业务价值走，而不是跟着好奇心走。
最后聊两句
Agent-Reach这个项目做到现在，要说最值钱的心得，不是某个架构多优雅，而是一句很朴素的话：Agent的边界是你画的，它的能力只能在你画的边界里兑现。你想让它触达更多，就要把触达的路径铺得足够清晰；你想让它记得更牢，就要把记忆的层次分得足够干净。如果你也正在被工具调用不准、上下文塞不下、成本越跑越高这些问题折磨，不妨先别急着换更强的模型，回头把Reach这套体系重新捋一遍，很多问题会自己解开。这条路我还在继续走，后面有新的进展再来更新。
