做Agent项目有一件事迟早绕不过去——你很难说清楚这个Agent到底能把活干到哪一步。它能调哪些工具上下文能覆盖多长的任务几个Agent协作的时候这笔任务到底该归谁管这三个问题听着基础真上了生产全是坑。我见过太多次Demo阶段顺滑无比、一上线就拉胯的场面最后复盘下来问题根源往往不是模型不够聪明而是Agent缺一套清晰的能力边界管理机制。我做的这套东西叫Agent-Reach一个面向生产环境的Agent能力边界管理框架。它把Agent的能力拆成三层来管工具触达Tool Reach、上下文覆盖Context Reach、协作边界Team Reach。装进现有服务跑了一段时间后最直观的变化是任务路由准确率从73%升到了91%上下文超限的报错少了近九成多Agent协作时也不再互相踩脚。如果你正在搞Agent类项目哪怕只是刚让大模型接几个API这篇记录应该都能帮上点忙。我文里不写云里雾里的架构图就把设计思路、核心实现和踩过的坑全盘拆开聊。1. 需求分析与整体设计1.1 为什么有必要给Agent画一条显式能力边界Agent放开跑之前大部分人对它的预期是什么都能干。但实际跑一段时间你就会发现这个预期本身就是灾难的源头。我接触过的项目里有把客服Agent丢去处理售后赔付的结果赔付规则一变Agent按照记忆里的旧规则执行赔错了一笔金额不小的单子也有把数据分析Agent接到线上交易链路的它恰好有数据库权限一次错误的聚合查询直接影响了上游报表。这些事故的共同本质是Agent的能力范围没有被显式声明更没有被运行时约束。大模型的输出是概率性的它自己并不会天然地知道这件事我能干、那件事我不能干。如果你不在外部给它定义一套能力可达范围它就会在边界外硬闯闯到哪算哪。所以Agent-Reach的出发点很朴素把Agent的能力从隐式的模型行为变成显式的运行时管理系统。每个Agent上线之前必须先声明自己的能力边界运行过程中所有工具调用、上下文读写、协作转移都要在这个边界内进行。边界外的请求要么明确拒绝要么把任务转给更合适的Agent。这套约束不是用来限制能力的恰恰相反它是让Agent在可控范围内放心发挥的前提。1.2 Reach三层模型工具触达、上下文覆盖与协作边界Reach这个词我拆成三个层面来理解每一个层面都对着一类真实的失败模式。第一层是工具触达。Agent要干活就必须调用外部工具比如查订单、查库存、发起退款。工具能不能调、参数怎么填、调用失败怎么兜底都属于这一层的职责。我们在生产环境里见过最多的工具事故基本都是这一层没管住导致的。第二层是上下文覆盖。LLM的上下文窗口再大也有上限Agent处理一个复杂任务可能需要查10个文档、来回20轮对话。它的视野能不能覆盖到完成任务所需的关键信息上下文里哪些内容必须保留、哪些可以压缩这是Context Reach负责的问题。这一层如果没做好最常见的表现就是任务干到一半关键信息被挤掉了Agent在失忆状态下开始胡说。第三层是协作边界。多Agent系统里每个Agent各管一段没有一个Agent是万能的。任务从哪个入口进来、应该路由给谁、当前Agent处理不了时怎么转移这是Team Reach要管的事。协作边界不清的典型症状就是踢皮球——任务在多个Agent之间来回转谁都不真正负责。Reach层级要解决的问题典型失败模式Tool ReachAgent能调哪些工具参数如何规范化工具调错、参数格式错误、权限越界Context Reach上下文窗口内的信息覆盖是否足够关键信息被裁剪、上下文溢出、幻觉Team Reach多Agent任务路由与责任边界踢皮球、重复处理、任务悬空项目名里用Reach就是想把这三层统一成一个可观测、可度量的概念。后面几个章节我会逐一展开每一层的实现细节。1.3 方案选型LangGraph做编排Reach层完全自研技术选型上我走了个混合路线底层编排用LangGraphReach相关的逻辑全部自研。原因很实际。LangGraph的StateGraph在描述复杂Agent状态流转上确实省力你不需要自己维护一套状态机框架。它的短板也明显它默认不管Agent能调哪些工具也不提供任何路由约束。你可以在LangGraph里画出一个很漂亮的Agent流程图但每个节点上的Agent到底该做什么、不该做什么它压根不关心。另一个重要原因是审计需求。我们团队接的很多业务场景要求每一次工具调用都有据可查——什么时间、哪个Agent、为什么调这个工具、参数是什么、结果如何。这个审计能力LangGraph自带的API覆盖不了必须自己在外面包一层。所以最终的架构是LangGraph负责Agent的状态流转和任务编排ReachManager负责工具注册、能力匹配、上下文分配和路由确认。两层通过接口交互不互相污染数据。如果项目体量小其实完全不必要上LangGraph直接用纯函数编排也行。Agent-Reach的ReachManager是一个独立模块不依赖LangGraph的类型后期就算换掉编排引擎Reach核心逻辑也能原样保留。2. 核心机制与实操要点2.1 工具注册表JSON Schema就是一份硬契约Agent-Reach的第一步是让系统知道现在有哪些工具存在。工具注册表这个组件我前前后后改了三版最开始就是一张简单的Python字典后来发现这种方式根本做不了校验和审计。现在工具注册表的核心设计是每一个工具都用JSON Schema描述注册阶段做Schema完整性校验运行阶段做参数格式校验。工具Schema就是Agent和系统之间的一份硬契约——Agent声称要调用某个工具参数必须符合Schema约束否则直接拒掉。# tools/registry.py from jsonschema import validate, ValidationError class ToolRegistry: def __init__(self): self._tools {} def register(self, name: str, schema: dict, handler: callable): # 注册前校验 schema 是否完整 assert type in schema, 工具Schema必须声明type字段 assert properties in schema, 工具Schema必须声明properties字段 self._tools[name] { name: name, schema: schema, handler: handler, } def list(self): return list(self._tools.keys()) def call(self, name: str, args: dict): if name not in self._tools: raise KeyError(f未注册的工具: {name}) tool self._tools[name] try: validate(instanceargs, schematool[schema]) except ValidationError as e: raise ValueError(f工具参数校验失败: {e.message}) from e # 执行工具逻辑前记录审计日志 result tool[handler](**args) # 返回前强制序列化 return to_json(result)这里有一个必须强调的点为什么参数校验这么重要因为Agent本质上是语言模型它生成工具参数时是按概率来的。如果不校验你可能会收到一个根本不存在的日期格式或者漏掉必填字段。JSON Schema校验就是一道硬约束专门拦截这类低级错误。我在多个项目里反复看到加了这一步之后工具调用成功率能提升20个百分点以上。另外一个容易忽略的细节是to_json()这一步。很多工具handler内部会把ORM对象、自定义类实例什么的直接返回如果不强制序列化这些非JSON对象一旦拼进上下文轻则影响后续模型调用重则直接报序列化错误。2.2 Agent能力声明与Reach匹配算法工具注册表解决的是有哪些工具能力声明解决的是这个Agent能用哪些工具、覆盖哪类任务。每个Agent上线前必须提交一份能力声明我用AgentCap这个数据模型来承载。# reach/caps.py from dataclasses import dataclass dataclass class AgentCap: agent_id: str role: str # 例如 customer_service / after_sale tools: list[str] # 允许调用的工具白名单 context_limit: int # 上下文token上限 routing_rules: list[str] # 路由规则关键词 def can_handle(self, task: str) - float: 返回该Agent对任务的匹配分0-1之间 score 0.0 for rule in self.routing_rules: if rule.lower() in task.lower(): score 0.7 return min(score, 1.0)实际项目里我把匹配逻辑做得比示例代码复杂一些。关键词规则以外还会用一个轻量级的embedding模型把任务向量化每条路由规则也有自己的向量算余弦相似度作为语义匹配分。最后加权组合关键词匹配走快路径语义相似度负责兜底。需要特别注意的是匹配分不能只看最高分这个原则。我踩过这样一个坑某个任务本身是售后赔付但售后Agent和客服Agent的语义匹配分都超过了0.6Router按分数把任务派给了客服Agent结果客服Agent只能回复用户我帮你转接一下再跟进白白浪费一次交互。后来我在Reach匹配逻辑里加了一条强制规则一旦出现多个Agent匹配分都超过阈值任务进入双确认流程——Router先生成候选Agent清单让资格分最高的Agent必须做一次接管确认如果它表示当前能力覆盖不了才允许转给次优Agent。接管确认机制在工程上实现也很简单就是多返回一个字段的事。但它在产品体验上的价值很大能有效抑制多Agent背景下常见的乱接单、接不住问题。2.3 上下文管理器分档保留与动态摘要上下文管理是整个系统里最容易翻车的一层。Agent上下文塞满了第一反应通常是把最早的会话记录剪掉。但裁剪绝对有讲究——你要保留的是与任务相关的关键信息而不是字面意义上最早的信息。我的上下文管理器采用两级结构第一级是核心上下文始终完整保留。包含系统身份提示词、当前任务目标、用户最新输入、最近两轮的对话。这部分是Agent做决策时的必须信息动了它Agent就会在不知道用户到底要什么的状态下开始瞎干活。第二级是扩展上下文包括历史工具调用记录、查过文档的摘要、更早轮次的对话。这部分支持压缩压缩策略是分层摘要每3轮旧对话压缩成一段摘要放进扩展区如果扩展区仍然超限就再把摘要做二次合并形成更粗粒度的摘要。# reach/context_manager.py class ContextManager: def build(self, task, chat_history, tool_logs, max_tokens): # 核心区当前任务 最近2轮对话 core self.build_core_block(task, chat_history[-2:]) # 扩展区历史对话 工具调用日志 ext self.build_extend_block(chat_history[:-2], tool_logs) # 优先保障核心区不断压缩扩展区 while core.tokens ext.tokens max_tokens: ext ext.summarize(target_tokenslen(ext.tokens) // 2) return core ext我参考了存储引擎里增量合并的思路每次只对新增的对话做摘要而不是把全部历史重新压缩一遍。这样做能够显著降低token消耗避免每次请求都去全量跑一次摘要模型。核心原则概括成一句话宁可牺牲历史细节不能牺牲当前任务目标。3. 落地实现与完整流程3.1 最小可运行环境与系统骨架如果你是第一次搭这种系统别一上来就把LangChain全家桶装上。我现在的标准环境非常克制Python 3.10、FastAPI、LangGraph、jsonschema、外加一个兼容OpenAI调用格式的SDK。依赖越少后期升级和排查问题就越省心。先起一个最小的Agent服务骨架验证链路通畅再往里面加逻辑# main.py from fastapi import FastAPI from tools.registry import ToolRegistry from reach.router import ReachRouter app FastAPI() registry ToolRegistry() router ReachRouter() app.post(/agent/{agent_id}/run) def run_agent(agent_id: str, payload: dict): cap router.get_cap(agent_id) if not cap: return {error: unknown_agent} if payload.get(tool) not in cap.tools: return {error: tool_not_allowed} # 主流程逻辑在此扩展 return {status: ok}这个骨架虽然简单但已经把最重要的校验逻辑放到了入口处一是Agent是否存在二是这个Agent是否允许调用目标工具。这两道校验防线越早执行后续出乱子的概率就越低。先把原始模型跑通再一步一步把Reach的三层逻辑接进去避免一次性堆砌所有功能导致排查困难。3.2 三步接入Reach声明、注册、绑定接入Agent-Reach的流程概括下来就三步不需要改动Agent内部的大量逻辑。第一步是声明能力。每个Agent上线之前必须写一份AgentCap声明文件。我们团队用YAML管理这份声明不写在代码里方便非技术人员一起来审核# agents/customer_service.yaml agent_id: customer_service role: 售前咨询 tools: - search_products - query_stock - get_delivery_policy context_limit: 12000 routing_rules: - 咨询 - 推荐 - 价格第二步是注册工具。把每个工具的JSON Schema和实际handler注册到ToolRegistry。这里我要强调一个细节handler的函数签名必须和Schema里的properties名称严格对应。如果工具的Schema声明了user_id字段但handler函数里的形参名写成了uid运行时必然报参数错误。这类问题在我们测试阶段反复出现现在注册工具时还加了一道自动化检查遍历Schema里的每个属性名确认它们都能映射到handler的形参。第三步是绑定路由。启动服务时把所有的AgentCap列表加载进ReachRouter。任务进来时Router按匹配分派发派发前再校验一次工具白名单白名单不通过的直接拒绝并说明原因。3.3 一次完整任务流转拆解从咨询到售后的边界切换为了让大家更有体感我用电商场景里的一个完整例子走一遍整套流程。用户发起会话说我上周下的这个订单物流已经三天没动了我要退款。第一步ReachRouter解析任务检测到物流和退款两个关键词同时命中客服Agent和售后Agent。经过语义匹配打分售后Agent得分更高因为用户的核心意图是退款这属于售后赔付的职责范围。任务派发给售后Agent。第二步售后Agent进入处理流程按白名单它只能调用get_order_status、query_logistics、initiate_refund三个工具。它先查订单状态和物流轨迹参数从用户消息中抽取订单号。如果参数抽取失败Reach框架会给Agent一次重试机会并把上次的参数填充错误信息反馈给它修正。这里的设计初衷是一次工具调用失败可能是模型的偶发失误通过反馈纠错能够提高成功率而不是让Agent直接摆烂。第三步售后Agent查到订单还在运输途中根据风控规则当前的物流状态下不能直接执行退款。它判断这个申请超出了自己的处理能力边界于是发起一个handover操作把任务连同上下文摘要一起转给退款风控Agent。这一步在系统里的表现就是Team Reach的应用当前Agent明确自己覆盖不了主动转移而不是硬撑着做决定。关于这个交接过程我要专门说一个实践细节Agent发起handover时候带的不是一句话而是一份交接上下文摘要。这份摘要包括用户原始诉求、已经执行过的工具调用、目前的中间结论。没有这份摘要下一个Agent接到的就是一段孤零零的任务描述它还得回过头来重新问用户一遍情况体验极差。3.4 参数预算与流控设计Agent系统的流控比普通API网关复杂一点因为每次LLM调用的token数是不确定的。我用的策略是分档限流和token预算管理。每个Agent实例配一个按token计费的令牌桶而不是按请求次数。上下文预算按比例划分为三块核心区固定占40%扩展区占50%预留10%给LLM的输出。举个具体例子一个Agent的context_limit是12000 token核心区就是4800 token扩展区6000 token输出预留1200 token。如果某个请求进来时扩展区的原始内容要8000 tokenContextManager就会执行摘要压缩把它压到6000以内。加这个预留区的设计是很重要的。早期版本我把上下文窗口的token全部分配给输入结果经常出现模型写回答写到一半token耗尽直接截断输出。后来强制预留10%给输出这个问题基本消失。如果你跑的是复杂推理任务输出长度需求高建议把预留比例上调到15%左右。4. 生产环境问题排查实录4.1 工具声明了但调用一直失败这个问题的出现频率常年排第一。大多数情况并不是Agent不会调而是Schema写得太宽或者参数名和handler对不上。我印象很深的一个排查案例花了将近半天工具Schema里用的是product_nameAgent从对话里抽取的商品名也能填上但一调用就报Object of type Product is not JSON serializable。问题其实出在handler内部返回了一个ORM对象。工具调用结果最终是要拼进上下文的返回值必须是纯JSON。解决方式是在所有工具handler出口统一过一层to_json()强制序列化从根上杜绝非JSON对象混入链路。4.2 上下文不超限但效果反而变差有一种情况很迷惑token占用明明在预算以内但Agent的回答质量明显下降。排查下来发现问题出在核心上下文区被无关的静态内容占据了——企业介绍、使用规范这些东西被塞进了核心区而用户真正的诉求被挤到扩展区而且可能已经被摘要过。修正方式是让核心区按任务相关度动态组装不再固定塞全套系统提示词。固定身份部分放核心区不变但行为规范类的提示词则按当前任务类型动态选择是否进入核心区。这个改动之后关键任务的目标保持率明显上来了Agent也终于不再忘记用户要什么了。4.3 多Agent协作互相踢皮球这可能是多Agent系统里最头疼的问题现象是任务在A和B之间反复转移谁也不真正负责。我用Reach的三层框架排查根源最终锁定在Team Reach的接管确认机制缺失。上一个版本的处理方式很简单A Agent觉得处理不了就直接发起handover把任务丢给BB接手一看也处理不了又丢回去。来回两三次白白消耗token和时间。现在加上两条强制规则每个Agent处理任务时有接管责任数标记。一旦确认接管除非标记为已完成或明确无法处理否则不允许再次发起相同目标的handover。任务转移超过两次后自动升级到人工兜底流程杜绝无限循环。这两条规则上线后踢皮球问题基本消失。我的核心体会是多Agent协作里责任确认和人工兜底比算法调优更重要。4.4 排查手段与可观测性Agent系统排错最痛苦的地方在于没有痕迹。Agent在中间想了什么、调了哪些工具、上下文怎么被压缩的全凭日志去猜。我在Agent-Reach里把决策痕迹做成了结构化日志。每次工具调用、每次上下文压缩、每次handover都会写一条带trace_id的JSON日志。检索问题的时候按trace_id把整条链路捞出来从上到下看每个环节的输入输出问题通常一眼就能定位。这里我强烈建议从第一天就开启结构化日志不要等出了事再补。Agent系统链路复杂事后追查的成本极高提前埋点顺手又划算。做Agent-Reach这段时间最深刻的体会其实是Agent能不能稳定落地往往不在模型本身而在边界管理。给Agent画清楚能力边界不是限制它恰恰是保护它——让它在可控范围内发挥最大自由度出了边界就诚实地说这个我做不了比硬撑着乱来要靠谱得多。如果你的团队正准备把Agent推向生产我建议先别急着堆功能先把工具注册表、上下文分档、路由确认这三件事做扎实。这三件事做好了后面踩坑的几率会小很多。 Agent能力边界管理框架Agent-Reach：三层模型设计与生产实践
做Agent项目有一件事迟早绕不过去——你很难说清楚这个Agent到底能把活干到哪一步。它能调哪些工具上下文能覆盖多长的任务几个Agent协作的时候这笔任务到底该归谁管这三个问题听着基础真上了生产全是坑。我见过太多次Demo阶段顺滑无比、一上线就拉胯的场面最后复盘下来问题根源往往不是模型不够聪明而是Agent缺一套清晰的能力边界管理机制。我做的这套东西叫Agent-Reach一个面向生产环境的Agent能力边界管理框架。它把Agent的能力拆成三层来管工具触达Tool Reach、上下文覆盖Context Reach、协作边界Team Reach。装进现有服务跑了一段时间后最直观的变化是任务路由准确率从73%升到了91%上下文超限的报错少了近九成多Agent协作时也不再互相踩脚。如果你正在搞Agent类项目哪怕只是刚让大模型接几个API这篇记录应该都能帮上点忙。我文里不写云里雾里的架构图就把设计思路、核心实现和踩过的坑全盘拆开聊。1. 需求分析与整体设计1.1 为什么有必要给Agent画一条显式能力边界Agent放开跑之前大部分人对它的预期是什么都能干。但实际跑一段时间你就会发现这个预期本身就是灾难的源头。我接触过的项目里有把客服Agent丢去处理售后赔付的结果赔付规则一变Agent按照记忆里的旧规则执行赔错了一笔金额不小的单子也有把数据分析Agent接到线上交易链路的它恰好有数据库权限一次错误的聚合查询直接影响了上游报表。这些事故的共同本质是Agent的能力范围没有被显式声明更没有被运行时约束。大模型的输出是概率性的它自己并不会天然地知道这件事我能干、那件事我不能干。如果你不在外部给它定义一套能力可达范围它就会在边界外硬闯闯到哪算哪。所以Agent-Reach的出发点很朴素把Agent的能力从隐式的模型行为变成显式的运行时管理系统。每个Agent上线之前必须先声明自己的能力边界运行过程中所有工具调用、上下文读写、协作转移都要在这个边界内进行。边界外的请求要么明确拒绝要么把任务转给更合适的Agent。这套约束不是用来限制能力的恰恰相反它是让Agent在可控范围内放心发挥的前提。1.2 Reach三层模型工具触达、上下文覆盖与协作边界Reach这个词我拆成三个层面来理解每一个层面都对着一类真实的失败模式。第一层是工具触达。Agent要干活就必须调用外部工具比如查订单、查库存、发起退款。工具能不能调、参数怎么填、调用失败怎么兜底都属于这一层的职责。我们在生产环境里见过最多的工具事故基本都是这一层没管住导致的。第二层是上下文覆盖。LLM的上下文窗口再大也有上限Agent处理一个复杂任务可能需要查10个文档、来回20轮对话。它的视野能不能覆盖到完成任务所需的关键信息上下文里哪些内容必须保留、哪些可以压缩这是Context Reach负责的问题。这一层如果没做好最常见的表现就是任务干到一半关键信息被挤掉了Agent在失忆状态下开始胡说。第三层是协作边界。多Agent系统里每个Agent各管一段没有一个Agent是万能的。任务从哪个入口进来、应该路由给谁、当前Agent处理不了时怎么转移这是Team Reach要管的事。协作边界不清的典型症状就是踢皮球——任务在多个Agent之间来回转谁都不真正负责。Reach层级要解决的问题典型失败模式Tool ReachAgent能调哪些工具参数如何规范化工具调错、参数格式错误、权限越界Context Reach上下文窗口内的信息覆盖是否足够关键信息被裁剪、上下文溢出、幻觉Team Reach多Agent任务路由与责任边界踢皮球、重复处理、任务悬空项目名里用Reach就是想把这三层统一成一个可观测、可度量的概念。后面几个章节我会逐一展开每一层的实现细节。1.3 方案选型LangGraph做编排Reach层完全自研技术选型上我走了个混合路线底层编排用LangGraphReach相关的逻辑全部自研。原因很实际。LangGraph的StateGraph在描述复杂Agent状态流转上确实省力你不需要自己维护一套状态机框架。它的短板也明显它默认不管Agent能调哪些工具也不提供任何路由约束。你可以在LangGraph里画出一个很漂亮的Agent流程图但每个节点上的Agent到底该做什么、不该做什么它压根不关心。另一个重要原因是审计需求。我们团队接的很多业务场景要求每一次工具调用都有据可查——什么时间、哪个Agent、为什么调这个工具、参数是什么、结果如何。这个审计能力LangGraph自带的API覆盖不了必须自己在外面包一层。所以最终的架构是LangGraph负责Agent的状态流转和任务编排ReachManager负责工具注册、能力匹配、上下文分配和路由确认。两层通过接口交互不互相污染数据。如果项目体量小其实完全不必要上LangGraph直接用纯函数编排也行。Agent-Reach的ReachManager是一个独立模块不依赖LangGraph的类型后期就算换掉编排引擎Reach核心逻辑也能原样保留。2. 核心机制与实操要点2.1 工具注册表JSON Schema就是一份硬契约Agent-Reach的第一步是让系统知道现在有哪些工具存在。工具注册表这个组件我前前后后改了三版最开始就是一张简单的Python字典后来发现这种方式根本做不了校验和审计。现在工具注册表的核心设计是每一个工具都用JSON Schema描述注册阶段做Schema完整性校验运行阶段做参数格式校验。工具Schema就是Agent和系统之间的一份硬契约——Agent声称要调用某个工具参数必须符合Schema约束否则直接拒掉。# tools/registry.py from jsonschema import validate, ValidationError class ToolRegistry: def __init__(self): self._tools {} def register(self, name: str, schema: dict, handler: callable): # 注册前校验 schema 是否完整 assert type in schema, 工具Schema必须声明type字段 assert properties in schema, 工具Schema必须声明properties字段 self._tools[name] { name: name, schema: schema, handler: handler, } def list(self): return list(self._tools.keys()) def call(self, name: str, args: dict): if name not in self._tools: raise KeyError(f未注册的工具: {name}) tool self._tools[name] try: validate(instanceargs, schematool[schema]) except ValidationError as e: raise ValueError(f工具参数校验失败: {e.message}) from e # 执行工具逻辑前记录审计日志 result tool[handler](**args) # 返回前强制序列化 return to_json(result)这里有一个必须强调的点为什么参数校验这么重要因为Agent本质上是语言模型它生成工具参数时是按概率来的。如果不校验你可能会收到一个根本不存在的日期格式或者漏掉必填字段。JSON Schema校验就是一道硬约束专门拦截这类低级错误。我在多个项目里反复看到加了这一步之后工具调用成功率能提升20个百分点以上。另外一个容易忽略的细节是to_json()这一步。很多工具handler内部会把ORM对象、自定义类实例什么的直接返回如果不强制序列化这些非JSON对象一旦拼进上下文轻则影响后续模型调用重则直接报序列化错误。2.2 Agent能力声明与Reach匹配算法工具注册表解决的是有哪些工具能力声明解决的是这个Agent能用哪些工具、覆盖哪类任务。每个Agent上线前必须提交一份能力声明我用AgentCap这个数据模型来承载。# reach/caps.py from dataclasses import dataclass dataclass class AgentCap: agent_id: str role: str # 例如 customer_service / after_sale tools: list[str] # 允许调用的工具白名单 context_limit: int # 上下文token上限 routing_rules: list[str] # 路由规则关键词 def can_handle(self, task: str) - float: 返回该Agent对任务的匹配分0-1之间 score 0.0 for rule in self.routing_rules: if rule.lower() in task.lower(): score 0.7 return min(score, 1.0)实际项目里我把匹配逻辑做得比示例代码复杂一些。关键词规则以外还会用一个轻量级的embedding模型把任务向量化每条路由规则也有自己的向量算余弦相似度作为语义匹配分。最后加权组合关键词匹配走快路径语义相似度负责兜底。需要特别注意的是匹配分不能只看最高分这个原则。我踩过这样一个坑某个任务本身是售后赔付但售后Agent和客服Agent的语义匹配分都超过了0.6Router按分数把任务派给了客服Agent结果客服Agent只能回复用户我帮你转接一下再跟进白白浪费一次交互。后来我在Reach匹配逻辑里加了一条强制规则一旦出现多个Agent匹配分都超过阈值任务进入双确认流程——Router先生成候选Agent清单让资格分最高的Agent必须做一次接管确认如果它表示当前能力覆盖不了才允许转给次优Agent。接管确认机制在工程上实现也很简单就是多返回一个字段的事。但它在产品体验上的价值很大能有效抑制多Agent背景下常见的乱接单、接不住问题。2.3 上下文管理器分档保留与动态摘要上下文管理是整个系统里最容易翻车的一层。Agent上下文塞满了第一反应通常是把最早的会话记录剪掉。但裁剪绝对有讲究——你要保留的是与任务相关的关键信息而不是字面意义上最早的信息。我的上下文管理器采用两级结构第一级是核心上下文始终完整保留。包含系统身份提示词、当前任务目标、用户最新输入、最近两轮的对话。这部分是Agent做决策时的必须信息动了它Agent就会在不知道用户到底要什么的状态下开始瞎干活。第二级是扩展上下文包括历史工具调用记录、查过文档的摘要、更早轮次的对话。这部分支持压缩压缩策略是分层摘要每3轮旧对话压缩成一段摘要放进扩展区如果扩展区仍然超限就再把摘要做二次合并形成更粗粒度的摘要。# reach/context_manager.py class ContextManager: def build(self, task, chat_history, tool_logs, max_tokens): # 核心区当前任务 最近2轮对话 core self.build_core_block(task, chat_history[-2:]) # 扩展区历史对话 工具调用日志 ext self.build_extend_block(chat_history[:-2], tool_logs) # 优先保障核心区不断压缩扩展区 while core.tokens ext.tokens max_tokens: ext ext.summarize(target_tokenslen(ext.tokens) // 2) return core ext我参考了存储引擎里增量合并的思路每次只对新增的对话做摘要而不是把全部历史重新压缩一遍。这样做能够显著降低token消耗避免每次请求都去全量跑一次摘要模型。核心原则概括成一句话宁可牺牲历史细节不能牺牲当前任务目标。3. 落地实现与完整流程3.1 最小可运行环境与系统骨架如果你是第一次搭这种系统别一上来就把LangChain全家桶装上。我现在的标准环境非常克制Python 3.10、FastAPI、LangGraph、jsonschema、外加一个兼容OpenAI调用格式的SDK。依赖越少后期升级和排查问题就越省心。先起一个最小的Agent服务骨架验证链路通畅再往里面加逻辑# main.py from fastapi import FastAPI from tools.registry import ToolRegistry from reach.router import ReachRouter app FastAPI() registry ToolRegistry() router ReachRouter() app.post(/agent/{agent_id}/run) def run_agent(agent_id: str, payload: dict): cap router.get_cap(agent_id) if not cap: return {error: unknown_agent} if payload.get(tool) not in cap.tools: return {error: tool_not_allowed} # 主流程逻辑在此扩展 return {status: ok}这个骨架虽然简单但已经把最重要的校验逻辑放到了入口处一是Agent是否存在二是这个Agent是否允许调用目标工具。这两道校验防线越早执行后续出乱子的概率就越低。先把原始模型跑通再一步一步把Reach的三层逻辑接进去避免一次性堆砌所有功能导致排查困难。3.2 三步接入Reach声明、注册、绑定接入Agent-Reach的流程概括下来就三步不需要改动Agent内部的大量逻辑。第一步是声明能力。每个Agent上线之前必须写一份AgentCap声明文件。我们团队用YAML管理这份声明不写在代码里方便非技术人员一起来审核# agents/customer_service.yaml agent_id: customer_service role: 售前咨询 tools: - search_products - query_stock - get_delivery_policy context_limit: 12000 routing_rules: - 咨询 - 推荐 - 价格第二步是注册工具。把每个工具的JSON Schema和实际handler注册到ToolRegistry。这里我要强调一个细节handler的函数签名必须和Schema里的properties名称严格对应。如果工具的Schema声明了user_id字段但handler函数里的形参名写成了uid运行时必然报参数错误。这类问题在我们测试阶段反复出现现在注册工具时还加了一道自动化检查遍历Schema里的每个属性名确认它们都能映射到handler的形参。第三步是绑定路由。启动服务时把所有的AgentCap列表加载进ReachRouter。任务进来时Router按匹配分派发派发前再校验一次工具白名单白名单不通过的直接拒绝并说明原因。3.3 一次完整任务流转拆解从咨询到售后的边界切换为了让大家更有体感我用电商场景里的一个完整例子走一遍整套流程。用户发起会话说我上周下的这个订单物流已经三天没动了我要退款。第一步ReachRouter解析任务检测到物流和退款两个关键词同时命中客服Agent和售后Agent。经过语义匹配打分售后Agent得分更高因为用户的核心意图是退款这属于售后赔付的职责范围。任务派发给售后Agent。第二步售后Agent进入处理流程按白名单它只能调用get_order_status、query_logistics、initiate_refund三个工具。它先查订单状态和物流轨迹参数从用户消息中抽取订单号。如果参数抽取失败Reach框架会给Agent一次重试机会并把上次的参数填充错误信息反馈给它修正。这里的设计初衷是一次工具调用失败可能是模型的偶发失误通过反馈纠错能够提高成功率而不是让Agent直接摆烂。第三步售后Agent查到订单还在运输途中根据风控规则当前的物流状态下不能直接执行退款。它判断这个申请超出了自己的处理能力边界于是发起一个handover操作把任务连同上下文摘要一起转给退款风控Agent。这一步在系统里的表现就是Team Reach的应用当前Agent明确自己覆盖不了主动转移而不是硬撑着做决定。关于这个交接过程我要专门说一个实践细节Agent发起handover时候带的不是一句话而是一份交接上下文摘要。这份摘要包括用户原始诉求、已经执行过的工具调用、目前的中间结论。没有这份摘要下一个Agent接到的就是一段孤零零的任务描述它还得回过头来重新问用户一遍情况体验极差。3.4 参数预算与流控设计Agent系统的流控比普通API网关复杂一点因为每次LLM调用的token数是不确定的。我用的策略是分档限流和token预算管理。每个Agent实例配一个按token计费的令牌桶而不是按请求次数。上下文预算按比例划分为三块核心区固定占40%扩展区占50%预留10%给LLM的输出。举个具体例子一个Agent的context_limit是12000 token核心区就是4800 token扩展区6000 token输出预留1200 token。如果某个请求进来时扩展区的原始内容要8000 tokenContextManager就会执行摘要压缩把它压到6000以内。加这个预留区的设计是很重要的。早期版本我把上下文窗口的token全部分配给输入结果经常出现模型写回答写到一半token耗尽直接截断输出。后来强制预留10%给输出这个问题基本消失。如果你跑的是复杂推理任务输出长度需求高建议把预留比例上调到15%左右。4. 生产环境问题排查实录4.1 工具声明了但调用一直失败这个问题的出现频率常年排第一。大多数情况并不是Agent不会调而是Schema写得太宽或者参数名和handler对不上。我印象很深的一个排查案例花了将近半天工具Schema里用的是product_nameAgent从对话里抽取的商品名也能填上但一调用就报Object of type Product is not JSON serializable。问题其实出在handler内部返回了一个ORM对象。工具调用结果最终是要拼进上下文的返回值必须是纯JSON。解决方式是在所有工具handler出口统一过一层to_json()强制序列化从根上杜绝非JSON对象混入链路。4.2 上下文不超限但效果反而变差有一种情况很迷惑token占用明明在预算以内但Agent的回答质量明显下降。排查下来发现问题出在核心上下文区被无关的静态内容占据了——企业介绍、使用规范这些东西被塞进了核心区而用户真正的诉求被挤到扩展区而且可能已经被摘要过。修正方式是让核心区按任务相关度动态组装不再固定塞全套系统提示词。固定身份部分放核心区不变但行为规范类的提示词则按当前任务类型动态选择是否进入核心区。这个改动之后关键任务的目标保持率明显上来了Agent也终于不再忘记用户要什么了。4.3 多Agent协作互相踢皮球这可能是多Agent系统里最头疼的问题现象是任务在A和B之间反复转移谁也不真正负责。我用Reach的三层框架排查根源最终锁定在Team Reach的接管确认机制缺失。上一个版本的处理方式很简单A Agent觉得处理不了就直接发起handover把任务丢给BB接手一看也处理不了又丢回去。来回两三次白白消耗token和时间。现在加上两条强制规则每个Agent处理任务时有接管责任数标记。一旦确认接管除非标记为已完成或明确无法处理否则不允许再次发起相同目标的handover。任务转移超过两次后自动升级到人工兜底流程杜绝无限循环。这两条规则上线后踢皮球问题基本消失。我的核心体会是多Agent协作里责任确认和人工兜底比算法调优更重要。4.4 排查手段与可观测性Agent系统排错最痛苦的地方在于没有痕迹。Agent在中间想了什么、调了哪些工具、上下文怎么被压缩的全凭日志去猜。我在Agent-Reach里把决策痕迹做成了结构化日志。每次工具调用、每次上下文压缩、每次handover都会写一条带trace_id的JSON日志。检索问题的时候按trace_id把整条链路捞出来从上到下看每个环节的输入输出问题通常一眼就能定位。这里我强烈建议从第一天就开启结构化日志不要等出了事再补。Agent系统链路复杂事后追查的成本极高提前埋点顺手又划算。做Agent-Reach这段时间最深刻的体会其实是Agent能不能稳定落地往往不在模型本身而在边界管理。给Agent画清楚能力边界不是限制它恰恰是保护它——让它在可控范围内发挥最大自由度出了边界就诚实地说这个我做不了比硬撑着乱来要靠谱得多。如果你的团队正准备把Agent推向生产我建议先别急着堆功能先把工具注册表、上下文分档、路由确认这三件事做扎实。这三件事做好了后面踩坑的几率会小很多。