Agent-Reach 这个名字听起来像是一个框架或者平台但实际上它是我在处理AI Agent落地时攒出来的一套编排层方案。简单说它解决的是一个问题你的Agent知道该干什么但它“够不着”需要的工具和数据。把Agent从只能聊天的状态变成真正能动用企业内部系统、第三方API、数据库、文档库的干活状态中间缺的正是这一层能力调配。这个项目是我在过去大半年里在一个中型团队里从0搭起来的踩了无数坑也验证了不少思路今天拿出来聊一聊。先给刚接触Agent开发的同学一个定位Agent-Reach不是某个大模型也替换不了RAG或者向量库它更像是一个大脑和手脚之间的“神经传导层”。你给它一个用户请求它负责判断该调哪个工具、按什么顺序调、哪些信息需要留、哪些需要丢、权限怎么控制、调用失败怎么办。它最适合三类人一类是在做企业内部知识助手、想让Agent真的操作业务系统的工程师一类是做自动化工作流的团队被各种工具调用混乱搞到头大还有一类是准备把Agent从Demo推向生产环境、开始考虑稳定性和安全性的技术负责人。这个项目的核心价值说到底就是把“工具调用”这层做成了可信赖的基础设施而不是一段到处复制粘贴的胶水代码。下面我按照当时的设计和落地过程把思路、结构、实操和踩坑都拆开讲。1. 整体设计与思路拆解为什么Agent需要一个“够得着”的中间层1.1 我是怎么被逼着做Agent-Reach的场景很典型——我们团队做了一个基于大模型的业务助理最初只接了一个知识库问答效果还凑合。后来产品要往上加需求帮用户查订单状态、提交审批、计算项目工时、查询库存水位甚至通过API去修改配置。第一个版本我直接把工具函数写死在系统提示词里看起来好像每个功能都能用结果一上线就出了大问题Agent经常把“查订单状态”和“查物流轨迹”混在一起明明有库存查询接口它偏要猜更头疼的是有一次它竟然在没有权限确认的情况下调用了删除配置的API。那个版本的代码逻辑是简单的但整个系统的可信度瞬间崩塌。那时候我开始意识到问题不在模型本身而在模型和工具之间缺少一个交通警察。交通警察要干的事是弄清楚每个路口通往哪里、谁可以走这条路、怎么根据车的去向安排最快的线路。放到Agent体系里就是工具注册、权限判断、路由选择和结果整理。这就是Agent-Reach的起点。1.2 Agent执行失败的三个根因你会发现Agent拿到任务后表现不稳其实根子往往不在模型智商而是这三个地方第一个是工具碎片化。团队里不同模块的工具各自定义参数格式、错误码和字段命名Agent看到的是几十个参差不齐的函数别说大模型人看着都头大。就好比你让一个人去仓库里找货既不告诉他货架号也不告诉他货品单位他只能靠猜。第二个是上下文膨胀。每一轮对话都把大量工具描述、返回结果塞进上下文问题很快就出现了——要么超长截断要么关键信息被淹没。相当于一个人手里拿着二十张纸条每张都写满字但只有半句话有用。第三个是权限模糊。工具没有声明自己的权限等级Agent也没有判断依据结果就是“能调的都能调”这离事故只有一步之遥。1.3 Agent-Reach的核心设计目标针对上面三个根因我立了三个设计目标第一统一工具协议所有工具按同一套schema注册描述内容标准化。第二引入路由决策Agent不是直接从工具列表里选而是通过一个路由层做评分和排序。第三把权限控制和审计从业务代码里剥离出来统一在这一层执行。一句话总结Agent-Reach的定位是“让Agent的每一次工具调用都有据可依、有迹可循、有权限边界”。这个设计带来一个很实际的收益——后续每接入一个新工具不用改Agent的核心逻辑只需要做一次注册写清描述、类型、参数、权限等级剩下的路由、校验、重试都由Agent-Reach接管。团队的开发效率明显提升接入新功能的时间从一周缩到了半天。2. 核心细节解析与实操要点工具注册、路由策略、权限审计2.1 整体架构分层Agent-Reach在逻辑上分成三层接口网关层、路由决策层、执行适配层。接口网关层负责接收Agent传来的自然语言目标和上下文压缩包做基础校验比如用户身份、会话ID、目标中是否带有敏感词。路由决策层是核心它要做两件事一是从工具注册表里筛选出候选集二是对候选集做相关性评分最终决定调谁、不调谁。执行适配层负责把路由结果转成具体工具的参数处理鉴权票据、调用外部API或内部函数再把结果按统一格式回传。我见过不少团队把这三层混在一起代码量看着不多但调试起来非常痛苦因为分不清是模型决策错了还是执行报错了。分开之后每一层的日志可以单独追踪排查问题快得多。2.2 工具注册表的Schema设计工具注册表是整个Agent-Reach的心脏。我的经验是schema不能太自由至少要包含这几个字段tool_name全局唯一只能用英文和下划线例如get_order_status。description用一句话说清这个工具干什么尽量包含“何时用”和“何时不用”两个信息。比如“当用户询问订单配送进度时使用当询问退换货政策时不要使用”。parametersJSON Schema格式的参数定义每个参数要注明是否必填、类型、取值范围、示例值。permission_level读操作、写操作、高风险操作三档例如select对应读、update对应写、delete对应高风险。timeout_ms和rate_limit给工具执行设超时和限流。handler指向真正执行函数或HTTP接口。这里有个容易被忽略的细节——description不要写太长也不要写太抽象。我们测试下来一个40到80字的描述既能让模型准确理解又不会占用太多上下文。写得像“提供订单信息查询服务”这种模型还是会在多个订单类工具之间选错写成“当用户需要查看订单当前状态未支付 已支付 已发货 已完成时使用订单列表查询用另一个工具get_order_list”准确率能提升不少。2.3 路由策略从意图匹配到评分排序路由决策层的设计我当时试过两种思路。第一种是纯函数规则用关键词实体匹配筛选候选工具。比如query里出现“订单”就拉出get_order_status和get_order_list。这种方案胜在快和可解释但缺陷是遇到自然语言变化就失灵比如用户说“我的快递到哪了”你很难直接从关键词里匹配到“订单”。第二种是基于模型打分。把query和候选工具的description拼接起来让模型输出0到100的匹配度和选择理由。这个方案更准但每次路由会有额外延迟和成本。我最后采用的是混合方案先用规则缩小候选集到最多5个再由模型在候选集里做二次精确选择。这样既控制了cost和latency又保证了准确率。还有一点值得说——不要让Agent直接对原始工具列表做“最后一跳”选择。因为一旦工具超过十几个无论多强的模型都会开始犯错。把工具列表缩小到3到5个再做选择准确率提升非常明显我们内部做过统计top1准确率从68%提升到了90%以上。2.4 权限隔离与审计追踪权限这块是上生产环境前必须处理的。我的做法不是给Agent“授权”而是给任务“临时授权”用户提出请求后Agent-Reach先根据permission_level判断这次调用是不是高风险如果是就把工具调用的完整参数返回给前端要求用户二次确认。确认后生成一个有效期5分钟的一次性token执行完之后立刻作废。这一招在内部Demo上和真实业务场景中都很有效。它不会让用户觉得流程烦琐反而会提升信任感因为用户能看到Agent到底要拿他的身份去做什么。另外每一次工具调用无论成功失败都会写一条审计日志字段包括用户ID、会话ID、query摘要、路由候选集、最终选择、参数、耗时、错误信息。这些数据一方面用来排查问题另一方面后来也成了我们优化路由策略的重要依据。3. 实操过程与核心环节实现从注册到路由再到执行的完整闭环3.1 环境准备与项目结构Agent-Reach用Python实现因为这个生态里处理JSON Schema和调用大模型最顺手。核心依赖只有三个pydantic做参数校验、httpx做异步HTTP调用、任意的模型客户端SDK我用的是兼容OpenAI格式的接口所以切换模型时不用改代码。项目结构大概是这样的agent_reach/ ├── core/ │ ├── registry.py # 工具注册表 │ ├── router.py # 路由决策 │ ├── executor.py # 工具执行与重试 │ └── context.py # 上下文压缩与预算 ├── tools/ │ ├── order.py # 订单域工具 │ ├── inventory.py # 库存域工具 │ └── approval.py # 审批域工具 ├── config.yaml # 限流、超时、模型配置 └── main.py # 入口编排3.2 定义工具注册表先写一个工具注册的装饰器让团队成员可以很方便地把一个普通函数注册成Agent-Reach工具。这段代码是整个项目的第一块基石# agent_reach/core/registry.py import inspect from typing import Callable, Dict, Any class ToolRegistry: def __init__(self): self._tools: Dict[str, Dict[str, Any]] {} def register( self, name: str, description: str, parameters: dict, permission_level: str read, timeout_ms: int 5000, rate_limit: int 10, ): def decorator(func: Callable): self._tools[name] { name: name, description: description, parameters: parameters, permission_level: permission_level, timeout_ms: timeout_ms, rate_limit: rate_limit, handler: func, } return func return decorator registry ToolRegistry()注册一个业务工具时只需要这样写from agent_reach.core.registry import registry registry.register( nameget_order_status, description当用户需要查看订单当前状态未支付/已支付/已发货/已完成时使用 订单列表查询请使用另一个工具get_order_list不要混用。, parameters{ type: object, properties: { order_id: {type: string, description: 订单号形如ORD2024001} }, required: [order_id] }, permission_levelread, timeout_ms3000, rate_limit30, ) def get_order_status(order_id: str): # 这里是真实业务调用查DB或者调内部API return {order_id: order_id, status: 已发货, logistics: 顺丰SF123456}这里有两个实操心得参数定义里一定要给示例值pydantic校验错误提示会友好很多description里明确写“不要用”的情况等于帮模型在候选阶段做了一次负样本划分。3.3 实现路由决策模块路由模块要做的事是接收用户目标文本先规则缩小候选集再让模型在候选集里打分。我写了一个简化版本# agent_reach/core/router.py import json from agent_reach.core.registry import registry class Router: def __init__(self, model_client): self.model_client model_client def _rule_filter(self, query: str, max_candidates: int 5): 先用简单关键词规则缩小范围控制后续模型打分成本 scored [] for tool in registry._tools.values(): score 0 desc tool[description].lower() query_lower query.lower() keywords [订单, 库存, 审批, 项目, 物流, 退款, 价格] for kw in keywords: if kw in query_lower and kw in desc: score 1 if score 0: scored.append((score, tool)) scored.sort(keylambda x: -x[0]) return [tool for _, tool in scored[:max_candidates]] def _model_choose(self, query: str, candidates: list) - str: 让模型判断哪个工具最匹配当前请求 if not candidates: return None candidate_text \n.join( f{t[name]}: {t[description]} for t in candidates ) prompt ( f用户请求{query}\n\n f可用工具列表\n{candidate_text}\n\n 请返回一个工具名不要解释。 ) response self.model_client.chat( messages[{role: user, content: prompt}], temperature0, ) return response.strip() def route(self, query: str): candidates self._rule_filter(query) if len(candidates) 1: return candidates[0] tool_name self._model_choose(query, candidates) return registry._tools.get(tool_name)这里有一点关键temperature必须为0路由决策不需要任何随机性。随机性等于碰运气在工具选择上是大忌。另外一个约束是max_candidates控制为5测试下来候选集太多模型会开始出现“选择困难症”太少又怕漏掉正确工具5是一个性价比非常高的数字。3.4 上下文预算与压缩Agent-Reach里面我实现了一个简单的上下文预算器。不要小看这个模块它直接决定了Agent能在多长的会话中保持稳定。先给一个常用参数计算模型假设模型最大上下文是128K系统提示占3K对话历史保留20K工具执行结果最多占40K模型输出预留20K剩下就是预留缓冲。计算公式是工具结果预算 max_context - system_prompt - conversation_history - output_reserved - buffer我按这个公式给团队定了默认值128K上下文模型工具结果预算45K64K上下文模型工具结果预算20K。如果不做预算Agent最后一次回复时可能会因为上下文超过限制出现“忘掉”前面工具结果的情况非常坑。压缩策略上我采用的是“每个工具结果只保留结构化摘要”。比如调用库存API返回了200行明细我不会把这些明细全部保留而是让模型先抽取出重要数值比如总库存量、低于安全水位的SKU数量然后再把摘要放回上下文原始明细丢进侧车存储用户若需要详单再单独展示。3.5 执行层与重试机制执行层的核心代码不复杂但有几个参数值得反复调。# agent_reach/core/executor.py import asyncio import time class Executor: def __init__(self, retry_times: int 2, retry_delay: float 0.5): self.retry_times retry_times self.retry_delay retry_delay async def execute(self, tool: dict, arguments: dict): handler tool[handler] for attempt in range(self.retry_times 1): try: start time.time() result await asyncio.wait_for( handler(**arguments), timeouttool[timeout_ms] / 1000 ) return {ok: True, result: result, latency: time.time() - start} except asyncio.TimeoutError: # 超时状态下不推荐直接重试先检查目标服务的健康状态 return {ok: False, error: timeout, latency: time.time() - start} except Exception as e: if attempt self.retry_times: await asyncio.sleep(self.retry_delay) continue return {ok: False, error: str(e), latency: time.time() - start} return {ok: False, error: unknown}一个经验总结只有网络抖动类和瞬时限流类错误适合重试业务参数错误不要重试比如订单号不存在这种重试一百次也没有意义。超时不要盲目重试因为如果下游已经过载重试只会加重雪崩。3.6 整体编排主流程把注册、路由、执行串起来就是main.py的职责。我按照“决策-执行-再决策”的模式而不是“一次决策执行到底”的模式来写# agent_reach/main.py import asyncio from agent_reach.core.router import Router from agent_reach.core.executor import Executor from agent_reach.core.context import ContextManager async def run_agent(query: str, user_id: str): ctx ContextManager(user_iduser_id, max_tool_result_tokens45000) # 第一轮决策 router Router(model_client) executor Executor() current_query query for step in range(5): # 最多让Agent执行5轮工具调用 tool router.route(current_query) if tool is None: break arguments ctx.extract_arguments(tool) # 从query和上下文中提取参数 if not ctx.permission_granted(tool, arguments): return {need_confirm: tool[name], arguments: arguments} result await executor.execute(tool, arguments) ctx.add_tool_result(tool[name], result) # 判断是否完成任务调用模型做总结或继续 current_query ctx.next_question() return ctx.final_answer()这个流程里有个细节每次循环后都需要重新生成current_query。原因很简单工具返回结果可能改变问题答案Agent需要基于最新信息重新判断不能死守着最初的用户提问。4. 常见问题与排查技巧实录Agent-Reach上线后踩过的真实坑4.1 工具选择乱跳选择了不在候选集里的工具有段时间用户反馈明明查询库存功能Agent却调用了盘点列表接口。排查日志发现路由阶段候选集只有三个库存相关工具模型却返回了一个完全不在名单上的工具名。原因是模型会强行“联想”甚至编一个听上去合理的工具名。我的对策有两招第一在模型提示词里强约束“只能从列表中返回如果列表中没有合适工具返回NO_TOOL”第二路由返回后增加一层validate如果匹配不到注册表中的工具名直接丢弃并走默认答复流程。这两招叠加后瞎编工具名的概率几乎降到了0。4.2 Agent反复调用同一个工具形成死循环另一个高频坑是循环调用。比如第一次查库存发现不够Agent不去通知用户而是继续查另一个仓库接着查第三个仓库最多一次连续调了12次库存接口不仅浪费token还把下游数据库打到了高负载。解决思路是给Agent设置两个约束。一是在上下文中累计记录每轮工具调用摘要——不要太长一串字符串就行。二是明确告诉模型“如果没有新信息或答案已经清楚请立即结束任务不要为了调用工具而调用工具”。同时在主流程里限制最大工具调用轮数为5超出之后强制收束。用户其实不太关心你调了几次工具他们在意的只是答案对不对。4.3 权限误判读操作被当成写操作拦截这个问题的难点在于判断用户意图到底要不要写。比如“帮我改一下收货地址”可能是真的修改也可能只是询问怎么改。我自己测试多了发现与其让模型猜不如在权限不确定时直接走二次确认流程。这不算打扰反而是在帮Agent避责。我把权限等级细化成了五档public、read、write、high_risk、forbidden。其中write以上的操作一律要求用户确认即便是Agent调用的结果也会在返回前端时高亮提示“已执行修改操作”。实际操作中加了这一层之后再也没有出现过误删配置这种事故。4.4 上下文还是爆了压缩后信息丢失有段时间我们遇到一个“诡异”现象会话前5轮一切正常到第7轮的时候Agent开始回答得牛头不对马嘴。后来看日志发现工具结果摘要里只保留了数字把单位给丢了。库存表里写的“50”既可能是50件也可能是50箱模型就开始乱猜。这个坑让我把摘要模板固定成了“主语值单位时间”比如“SKU12345库存剩余50箱更新时间2025-06-10 10:30”。同时压缩时强制保留三个关键时间点数据更新时间、用户请求时间、当前时间。这些字段看起来小但在决策时非常关键。下面把几个常见问题整理成速查表方便你以后直接翻现象可能原因排查入口解决思路Agent选择了不存在的工具名路由阶段模型幻觉路由日志里校验环节提示词强约束 validate兜底反复调用同一工具决策信息不足历史工具调用记录补充有效性判断 最大轮数限制写操作未确认就执行权限分级不清审计日志permission_level写和高风险操作强制二次确认上下文被工具结果塞满未做结果压缩context预算日志摘要化 token预算硬限制下游接口超时并发过高网关层并发监控并发数上限 排队或降级策略4.5 限流与并发控制的小技巧最后说一个容易忽略的点工具被Agent并发调用时下游系统的限流策略不是简单的QPS阈值。我当时用Littles Law来估算并发上限并发数 平均QPS × 平均耗时秒比如某个第三方API限流QPS5单次查询平均耗时2秒那并发上限就是5×210。超过这个数字响应必然开始排队。在Executor层做一个信号量控制并发实测下来稳定性好很多。另一个经验是给工具做“熔断”。如果同一个工具连续报错超过5次就在短期内直接从路由候选集里移除避免Agent在不可用的工具上反复试错。等到错误恢复后再放回路由表。5. 后续还能往哪些方向扩展写到这儿其实Agent-Reach已经能承担企业内部Agent的“工具神经中枢”角色。如果再往下走我这边有几个已验证或者正在尝试的方向也算给后来者一点参考。第一是工具自文档化。目前的趋势是让Agent自己生成工具描述而不是工程师手工写。但我的经验是在Agent-Reach的注册表里手工写的description带有的“边界感”是自动生成描述比不了的。后续可以考虑让Agent生成初稿再由工程师微调既省力又能保证质量。第二是多Agent场景。一个Agent解决不了跨度太大的任务时拆成多个子Agent每个子Agent配一个独立的工具子集再由顶层Agent做调度。Agent-Reach的路由层可以非常自然地升级成“Agent调度层”只要把候选集从工具换成Agent就行。第三是动态工具装载。当前工具表在启动时加载完就固定了但在大型系统里业务方临时上线一个运营活动工具总不能重启服务。后续可以考虑做一个热插拔机制让工具在运行期动态注册和下架同时同步更新注册表版本这样整个系统的敏捷度会上一个台阶。我个人的体会是Agent的能力边界不取决于模型多聪明而取决于它够得着的工具多可靠。Agent-Reach这层设计看起来只是在做“调度”但它实际上把Agent从实验品变成了生产工具。只要你认真对待路由决策、上下文预算和权限这三件事你的Agent项目就成功了一大半。如果你也在做类似的Agent框架欢迎拿这套思路去做参考有一些细节只有自己跑过才知道怎么调。
Agent-Reach：为AI Agent打造高效可靠的工具调用编排层
Agent-Reach 这个名字听起来像是一个框架或者平台但实际上它是我在处理AI Agent落地时攒出来的一套编排层方案。简单说它解决的是一个问题你的Agent知道该干什么但它“够不着”需要的工具和数据。把Agent从只能聊天的状态变成真正能动用企业内部系统、第三方API、数据库、文档库的干活状态中间缺的正是这一层能力调配。这个项目是我在过去大半年里在一个中型团队里从0搭起来的踩了无数坑也验证了不少思路今天拿出来聊一聊。先给刚接触Agent开发的同学一个定位Agent-Reach不是某个大模型也替换不了RAG或者向量库它更像是一个大脑和手脚之间的“神经传导层”。你给它一个用户请求它负责判断该调哪个工具、按什么顺序调、哪些信息需要留、哪些需要丢、权限怎么控制、调用失败怎么办。它最适合三类人一类是在做企业内部知识助手、想让Agent真的操作业务系统的工程师一类是做自动化工作流的团队被各种工具调用混乱搞到头大还有一类是准备把Agent从Demo推向生产环境、开始考虑稳定性和安全性的技术负责人。这个项目的核心价值说到底就是把“工具调用”这层做成了可信赖的基础设施而不是一段到处复制粘贴的胶水代码。下面我按照当时的设计和落地过程把思路、结构、实操和踩坑都拆开讲。1. 整体设计与思路拆解为什么Agent需要一个“够得着”的中间层1.1 我是怎么被逼着做Agent-Reach的场景很典型——我们团队做了一个基于大模型的业务助理最初只接了一个知识库问答效果还凑合。后来产品要往上加需求帮用户查订单状态、提交审批、计算项目工时、查询库存水位甚至通过API去修改配置。第一个版本我直接把工具函数写死在系统提示词里看起来好像每个功能都能用结果一上线就出了大问题Agent经常把“查订单状态”和“查物流轨迹”混在一起明明有库存查询接口它偏要猜更头疼的是有一次它竟然在没有权限确认的情况下调用了删除配置的API。那个版本的代码逻辑是简单的但整个系统的可信度瞬间崩塌。那时候我开始意识到问题不在模型本身而在模型和工具之间缺少一个交通警察。交通警察要干的事是弄清楚每个路口通往哪里、谁可以走这条路、怎么根据车的去向安排最快的线路。放到Agent体系里就是工具注册、权限判断、路由选择和结果整理。这就是Agent-Reach的起点。1.2 Agent执行失败的三个根因你会发现Agent拿到任务后表现不稳其实根子往往不在模型智商而是这三个地方第一个是工具碎片化。团队里不同模块的工具各自定义参数格式、错误码和字段命名Agent看到的是几十个参差不齐的函数别说大模型人看着都头大。就好比你让一个人去仓库里找货既不告诉他货架号也不告诉他货品单位他只能靠猜。第二个是上下文膨胀。每一轮对话都把大量工具描述、返回结果塞进上下文问题很快就出现了——要么超长截断要么关键信息被淹没。相当于一个人手里拿着二十张纸条每张都写满字但只有半句话有用。第三个是权限模糊。工具没有声明自己的权限等级Agent也没有判断依据结果就是“能调的都能调”这离事故只有一步之遥。1.3 Agent-Reach的核心设计目标针对上面三个根因我立了三个设计目标第一统一工具协议所有工具按同一套schema注册描述内容标准化。第二引入路由决策Agent不是直接从工具列表里选而是通过一个路由层做评分和排序。第三把权限控制和审计从业务代码里剥离出来统一在这一层执行。一句话总结Agent-Reach的定位是“让Agent的每一次工具调用都有据可依、有迹可循、有权限边界”。这个设计带来一个很实际的收益——后续每接入一个新工具不用改Agent的核心逻辑只需要做一次注册写清描述、类型、参数、权限等级剩下的路由、校验、重试都由Agent-Reach接管。团队的开发效率明显提升接入新功能的时间从一周缩到了半天。2. 核心细节解析与实操要点工具注册、路由策略、权限审计2.1 整体架构分层Agent-Reach在逻辑上分成三层接口网关层、路由决策层、执行适配层。接口网关层负责接收Agent传来的自然语言目标和上下文压缩包做基础校验比如用户身份、会话ID、目标中是否带有敏感词。路由决策层是核心它要做两件事一是从工具注册表里筛选出候选集二是对候选集做相关性评分最终决定调谁、不调谁。执行适配层负责把路由结果转成具体工具的参数处理鉴权票据、调用外部API或内部函数再把结果按统一格式回传。我见过不少团队把这三层混在一起代码量看着不多但调试起来非常痛苦因为分不清是模型决策错了还是执行报错了。分开之后每一层的日志可以单独追踪排查问题快得多。2.2 工具注册表的Schema设计工具注册表是整个Agent-Reach的心脏。我的经验是schema不能太自由至少要包含这几个字段tool_name全局唯一只能用英文和下划线例如get_order_status。description用一句话说清这个工具干什么尽量包含“何时用”和“何时不用”两个信息。比如“当用户询问订单配送进度时使用当询问退换货政策时不要使用”。parametersJSON Schema格式的参数定义每个参数要注明是否必填、类型、取值范围、示例值。permission_level读操作、写操作、高风险操作三档例如select对应读、update对应写、delete对应高风险。timeout_ms和rate_limit给工具执行设超时和限流。handler指向真正执行函数或HTTP接口。这里有个容易被忽略的细节——description不要写太长也不要写太抽象。我们测试下来一个40到80字的描述既能让模型准确理解又不会占用太多上下文。写得像“提供订单信息查询服务”这种模型还是会在多个订单类工具之间选错写成“当用户需要查看订单当前状态未支付 已支付 已发货 已完成时使用订单列表查询用另一个工具get_order_list”准确率能提升不少。2.3 路由策略从意图匹配到评分排序路由决策层的设计我当时试过两种思路。第一种是纯函数规则用关键词实体匹配筛选候选工具。比如query里出现“订单”就拉出get_order_status和get_order_list。这种方案胜在快和可解释但缺陷是遇到自然语言变化就失灵比如用户说“我的快递到哪了”你很难直接从关键词里匹配到“订单”。第二种是基于模型打分。把query和候选工具的description拼接起来让模型输出0到100的匹配度和选择理由。这个方案更准但每次路由会有额外延迟和成本。我最后采用的是混合方案先用规则缩小候选集到最多5个再由模型在候选集里做二次精确选择。这样既控制了cost和latency又保证了准确率。还有一点值得说——不要让Agent直接对原始工具列表做“最后一跳”选择。因为一旦工具超过十几个无论多强的模型都会开始犯错。把工具列表缩小到3到5个再做选择准确率提升非常明显我们内部做过统计top1准确率从68%提升到了90%以上。2.4 权限隔离与审计追踪权限这块是上生产环境前必须处理的。我的做法不是给Agent“授权”而是给任务“临时授权”用户提出请求后Agent-Reach先根据permission_level判断这次调用是不是高风险如果是就把工具调用的完整参数返回给前端要求用户二次确认。确认后生成一个有效期5分钟的一次性token执行完之后立刻作废。这一招在内部Demo上和真实业务场景中都很有效。它不会让用户觉得流程烦琐反而会提升信任感因为用户能看到Agent到底要拿他的身份去做什么。另外每一次工具调用无论成功失败都会写一条审计日志字段包括用户ID、会话ID、query摘要、路由候选集、最终选择、参数、耗时、错误信息。这些数据一方面用来排查问题另一方面后来也成了我们优化路由策略的重要依据。3. 实操过程与核心环节实现从注册到路由再到执行的完整闭环3.1 环境准备与项目结构Agent-Reach用Python实现因为这个生态里处理JSON Schema和调用大模型最顺手。核心依赖只有三个pydantic做参数校验、httpx做异步HTTP调用、任意的模型客户端SDK我用的是兼容OpenAI格式的接口所以切换模型时不用改代码。项目结构大概是这样的agent_reach/ ├── core/ │ ├── registry.py # 工具注册表 │ ├── router.py # 路由决策 │ ├── executor.py # 工具执行与重试 │ └── context.py # 上下文压缩与预算 ├── tools/ │ ├── order.py # 订单域工具 │ ├── inventory.py # 库存域工具 │ └── approval.py # 审批域工具 ├── config.yaml # 限流、超时、模型配置 └── main.py # 入口编排3.2 定义工具注册表先写一个工具注册的装饰器让团队成员可以很方便地把一个普通函数注册成Agent-Reach工具。这段代码是整个项目的第一块基石# agent_reach/core/registry.py import inspect from typing import Callable, Dict, Any class ToolRegistry: def __init__(self): self._tools: Dict[str, Dict[str, Any]] {} def register( self, name: str, description: str, parameters: dict, permission_level: str read, timeout_ms: int 5000, rate_limit: int 10, ): def decorator(func: Callable): self._tools[name] { name: name, description: description, parameters: parameters, permission_level: permission_level, timeout_ms: timeout_ms, rate_limit: rate_limit, handler: func, } return func return decorator registry ToolRegistry()注册一个业务工具时只需要这样写from agent_reach.core.registry import registry registry.register( nameget_order_status, description当用户需要查看订单当前状态未支付/已支付/已发货/已完成时使用 订单列表查询请使用另一个工具get_order_list不要混用。, parameters{ type: object, properties: { order_id: {type: string, description: 订单号形如ORD2024001} }, required: [order_id] }, permission_levelread, timeout_ms3000, rate_limit30, ) def get_order_status(order_id: str): # 这里是真实业务调用查DB或者调内部API return {order_id: order_id, status: 已发货, logistics: 顺丰SF123456}这里有两个实操心得参数定义里一定要给示例值pydantic校验错误提示会友好很多description里明确写“不要用”的情况等于帮模型在候选阶段做了一次负样本划分。3.3 实现路由决策模块路由模块要做的事是接收用户目标文本先规则缩小候选集再让模型在候选集里打分。我写了一个简化版本# agent_reach/core/router.py import json from agent_reach.core.registry import registry class Router: def __init__(self, model_client): self.model_client model_client def _rule_filter(self, query: str, max_candidates: int 5): 先用简单关键词规则缩小范围控制后续模型打分成本 scored [] for tool in registry._tools.values(): score 0 desc tool[description].lower() query_lower query.lower() keywords [订单, 库存, 审批, 项目, 物流, 退款, 价格] for kw in keywords: if kw in query_lower and kw in desc: score 1 if score 0: scored.append((score, tool)) scored.sort(keylambda x: -x[0]) return [tool for _, tool in scored[:max_candidates]] def _model_choose(self, query: str, candidates: list) - str: 让模型判断哪个工具最匹配当前请求 if not candidates: return None candidate_text \n.join( f{t[name]}: {t[description]} for t in candidates ) prompt ( f用户请求{query}\n\n f可用工具列表\n{candidate_text}\n\n 请返回一个工具名不要解释。 ) response self.model_client.chat( messages[{role: user, content: prompt}], temperature0, ) return response.strip() def route(self, query: str): candidates self._rule_filter(query) if len(candidates) 1: return candidates[0] tool_name self._model_choose(query, candidates) return registry._tools.get(tool_name)这里有一点关键temperature必须为0路由决策不需要任何随机性。随机性等于碰运气在工具选择上是大忌。另外一个约束是max_candidates控制为5测试下来候选集太多模型会开始出现“选择困难症”太少又怕漏掉正确工具5是一个性价比非常高的数字。3.4 上下文预算与压缩Agent-Reach里面我实现了一个简单的上下文预算器。不要小看这个模块它直接决定了Agent能在多长的会话中保持稳定。先给一个常用参数计算模型假设模型最大上下文是128K系统提示占3K对话历史保留20K工具执行结果最多占40K模型输出预留20K剩下就是预留缓冲。计算公式是工具结果预算 max_context - system_prompt - conversation_history - output_reserved - buffer我按这个公式给团队定了默认值128K上下文模型工具结果预算45K64K上下文模型工具结果预算20K。如果不做预算Agent最后一次回复时可能会因为上下文超过限制出现“忘掉”前面工具结果的情况非常坑。压缩策略上我采用的是“每个工具结果只保留结构化摘要”。比如调用库存API返回了200行明细我不会把这些明细全部保留而是让模型先抽取出重要数值比如总库存量、低于安全水位的SKU数量然后再把摘要放回上下文原始明细丢进侧车存储用户若需要详单再单独展示。3.5 执行层与重试机制执行层的核心代码不复杂但有几个参数值得反复调。# agent_reach/core/executor.py import asyncio import time class Executor: def __init__(self, retry_times: int 2, retry_delay: float 0.5): self.retry_times retry_times self.retry_delay retry_delay async def execute(self, tool: dict, arguments: dict): handler tool[handler] for attempt in range(self.retry_times 1): try: start time.time() result await asyncio.wait_for( handler(**arguments), timeouttool[timeout_ms] / 1000 ) return {ok: True, result: result, latency: time.time() - start} except asyncio.TimeoutError: # 超时状态下不推荐直接重试先检查目标服务的健康状态 return {ok: False, error: timeout, latency: time.time() - start} except Exception as e: if attempt self.retry_times: await asyncio.sleep(self.retry_delay) continue return {ok: False, error: str(e), latency: time.time() - start} return {ok: False, error: unknown}一个经验总结只有网络抖动类和瞬时限流类错误适合重试业务参数错误不要重试比如订单号不存在这种重试一百次也没有意义。超时不要盲目重试因为如果下游已经过载重试只会加重雪崩。3.6 整体编排主流程把注册、路由、执行串起来就是main.py的职责。我按照“决策-执行-再决策”的模式而不是“一次决策执行到底”的模式来写# agent_reach/main.py import asyncio from agent_reach.core.router import Router from agent_reach.core.executor import Executor from agent_reach.core.context import ContextManager async def run_agent(query: str, user_id: str): ctx ContextManager(user_iduser_id, max_tool_result_tokens45000) # 第一轮决策 router Router(model_client) executor Executor() current_query query for step in range(5): # 最多让Agent执行5轮工具调用 tool router.route(current_query) if tool is None: break arguments ctx.extract_arguments(tool) # 从query和上下文中提取参数 if not ctx.permission_granted(tool, arguments): return {need_confirm: tool[name], arguments: arguments} result await executor.execute(tool, arguments) ctx.add_tool_result(tool[name], result) # 判断是否完成任务调用模型做总结或继续 current_query ctx.next_question() return ctx.final_answer()这个流程里有个细节每次循环后都需要重新生成current_query。原因很简单工具返回结果可能改变问题答案Agent需要基于最新信息重新判断不能死守着最初的用户提问。4. 常见问题与排查技巧实录Agent-Reach上线后踩过的真实坑4.1 工具选择乱跳选择了不在候选集里的工具有段时间用户反馈明明查询库存功能Agent却调用了盘点列表接口。排查日志发现路由阶段候选集只有三个库存相关工具模型却返回了一个完全不在名单上的工具名。原因是模型会强行“联想”甚至编一个听上去合理的工具名。我的对策有两招第一在模型提示词里强约束“只能从列表中返回如果列表中没有合适工具返回NO_TOOL”第二路由返回后增加一层validate如果匹配不到注册表中的工具名直接丢弃并走默认答复流程。这两招叠加后瞎编工具名的概率几乎降到了0。4.2 Agent反复调用同一个工具形成死循环另一个高频坑是循环调用。比如第一次查库存发现不够Agent不去通知用户而是继续查另一个仓库接着查第三个仓库最多一次连续调了12次库存接口不仅浪费token还把下游数据库打到了高负载。解决思路是给Agent设置两个约束。一是在上下文中累计记录每轮工具调用摘要——不要太长一串字符串就行。二是明确告诉模型“如果没有新信息或答案已经清楚请立即结束任务不要为了调用工具而调用工具”。同时在主流程里限制最大工具调用轮数为5超出之后强制收束。用户其实不太关心你调了几次工具他们在意的只是答案对不对。4.3 权限误判读操作被当成写操作拦截这个问题的难点在于判断用户意图到底要不要写。比如“帮我改一下收货地址”可能是真的修改也可能只是询问怎么改。我自己测试多了发现与其让模型猜不如在权限不确定时直接走二次确认流程。这不算打扰反而是在帮Agent避责。我把权限等级细化成了五档public、read、write、high_risk、forbidden。其中write以上的操作一律要求用户确认即便是Agent调用的结果也会在返回前端时高亮提示“已执行修改操作”。实际操作中加了这一层之后再也没有出现过误删配置这种事故。4.4 上下文还是爆了压缩后信息丢失有段时间我们遇到一个“诡异”现象会话前5轮一切正常到第7轮的时候Agent开始回答得牛头不对马嘴。后来看日志发现工具结果摘要里只保留了数字把单位给丢了。库存表里写的“50”既可能是50件也可能是50箱模型就开始乱猜。这个坑让我把摘要模板固定成了“主语值单位时间”比如“SKU12345库存剩余50箱更新时间2025-06-10 10:30”。同时压缩时强制保留三个关键时间点数据更新时间、用户请求时间、当前时间。这些字段看起来小但在决策时非常关键。下面把几个常见问题整理成速查表方便你以后直接翻现象可能原因排查入口解决思路Agent选择了不存在的工具名路由阶段模型幻觉路由日志里校验环节提示词强约束 validate兜底反复调用同一工具决策信息不足历史工具调用记录补充有效性判断 最大轮数限制写操作未确认就执行权限分级不清审计日志permission_level写和高风险操作强制二次确认上下文被工具结果塞满未做结果压缩context预算日志摘要化 token预算硬限制下游接口超时并发过高网关层并发监控并发数上限 排队或降级策略4.5 限流与并发控制的小技巧最后说一个容易忽略的点工具被Agent并发调用时下游系统的限流策略不是简单的QPS阈值。我当时用Littles Law来估算并发上限并发数 平均QPS × 平均耗时秒比如某个第三方API限流QPS5单次查询平均耗时2秒那并发上限就是5×210。超过这个数字响应必然开始排队。在Executor层做一个信号量控制并发实测下来稳定性好很多。另一个经验是给工具做“熔断”。如果同一个工具连续报错超过5次就在短期内直接从路由候选集里移除避免Agent在不可用的工具上反复试错。等到错误恢复后再放回路由表。5. 后续还能往哪些方向扩展写到这儿其实Agent-Reach已经能承担企业内部Agent的“工具神经中枢”角色。如果再往下走我这边有几个已验证或者正在尝试的方向也算给后来者一点参考。第一是工具自文档化。目前的趋势是让Agent自己生成工具描述而不是工程师手工写。但我的经验是在Agent-Reach的注册表里手工写的description带有的“边界感”是自动生成描述比不了的。后续可以考虑让Agent生成初稿再由工程师微调既省力又能保证质量。第二是多Agent场景。一个Agent解决不了跨度太大的任务时拆成多个子Agent每个子Agent配一个独立的工具子集再由顶层Agent做调度。Agent-Reach的路由层可以非常自然地升级成“Agent调度层”只要把候选集从工具换成Agent就行。第三是动态工具装载。当前工具表在启动时加载完就固定了但在大型系统里业务方临时上线一个运营活动工具总不能重启服务。后续可以考虑做一个热插拔机制让工具在运行期动态注册和下架同时同步更新注册表版本这样整个系统的敏捷度会上一个台阶。我个人的体会是Agent的能力边界不取决于模型多聪明而取决于它够得着的工具多可靠。Agent-Reach这层设计看起来只是在做“调度”但它实际上把Agent从实验品变成了生产工具。只要你认真对待路由决策、上下文预算和权限这三件事你的Agent项目就成功了一大半。如果你也在做类似的Agent框架欢迎拿这套思路去做参考有一些细节只有自己跑过才知道怎么调。