AgentScope 这个框架我从 0.9 版本一直跟到 2.x前后做过几个 Java 项目包括客服质检、内部知识问答、供应链订单跟踪这类场景。一路用下来最大的感受是搭一个会聊天的 Agent 不难真正难的是让它“手能干活、脑子里有货”——这恰好对应 AgentScope 里的工具层和知识层。工具层就像给 Agent 装上手能调接口、查库、发消息知识层就像给它配了一个书架让它开口之前先翻到正确的资料页。这篇接着分享我在 Java 实战里怎么把这两层接进 AgentScope以及中间踩过的坑和最后跑通的一套完整方案。1. 为什么 Agent 需要“手”和“书架”——知识与工具层到底解决了什么问题1.1 纯粹靠大模型推理的 Agent 到底缺什么先做一个小实验。你在 AgentScope 里声明一个简单的对话 Agent接上通义千问或者 OpenAI 兼容的模型接口然后问它“帮我查一下订单 D123456789 现在到哪一步了。”它大概率会给你一个很有礼貌、语法完全没毛病的回答“请您稍等我来查询。”但下一秒就卡住了因为它根本没有渠道访问你的订单表也不会真的去调快递物流 API。这就是问题的根源大模型是一个推理引擎不是一个执行引擎。它能从你给的上下文里推断出“应该查订单状态”这个意图但推理结果要落地必须先有可调用的函数也就是工具与此同时它训练时学到的知识往往是泛化的、过时的对一个公司内部特有的业务规则、岗位 SOP、历史项目结论模型其实一无所知因此还需要一块能被实时检索的外部知识库。如果用一句话描述“给 Agent 装上手和书架”这个需求那就是让 Agent 在闭环里既能调用动作又能查资料再基于这两者的返回结果继续推理直到把问题回答完整。1.2 AgentScope 的分层设计Model、Tool、Knowledge 怎么各司其职AgentScope 的 Java 版虽然包名和细节在不同版本会有微调但分层思想一直没变。从下往上大致是Model 层负责与大模型交互封装成 ChatModel、EmbeddingModel 这类对象你只需要给它 API Key 和模型名。Agent 层负责编排对话逻辑。你通常会接触到 ReActAgent、PipelineAgent 这类角色它们决定先把问题拆成几步以及每一步用哪个工具、给模型看哪些上下文。Tool 层把外部能力包装成标准方法。比如查询订单、发送通知、回写数据库本质上是把业务系统已有的能力暴露给 Agent 使用。Knowledge 层负责把文档切成块、向量化、存储、检索。Agent 在回答问题前会先做一次相似度搜索把最相关的片段拼进 prompt。在实践里面我对这层的理解是它就是流水线中的工人和资料室。Agent 是组长负责看问题、定方案工具层是工人的手负责具体执行知识层是资料室负责随时递上正确的资料。组长不会自己动手也不会背下所有资料但每一环都缺一不可。1.3 用骑手来打比方推理、工具、知识缺一不可我经常用“外卖骑手”来解释这三者的关系。骑手的脑子是推理能力他能听懂“用户要一碗牛肉面送到 3 号楼”但送餐必须要有电动车和保温箱这是工具他还要知道路怎么走、哪个小区几点能进、用户留的备注是什么这是知识。如果没有电动车听得懂也送不到如果没有路线知识送得到也大概率会超时。做 Agent 其实一模一样。你给它挂上百个工具但没有知识它面对“这个客户上次投诉过什么问题”时会直接懵你给它塞了一书架资料但没有工具它查到客户地址也没法给客户发短信。所以这篇博客的整套实践思路就是把“手”和“书架”同时装好让 Agent 既有执行力又有背景知识这才算完整。2. 工具层实战给 Agent 装上手2.1 先想清楚哪些能力值得做成工具在写代码之前我建议先做一次“能力盘点”。把你业务系统里的接口全部列出来然后按两个标准筛选能不能被自然语言触发以及返回值能不能被模型读懂。比如“按照订单号查物流轨迹”就很适合因为用户问一句“我的货到哪了”就能触发“把日志里的堆栈打到本地磁盘”就没必要暴露给 Agent因为这是内部运维动作普通用户永远不需要提。我的经验是工具数量一开始控制在 5 到 10 个以内不要贪多。很多人上来就接 30 个工具接口结果模型反而不知道该选哪个甚至出现选错工具的情况。工具越少描述越精确模型的选择准确率越高。等基础链路跑通了再慢慢扩充。2.2 用注解方式注册一个订单查询工具AgentScope Java 里写工具的方法非常直观。以我之前做的订单客服 Agent 为例我写了这样一个定时工具类public class OrderToolkit { Tool( name query_order, description 根据订单号查询最新物流状态和预计送达时间, params { Param(name orderNo, type string, description 订单号例如 D202501011234), Param(name customerPhone, type string, description 下单手机号后四位用于身份校验) } ) public String queryOrder(String orderNo, String customerPhone) { // 调用自己系统的订单服务 OrderDO order orderService.queryByOrderNo(orderNo); if (order null) { return {\code\: 400, \msg\: \订单不存在\}; } if (!order.getPhoneTail().equals(customerPhone)) { return {\code\: 401, \msg\: \手机号校验不通过\}; } String logistics logisticsService.fetchLatest(orderNo); return String.format( {\code\: 200, \status\: \%s\, \detail\: \%s\}, logistics.getStatusName(), logistics.getTraceDetail() ); } }这里有几处很容易载跟头我特别说明下。第一返回值一定要是结构化的字符串。别把对象直接序列化成非常长的 JSON模型的上下文窗口有限一个上千字的 JSON 返回会把工具结果的优先级冲淡导致后续推理绕来绕去。我给工具的返回值定了个简单协议要么是 200 成功加关键信息要么是 400/401 这类错误码加一句话原因。这样模型一眼就能判断下一步该干什么。第二工具方法要自己做好参数校验。很多人把校验寄托在 Agent 内部实际上 Agent 只是个编排器它不会替业务系统做数据权限控制。手机号后四位校验、订单归属校验必须在工具方法里完成这属于安全底线。第三不要在工作线程里同步等待很久。如果你的工具要调第三方物流接口我建议在工具内部加超时控制一般 2 到 3 秒否则一个工具调用就可能拖垮整个对话响应时间。2.3 工具注册进 Agent 配置的方式当工具类写好了接下来一步就是把它挂到 Agent 上。在 AgentScope Java 里大致是这样AgentConfig config new AgentConfig(); config.setModelName(qwen-plus); config.addTool(new OrderToolkit()); ReActAgent agent new ReActAgent(config);如果你的工具不是靠注解注册而是自己封装成一个 ToolCaller 类那也无所谓核心逻辑是一致的在 Agent 初始化时把你的工具实例注入进去Agent 运行时会把工具列表转成模型能识别的 JSON Schema并在需要时回调执行。工具注册成功以后你可以打印一遍最终 JSON Schema重点看函数名、参数描述是否清晰。这一步我每次都会做原因很简单模型真正看到的是 JSON Schema不是我们的 Java 方法名。如果你的方法叫do2参数叫x、y模型基本不会用换成query_order、orderNo、phoneTail模型一眼就懂。2.4 工具边界设计与权限隔离关于工具层的边界设计我总结成一个表格供参考设计点建议做法理由输入校验工具内部做白名单校验不依赖模型模型偶尔会传错参数工具要把好最后一道关口输出长度压缩关键信息避免长 JSON节省 token也让模型更快提取重点超时控制2 至 3 秒超时异常统一返回错误码防止第三方接口慢导致对话卡死权限隔离按用户维度做数据隔离客服 Agent 里不同客服只能查自有客户数据工具数量先 5 到 10 个后续再扩充工具列表过长会稀释模型选择准确率幂等性读操作天然幂等写操作建议带操作人防止重复调用造成脏数据最后一个“幂等性”值得展开。Agent 在发生超时或者模型异常时可能会把同一个工具调用重复执行。对于查询类接口无所谓但对于“修改订单备注”“发送短信”这类写操作就必须考虑重复调用造成的影响。我在实践里给写操作加上业务单号比如requestId工具内部检查这个单号是否执行过是则直接返回上一次结果从源头防止重复执行。3. 知识层实战给 Agent 搭好书架3.1 知识层的三种组织方式文档、向量、图谱说完“手”接着来说“书架”。知识层的组织方式我实际操作中接触过三种分别适用不同场景。文档型适合产品手册、制度文件、FAQ 这种段落式内容。直接把文档切块放到向量库里。向量型把每个知识块用 Embedding 模型转成向量查询时用余弦相似度计算最相近的内容。这是当前 RAG 的主流姿势。AgentScope Java 里既支持直连向量数据库也可以用内置的向量检索组件。图谱型适合实体关系极强的场景比如“哪个部门负责哪套系统”“这个客户的下单流程是怎样的”。但是图谱构建成本高非必要我不会第一版就上。我自己的经验是先做“文档 向量”这一套80% 的内部知识问答都能覆盖上图谱通常是在文档检索满足不了跨多跳查询之后才考虑的事情。3.2 完整落地一套 RAG 检索从文档切块到组装知识片段以一个设备运维知识库为例我会这么处理。第一步把 PDF、Word、Markdown 全部转成纯文本。这一步千万别偷懒很多时候检索效果差不是因为向量库不好而是源文档里全是标题和表格切出来就是一堆碎片。第二步文本切块。我习惯按“语义完整”优先而不是硬按字符数切。一个简单的切块策略是先按段落拆段落太长再按句子拆每个块控制在 200 到 500 个汉字之间。第三步调用 Embedding 模型生成向量。我常用text-embedding-v3这类模型生成 1024 维向量存入 pgvector 或 Elasticsearch。如果你只是本地实验用一个开源的 sentence 级模型也够用。到了查询阶段过程大概是这样的String question 如何配置日志采集器; ListFloat queryVector embeddingModel.embed(question); ListKnowledgeChunk chunks vectorStore.search(queryVector, 5); String context chunks.stream() .map(c - 【来源】 c.getDocumentId() \n c.getText()) .collect(Collectors.joining(\n\n)); String prompt preprocessPromptTemplate 背景资料\n context \n用户问题 question;这里有个细节需要强调检索时用的向量必须和入库时用同一个 Embedding 模型。我遇到好几次检索效果突然变差排查了半天才发现是有人把入库模型从线上版本换成了测试版本向量空间不一致相似度自然全乱套。3.3 图书摆放技巧分块、元数据与相关性排序书架不是把书随便堆上去就完了知识库也一样。根据我和几个同行的交流下面几个经验基本是通用的。滑动窗口切块比如每块 400 字符步长 100 字符这样前后块之间有重叠能避免一句话被拦腰截断找不到主语。元数据必填每个块都带上文档编号、标题、更新时间、所属业务线。元数据有两个作用一是检索后可以按业务线过滤二是给模型标注来源方便它引用。多路召回不要只依赖一种检索方式。我常用的做法是“向量检索”和“关键词检索”并行各取前几名再合并去重交给模型判断。这样能覆盖语义相似但关键词完全不同的情况。相关性排序公式上你不需要做太复杂直接用余弦相似度降序再截断到 topK。topK 一般取 4 到 6太少可能漏资料太多会把 prompt 撑长、淹没重点。我用过一个参考经验知识块总长度控制在 1500 个汉字以内多出的检索结果直接丢弃。3.4 知识层和工具层怎么配合回答一个复杂问题单纯把知识检索结果塞给模型还称不上知识层与工具层的配合。一个更合理的链路是用户问“我刚买的设备一直连不上网怎么办”。Agent 先针对问题做切词和意图判断发现是“网络配置类”问题。知识层检索出对应的设备联网配置文档。同时工具层可以根据用户的设备 ID调用query_device_info查一下这台设备的固件版本。模型结合“文档描述的操作步骤”和“这台设备的固件实际情况”给出更精准的回答而不是让用户盲试。我这里尤其推荐一个做法把知识检索的时机拆成“主动检索”和“被动检索”两种。主动检索是用户问题到来时先查一次被动检索是在工具返回的字段含义不明时再补查一次知识库。两种检索结果都放入一个短暂上下文窗口用完即清理别塞进长期记忆否则会干扰后续对话。4. 把两者拼进 AgentScope 主链路单轮问答到多轮对话4.1 组合配置一个 Agent 同时挂载工具和知识库从前面的代码可以看到工具是直接挂到 Agent 配置里的。知识库的挂载方式类似有些版本里是通过一个 Retriever 组件塞进去有些则是通过 Agent 构造参数传入。一个典型配置如下AgentConfig config new AgentConfig(); config.setModelName(qwen-plus); OrderToolkit orderToolkit new OrderToolkit(); DeviceToolkit deviceToolkit new DeviceToolkit(); config.addTool(orderToolkit); config.addTool(deviceToolkit); KnowledgeBase knowledgeBase new KnowledgeBase(); knowledgeBase.setVectorStore(vectorStore); knowledgeBase.setEmbeddingModel(embeddingModel); config.setKnowledgeBase(knowledgeBase); ReActAgent agent new ReActAgent(config);这样配置完以后Agent 的每一次回答流程基本都是接收用户消息 - 判断意图 - 决定是否调工具或查知识库 - 拿到结果后组织最终回复。这个流程表面上看起来简单但实际跑起来很容易出现两个问题。第一个问题是循环控制。如果模型拿到的工具结果不理想它有可能反复调用同一个工具形成死循环。我一般会给 Agent 设最大推理步数比如 5 步超过就直接返回当前结果不再继续。第二个问题是上下文膨胀。每一轮工具调用和知识检索都会产生新的消息如果不清理多轮对话后上下文越来越长token 成本直线上升。我通常的做法是只把“用户原问题、工具返回的关键结果、最终回答”这三部分留在上下文里中间的一次次中间推理不全部保留。4.2 单轮执行流程从用户问题到最终回复单轮问答是后面所有复杂场景的地基。我把执行流程拆成七个步骤Agent 收到用户消息。系统提示词引导模型决定是否需要查询知识库。若需要先向知识库发起 topK 检索拿到若干相关片段。系统提示词引导模型决定是否需要调用工具。若需要Agent 根据 JSON Schema 生成参数调用对应 Java 方法。工具返回结构化结果模型把结果和知识片段合并到上下文。模型组织最终回答返回给用户。在这七步里我特别提醒一个用户体验的细节Agent 做知识检索和工具调用的时候最好先给用户一个中间响应比如“正在查询订单信息请稍候”。因为工具和知识检索通常会花费 1 到 3 秒用户如果盯着空白界面很容易误以为服务挂了。我在实现里是先把这个中间响应通过 WebSocket 推给前端然后再走后续步骤。4.3 多轮对话中知识检索结果和工具调用结果的取舍多轮对话比单轮要难一个量级因为你不能每次都对同一问题“重复翻书”。我踩过一个比较重的坑用户问了一次“我的货到哪了”Agent 查了知识库里面有一篇通用的物流 FAQ又查了工具拿到了实时轨迹这个回答很漂亮。但用户接着追问“你们多久能送到”Agent 又把物流 FAQ 翻出来结合上一次的工具结果又回答了一遍。表面看没毛病实际上重复查了一次知识库浪费 token而且如果物流状态在这几分钟内变了上一次的缓存结果反而会误导。我的改进方案是知识检索只在“当前上下文没有足够依据”时触发。具体做法是在模型推理前加一个判断先把历史对话里已有的信息提取出来如果发现已经包含答案所需的关键事实比如物流状态、订单号就不再触发知识检索直接让模型回答。这个判断可以用规则实现也可以用一个小模型做快速分类成本不高。工具调用结果的取舍也要遵循类似原则。工具结果一旦被采用我会把它标记为“已确认事实”在同一会话周期内不再重复调用同一工具获取同一类数据除非用户明确要求刷新。这样既保证准确性又省时间和成本。5. 并发场景Agent 服务扛得住多少流量5.1 并发瓶颈到底在哪里“AI Agent 怎么扛并发”是最近讨论特别多的话题。在 AgentScope Java 服务里真正的并发瓶颈其实不只是“Agent 本身”而是三个叠加在一起的因素大模型 API 网关每一次对话都要请求模型接口而大模型接口响应慢通常 1 到 5 秒它的 QPS 上限直接决定你的服务上限。工具层外部依赖每个工具背后可能对应订单服务、物流接口、数据库查询。外部接口如果扛不住Agent 再聪明也没用。知识库检索性能向量检索在大数据量下会有明显延迟连接池不够时也会拖后腿。所以搞清楚一个事实很重要你无法让模型 API 从 2 秒变成 200 毫秒你能做的是把并发压力尽量从模型 API 上挪开比如减少无效调用、合并相似请求、使用缓存。5.2 线程池、超时与有状态/无状态设计我自己在 Spring Boot 项目里给 Agent 单独开了一个线程池没有直接用默认的 Tomcat 线程池。原因很简单Agent 任务都是 IO 密集型线程不能太少也不能忙等但也不适合无脑开上千线程因为每个线程背后可能同时挂着一个模型 API 长连接。推荐一个起步配置实际效果稳ThreadPoolExecutor agentPool new ThreadPoolExecutor( 20, // 核心线程数 80, // 最大线程数 60, TimeUnit.SECONDS, new SynchronousQueue(), // 不积压任务满了就触发拒绝策略 new ThreadPoolExecutor.CallerRunsPolicy() );并发的另一个关键设计是无状态 Agent 实例。很多 Agent 框架鼓励把会话记忆挂在 Agent 对象里但这样一旦实例需要共享复用就会出现状态错乱。我建议的做法是Agent 实例本身不保存会话状态会话状态放到外部的 Redis 里以 sessionId 为 key 存取。这样同一时间的几百个会话可以共享为数不多的几个 Agent 实例并发能力一下子就被释放出来了。5.3 缓存策略与限流降级应对并发最简单有效的手段只有四个字减少重复。我的实际经验是对三种数据做缓存效果最好知识检索结果用户问“设备开不了机”这种高频问题同样的检索向量和结果可以缓存 5 到 10 分钟没必要每次重新查向量库。工具查询结果订单状态、物流轨迹这类数据虽然实时性要求高但 30 秒到 1 分钟的缓存完全可接受。我用 Caffeine 做了个短时缓存命中率很高。模型回答某些通用 FAQ 的完整答案可以缓存更久甚至直接返回模板。限流方面我建议按用户维度做配额而不是全局限流。因为 Agent 服务面向多租户时某一个大客户可能独占所有模型 API 配额影响其他客户。用 Redis 存每个用户的分钟级调用次数达到阈值就给 Agent 返回“今天太忙了稍后再试”的兜底回复。5.4 一个并发压测的参考结果我拿一个 2C4G 的测试机做过一次粗压测配置是 20 到 80 线程池模型用 qwen-plus工具和知识库都正常挂载单轮问答耗时约 2.8 秒。压测结果是20 并发时QPS 大概 7 左右成功率 99%升到 50 并发时QPS 约 11但 P99 开始出现 8 秒以上的超时。这说明瓶颈已经出现在模型 API 和外部依赖上提高线程数已经没有明显收益。根据这个结果我实践中的建议是不要盲目追求高并发而是把目标定在“在用户可接受的 5 秒内完成回答”。如果单轮要 3 秒留出 2 秒的容错一旦 P99 超过 6 秒就要考虑异步化处理而不是硬扛。6. 我踩过的一些坑与排查思路6.1 工具注册了但模型就是不调用这是使用 AgentScope Java 工具层最常见的坑之一。工具明明注册成功了模型却反复说“我没有相关工具可以回答”。排查方向按以下顺序先确认工具列表是否成功转成了 JSON Schema 并出现在请求里。打印一次完整的请求日志看模型实际看到的东西。检查工具描述是否包含足够的触发信号。比如你的工具叫“查询物流”但描述里没提“快递、运单号、发货、揽收”这些词模型就很难联想到用它。检查参数是否过度复杂。如果一个工具需要五个必填参数模型凑不齐参数时宁可不调用也不会去编造。我加过一条经验法则每个工具的必填参数尽量不要超过 3 个。超过 3 个时可以考虑将多个参数包装成一个 JSON 字符串由工具内部解析降低模型的调用门槛。6.2 知识检索命中很多但回答仍然不对这个问题我花了不少时间排查。发现命中文档不等于命中答案因为相似度检索看的是“像不像”不是“对不对”。比如用户问“打印机连不上 WiFi 怎么办”检索出的文档可能是“如何配置打印机的 WiFi 密码”也可能是“如何连接蓝牙打印机”两者在向量空间里都很接近但前者才是真正需要的。解决方法是两层。第一层是检索阶段增加领域过滤比如根据用户问题先判断业务线再限定业务线范围检索第二层是生成阶段增加一个校验步骤让模型判断“当前资料是否足以回答”不足则明确回复“知识库里暂时没有相关内容”而不是强行瞎编。6.3 上下文越到后面越乱token 成本失控多轮对话做久了以后我发现 prompt 里堆满了历史消息、知识片段、工具返回的 JSON。有一次一个会话进行到第 10 轮单次请求的 token 数已经接近模型上下文一半回答质量反而明显下降。这是因为模型对超长上下文的处理能力是有限的越靠后的内容越容易“淹没”前面的关键信息。我的做法是给 Agent 的上下文做分级管理系统提示词始终保留占很小比例。核心事实保留本会话已确认的关键信息比如订单号、客户诉求、上一步工具结果。历史对话只保留最近两轮完整对话更早的压缩成摘要。实现摘要可以用一个小模型做也可以用规则截断。我优先级推荐规则截断起步因为小模型额外调用会引入延迟和成本规则截断立竿见影。6.4 版本升级带来的兼容性波动AgentScope 从 0.9 到 2.x 走得不慢Java 版的 API 有过几次调整。比如早期工具注册方式和现在 2.x 的注解方式就不同知识库组件的包名也换过。如果你在升级版本后发现工具不被识别、知识库不生效请优先去查官方迁移文档里的 Breaking Changes。一个规避升级痛苦的小偏方把工具层和知识层封装在你的业务模块里不直接依赖 AgentScope 内部的类型。这样即使框架升级你只需要修改集成层的适配代码业务方法本身几乎不用动。我在几个项目里都用了这招实测能省掉大量踩坑时间。常见问题可能原因排查手段模型不调用工具工具描述不清晰、参数过多打印请求日志检查 JSON Schema知识检索结果不可用向量模型不一致、切块不当核对入库与查询的 Embedding 模型多轮对话越走越偏上下文过长、历史信息挤压压缩历史对话只保留核心事实并发一高就超时线程池配置不当或外部接口过慢单独配 Agent 线程池加缓存降级最后再分享一点实际体会把知识与工具层接入 AgentScope Java本质上是在给 Agent 设计“边界”。工具定义了这个 Agent 能做什么知识库定义了这个 Agent 知道什么。这两件事做得越清楚Agent 的表现就越稳定而不是偶尔灵光一现、经常翻车。如果你也是刚开始做 Agent我建议先别急着接十几个工具、灌一堆文档可以像我一样先拿 5 个工具加一个 30 篇文档的小知识库把完整链路跑通再逐步扩展。等你看到模型准确调用工具、又从知识库深处找到一段关键资料、最后组织出近乎完美的回答时你会觉得前面这些打磨都是值得的。 AgentScope工具层与知识层实战：给Agent装上手和书架
AgentScope 这个框架我从 0.9 版本一直跟到 2.x前后做过几个 Java 项目包括客服质检、内部知识问答、供应链订单跟踪这类场景。一路用下来最大的感受是搭一个会聊天的 Agent 不难真正难的是让它“手能干活、脑子里有货”——这恰好对应 AgentScope 里的工具层和知识层。工具层就像给 Agent 装上手能调接口、查库、发消息知识层就像给它配了一个书架让它开口之前先翻到正确的资料页。这篇接着分享我在 Java 实战里怎么把这两层接进 AgentScope以及中间踩过的坑和最后跑通的一套完整方案。1. 为什么 Agent 需要“手”和“书架”——知识与工具层到底解决了什么问题1.1 纯粹靠大模型推理的 Agent 到底缺什么先做一个小实验。你在 AgentScope 里声明一个简单的对话 Agent接上通义千问或者 OpenAI 兼容的模型接口然后问它“帮我查一下订单 D123456789 现在到哪一步了。”它大概率会给你一个很有礼貌、语法完全没毛病的回答“请您稍等我来查询。”但下一秒就卡住了因为它根本没有渠道访问你的订单表也不会真的去调快递物流 API。这就是问题的根源大模型是一个推理引擎不是一个执行引擎。它能从你给的上下文里推断出“应该查订单状态”这个意图但推理结果要落地必须先有可调用的函数也就是工具与此同时它训练时学到的知识往往是泛化的、过时的对一个公司内部特有的业务规则、岗位 SOP、历史项目结论模型其实一无所知因此还需要一块能被实时检索的外部知识库。如果用一句话描述“给 Agent 装上手和书架”这个需求那就是让 Agent 在闭环里既能调用动作又能查资料再基于这两者的返回结果继续推理直到把问题回答完整。1.2 AgentScope 的分层设计Model、Tool、Knowledge 怎么各司其职AgentScope 的 Java 版虽然包名和细节在不同版本会有微调但分层思想一直没变。从下往上大致是Model 层负责与大模型交互封装成 ChatModel、EmbeddingModel 这类对象你只需要给它 API Key 和模型名。Agent 层负责编排对话逻辑。你通常会接触到 ReActAgent、PipelineAgent 这类角色它们决定先把问题拆成几步以及每一步用哪个工具、给模型看哪些上下文。Tool 层把外部能力包装成标准方法。比如查询订单、发送通知、回写数据库本质上是把业务系统已有的能力暴露给 Agent 使用。Knowledge 层负责把文档切成块、向量化、存储、检索。Agent 在回答问题前会先做一次相似度搜索把最相关的片段拼进 prompt。在实践里面我对这层的理解是它就是流水线中的工人和资料室。Agent 是组长负责看问题、定方案工具层是工人的手负责具体执行知识层是资料室负责随时递上正确的资料。组长不会自己动手也不会背下所有资料但每一环都缺一不可。1.3 用骑手来打比方推理、工具、知识缺一不可我经常用“外卖骑手”来解释这三者的关系。骑手的脑子是推理能力他能听懂“用户要一碗牛肉面送到 3 号楼”但送餐必须要有电动车和保温箱这是工具他还要知道路怎么走、哪个小区几点能进、用户留的备注是什么这是知识。如果没有电动车听得懂也送不到如果没有路线知识送得到也大概率会超时。做 Agent 其实一模一样。你给它挂上百个工具但没有知识它面对“这个客户上次投诉过什么问题”时会直接懵你给它塞了一书架资料但没有工具它查到客户地址也没法给客户发短信。所以这篇博客的整套实践思路就是把“手”和“书架”同时装好让 Agent 既有执行力又有背景知识这才算完整。2. 工具层实战给 Agent 装上手2.1 先想清楚哪些能力值得做成工具在写代码之前我建议先做一次“能力盘点”。把你业务系统里的接口全部列出来然后按两个标准筛选能不能被自然语言触发以及返回值能不能被模型读懂。比如“按照订单号查物流轨迹”就很适合因为用户问一句“我的货到哪了”就能触发“把日志里的堆栈打到本地磁盘”就没必要暴露给 Agent因为这是内部运维动作普通用户永远不需要提。我的经验是工具数量一开始控制在 5 到 10 个以内不要贪多。很多人上来就接 30 个工具接口结果模型反而不知道该选哪个甚至出现选错工具的情况。工具越少描述越精确模型的选择准确率越高。等基础链路跑通了再慢慢扩充。2.2 用注解方式注册一个订单查询工具AgentScope Java 里写工具的方法非常直观。以我之前做的订单客服 Agent 为例我写了这样一个定时工具类public class OrderToolkit { Tool( name query_order, description 根据订单号查询最新物流状态和预计送达时间, params { Param(name orderNo, type string, description 订单号例如 D202501011234), Param(name customerPhone, type string, description 下单手机号后四位用于身份校验) } ) public String queryOrder(String orderNo, String customerPhone) { // 调用自己系统的订单服务 OrderDO order orderService.queryByOrderNo(orderNo); if (order null) { return {\code\: 400, \msg\: \订单不存在\}; } if (!order.getPhoneTail().equals(customerPhone)) { return {\code\: 401, \msg\: \手机号校验不通过\}; } String logistics logisticsService.fetchLatest(orderNo); return String.format( {\code\: 200, \status\: \%s\, \detail\: \%s\}, logistics.getStatusName(), logistics.getTraceDetail() ); } }这里有几处很容易载跟头我特别说明下。第一返回值一定要是结构化的字符串。别把对象直接序列化成非常长的 JSON模型的上下文窗口有限一个上千字的 JSON 返回会把工具结果的优先级冲淡导致后续推理绕来绕去。我给工具的返回值定了个简单协议要么是 200 成功加关键信息要么是 400/401 这类错误码加一句话原因。这样模型一眼就能判断下一步该干什么。第二工具方法要自己做好参数校验。很多人把校验寄托在 Agent 内部实际上 Agent 只是个编排器它不会替业务系统做数据权限控制。手机号后四位校验、订单归属校验必须在工具方法里完成这属于安全底线。第三不要在工作线程里同步等待很久。如果你的工具要调第三方物流接口我建议在工具内部加超时控制一般 2 到 3 秒否则一个工具调用就可能拖垮整个对话响应时间。2.3 工具注册进 Agent 配置的方式当工具类写好了接下来一步就是把它挂到 Agent 上。在 AgentScope Java 里大致是这样AgentConfig config new AgentConfig(); config.setModelName(qwen-plus); config.addTool(new OrderToolkit()); ReActAgent agent new ReActAgent(config);如果你的工具不是靠注解注册而是自己封装成一个 ToolCaller 类那也无所谓核心逻辑是一致的在 Agent 初始化时把你的工具实例注入进去Agent 运行时会把工具列表转成模型能识别的 JSON Schema并在需要时回调执行。工具注册成功以后你可以打印一遍最终 JSON Schema重点看函数名、参数描述是否清晰。这一步我每次都会做原因很简单模型真正看到的是 JSON Schema不是我们的 Java 方法名。如果你的方法叫do2参数叫x、y模型基本不会用换成query_order、orderNo、phoneTail模型一眼就懂。2.4 工具边界设计与权限隔离关于工具层的边界设计我总结成一个表格供参考设计点建议做法理由输入校验工具内部做白名单校验不依赖模型模型偶尔会传错参数工具要把好最后一道关口输出长度压缩关键信息避免长 JSON节省 token也让模型更快提取重点超时控制2 至 3 秒超时异常统一返回错误码防止第三方接口慢导致对话卡死权限隔离按用户维度做数据隔离客服 Agent 里不同客服只能查自有客户数据工具数量先 5 到 10 个后续再扩充工具列表过长会稀释模型选择准确率幂等性读操作天然幂等写操作建议带操作人防止重复调用造成脏数据最后一个“幂等性”值得展开。Agent 在发生超时或者模型异常时可能会把同一个工具调用重复执行。对于查询类接口无所谓但对于“修改订单备注”“发送短信”这类写操作就必须考虑重复调用造成的影响。我在实践里给写操作加上业务单号比如requestId工具内部检查这个单号是否执行过是则直接返回上一次结果从源头防止重复执行。3. 知识层实战给 Agent 搭好书架3.1 知识层的三种组织方式文档、向量、图谱说完“手”接着来说“书架”。知识层的组织方式我实际操作中接触过三种分别适用不同场景。文档型适合产品手册、制度文件、FAQ 这种段落式内容。直接把文档切块放到向量库里。向量型把每个知识块用 Embedding 模型转成向量查询时用余弦相似度计算最相近的内容。这是当前 RAG 的主流姿势。AgentScope Java 里既支持直连向量数据库也可以用内置的向量检索组件。图谱型适合实体关系极强的场景比如“哪个部门负责哪套系统”“这个客户的下单流程是怎样的”。但是图谱构建成本高非必要我不会第一版就上。我自己的经验是先做“文档 向量”这一套80% 的内部知识问答都能覆盖上图谱通常是在文档检索满足不了跨多跳查询之后才考虑的事情。3.2 完整落地一套 RAG 检索从文档切块到组装知识片段以一个设备运维知识库为例我会这么处理。第一步把 PDF、Word、Markdown 全部转成纯文本。这一步千万别偷懒很多时候检索效果差不是因为向量库不好而是源文档里全是标题和表格切出来就是一堆碎片。第二步文本切块。我习惯按“语义完整”优先而不是硬按字符数切。一个简单的切块策略是先按段落拆段落太长再按句子拆每个块控制在 200 到 500 个汉字之间。第三步调用 Embedding 模型生成向量。我常用text-embedding-v3这类模型生成 1024 维向量存入 pgvector 或 Elasticsearch。如果你只是本地实验用一个开源的 sentence 级模型也够用。到了查询阶段过程大概是这样的String question 如何配置日志采集器; ListFloat queryVector embeddingModel.embed(question); ListKnowledgeChunk chunks vectorStore.search(queryVector, 5); String context chunks.stream() .map(c - 【来源】 c.getDocumentId() \n c.getText()) .collect(Collectors.joining(\n\n)); String prompt preprocessPromptTemplate 背景资料\n context \n用户问题 question;这里有个细节需要强调检索时用的向量必须和入库时用同一个 Embedding 模型。我遇到好几次检索效果突然变差排查了半天才发现是有人把入库模型从线上版本换成了测试版本向量空间不一致相似度自然全乱套。3.3 图书摆放技巧分块、元数据与相关性排序书架不是把书随便堆上去就完了知识库也一样。根据我和几个同行的交流下面几个经验基本是通用的。滑动窗口切块比如每块 400 字符步长 100 字符这样前后块之间有重叠能避免一句话被拦腰截断找不到主语。元数据必填每个块都带上文档编号、标题、更新时间、所属业务线。元数据有两个作用一是检索后可以按业务线过滤二是给模型标注来源方便它引用。多路召回不要只依赖一种检索方式。我常用的做法是“向量检索”和“关键词检索”并行各取前几名再合并去重交给模型判断。这样能覆盖语义相似但关键词完全不同的情况。相关性排序公式上你不需要做太复杂直接用余弦相似度降序再截断到 topK。topK 一般取 4 到 6太少可能漏资料太多会把 prompt 撑长、淹没重点。我用过一个参考经验知识块总长度控制在 1500 个汉字以内多出的检索结果直接丢弃。3.4 知识层和工具层怎么配合回答一个复杂问题单纯把知识检索结果塞给模型还称不上知识层与工具层的配合。一个更合理的链路是用户问“我刚买的设备一直连不上网怎么办”。Agent 先针对问题做切词和意图判断发现是“网络配置类”问题。知识层检索出对应的设备联网配置文档。同时工具层可以根据用户的设备 ID调用query_device_info查一下这台设备的固件版本。模型结合“文档描述的操作步骤”和“这台设备的固件实际情况”给出更精准的回答而不是让用户盲试。我这里尤其推荐一个做法把知识检索的时机拆成“主动检索”和“被动检索”两种。主动检索是用户问题到来时先查一次被动检索是在工具返回的字段含义不明时再补查一次知识库。两种检索结果都放入一个短暂上下文窗口用完即清理别塞进长期记忆否则会干扰后续对话。4. 把两者拼进 AgentScope 主链路单轮问答到多轮对话4.1 组合配置一个 Agent 同时挂载工具和知识库从前面的代码可以看到工具是直接挂到 Agent 配置里的。知识库的挂载方式类似有些版本里是通过一个 Retriever 组件塞进去有些则是通过 Agent 构造参数传入。一个典型配置如下AgentConfig config new AgentConfig(); config.setModelName(qwen-plus); OrderToolkit orderToolkit new OrderToolkit(); DeviceToolkit deviceToolkit new DeviceToolkit(); config.addTool(orderToolkit); config.addTool(deviceToolkit); KnowledgeBase knowledgeBase new KnowledgeBase(); knowledgeBase.setVectorStore(vectorStore); knowledgeBase.setEmbeddingModel(embeddingModel); config.setKnowledgeBase(knowledgeBase); ReActAgent agent new ReActAgent(config);这样配置完以后Agent 的每一次回答流程基本都是接收用户消息 - 判断意图 - 决定是否调工具或查知识库 - 拿到结果后组织最终回复。这个流程表面上看起来简单但实际跑起来很容易出现两个问题。第一个问题是循环控制。如果模型拿到的工具结果不理想它有可能反复调用同一个工具形成死循环。我一般会给 Agent 设最大推理步数比如 5 步超过就直接返回当前结果不再继续。第二个问题是上下文膨胀。每一轮工具调用和知识检索都会产生新的消息如果不清理多轮对话后上下文越来越长token 成本直线上升。我通常的做法是只把“用户原问题、工具返回的关键结果、最终回答”这三部分留在上下文里中间的一次次中间推理不全部保留。4.2 单轮执行流程从用户问题到最终回复单轮问答是后面所有复杂场景的地基。我把执行流程拆成七个步骤Agent 收到用户消息。系统提示词引导模型决定是否需要查询知识库。若需要先向知识库发起 topK 检索拿到若干相关片段。系统提示词引导模型决定是否需要调用工具。若需要Agent 根据 JSON Schema 生成参数调用对应 Java 方法。工具返回结构化结果模型把结果和知识片段合并到上下文。模型组织最终回答返回给用户。在这七步里我特别提醒一个用户体验的细节Agent 做知识检索和工具调用的时候最好先给用户一个中间响应比如“正在查询订单信息请稍候”。因为工具和知识检索通常会花费 1 到 3 秒用户如果盯着空白界面很容易误以为服务挂了。我在实现里是先把这个中间响应通过 WebSocket 推给前端然后再走后续步骤。4.3 多轮对话中知识检索结果和工具调用结果的取舍多轮对话比单轮要难一个量级因为你不能每次都对同一问题“重复翻书”。我踩过一个比较重的坑用户问了一次“我的货到哪了”Agent 查了知识库里面有一篇通用的物流 FAQ又查了工具拿到了实时轨迹这个回答很漂亮。但用户接着追问“你们多久能送到”Agent 又把物流 FAQ 翻出来结合上一次的工具结果又回答了一遍。表面看没毛病实际上重复查了一次知识库浪费 token而且如果物流状态在这几分钟内变了上一次的缓存结果反而会误导。我的改进方案是知识检索只在“当前上下文没有足够依据”时触发。具体做法是在模型推理前加一个判断先把历史对话里已有的信息提取出来如果发现已经包含答案所需的关键事实比如物流状态、订单号就不再触发知识检索直接让模型回答。这个判断可以用规则实现也可以用一个小模型做快速分类成本不高。工具调用结果的取舍也要遵循类似原则。工具结果一旦被采用我会把它标记为“已确认事实”在同一会话周期内不再重复调用同一工具获取同一类数据除非用户明确要求刷新。这样既保证准确性又省时间和成本。5. 并发场景Agent 服务扛得住多少流量5.1 并发瓶颈到底在哪里“AI Agent 怎么扛并发”是最近讨论特别多的话题。在 AgentScope Java 服务里真正的并发瓶颈其实不只是“Agent 本身”而是三个叠加在一起的因素大模型 API 网关每一次对话都要请求模型接口而大模型接口响应慢通常 1 到 5 秒它的 QPS 上限直接决定你的服务上限。工具层外部依赖每个工具背后可能对应订单服务、物流接口、数据库查询。外部接口如果扛不住Agent 再聪明也没用。知识库检索性能向量检索在大数据量下会有明显延迟连接池不够时也会拖后腿。所以搞清楚一个事实很重要你无法让模型 API 从 2 秒变成 200 毫秒你能做的是把并发压力尽量从模型 API 上挪开比如减少无效调用、合并相似请求、使用缓存。5.2 线程池、超时与有状态/无状态设计我自己在 Spring Boot 项目里给 Agent 单独开了一个线程池没有直接用默认的 Tomcat 线程池。原因很简单Agent 任务都是 IO 密集型线程不能太少也不能忙等但也不适合无脑开上千线程因为每个线程背后可能同时挂着一个模型 API 长连接。推荐一个起步配置实际效果稳ThreadPoolExecutor agentPool new ThreadPoolExecutor( 20, // 核心线程数 80, // 最大线程数 60, TimeUnit.SECONDS, new SynchronousQueue(), // 不积压任务满了就触发拒绝策略 new ThreadPoolExecutor.CallerRunsPolicy() );并发的另一个关键设计是无状态 Agent 实例。很多 Agent 框架鼓励把会话记忆挂在 Agent 对象里但这样一旦实例需要共享复用就会出现状态错乱。我建议的做法是Agent 实例本身不保存会话状态会话状态放到外部的 Redis 里以 sessionId 为 key 存取。这样同一时间的几百个会话可以共享为数不多的几个 Agent 实例并发能力一下子就被释放出来了。5.3 缓存策略与限流降级应对并发最简单有效的手段只有四个字减少重复。我的实际经验是对三种数据做缓存效果最好知识检索结果用户问“设备开不了机”这种高频问题同样的检索向量和结果可以缓存 5 到 10 分钟没必要每次重新查向量库。工具查询结果订单状态、物流轨迹这类数据虽然实时性要求高但 30 秒到 1 分钟的缓存完全可接受。我用 Caffeine 做了个短时缓存命中率很高。模型回答某些通用 FAQ 的完整答案可以缓存更久甚至直接返回模板。限流方面我建议按用户维度做配额而不是全局限流。因为 Agent 服务面向多租户时某一个大客户可能独占所有模型 API 配额影响其他客户。用 Redis 存每个用户的分钟级调用次数达到阈值就给 Agent 返回“今天太忙了稍后再试”的兜底回复。5.4 一个并发压测的参考结果我拿一个 2C4G 的测试机做过一次粗压测配置是 20 到 80 线程池模型用 qwen-plus工具和知识库都正常挂载单轮问答耗时约 2.8 秒。压测结果是20 并发时QPS 大概 7 左右成功率 99%升到 50 并发时QPS 约 11但 P99 开始出现 8 秒以上的超时。这说明瓶颈已经出现在模型 API 和外部依赖上提高线程数已经没有明显收益。根据这个结果我实践中的建议是不要盲目追求高并发而是把目标定在“在用户可接受的 5 秒内完成回答”。如果单轮要 3 秒留出 2 秒的容错一旦 P99 超过 6 秒就要考虑异步化处理而不是硬扛。6. 我踩过的一些坑与排查思路6.1 工具注册了但模型就是不调用这是使用 AgentScope Java 工具层最常见的坑之一。工具明明注册成功了模型却反复说“我没有相关工具可以回答”。排查方向按以下顺序先确认工具列表是否成功转成了 JSON Schema 并出现在请求里。打印一次完整的请求日志看模型实际看到的东西。检查工具描述是否包含足够的触发信号。比如你的工具叫“查询物流”但描述里没提“快递、运单号、发货、揽收”这些词模型就很难联想到用它。检查参数是否过度复杂。如果一个工具需要五个必填参数模型凑不齐参数时宁可不调用也不会去编造。我加过一条经验法则每个工具的必填参数尽量不要超过 3 个。超过 3 个时可以考虑将多个参数包装成一个 JSON 字符串由工具内部解析降低模型的调用门槛。6.2 知识检索命中很多但回答仍然不对这个问题我花了不少时间排查。发现命中文档不等于命中答案因为相似度检索看的是“像不像”不是“对不对”。比如用户问“打印机连不上 WiFi 怎么办”检索出的文档可能是“如何配置打印机的 WiFi 密码”也可能是“如何连接蓝牙打印机”两者在向量空间里都很接近但前者才是真正需要的。解决方法是两层。第一层是检索阶段增加领域过滤比如根据用户问题先判断业务线再限定业务线范围检索第二层是生成阶段增加一个校验步骤让模型判断“当前资料是否足以回答”不足则明确回复“知识库里暂时没有相关内容”而不是强行瞎编。6.3 上下文越到后面越乱token 成本失控多轮对话做久了以后我发现 prompt 里堆满了历史消息、知识片段、工具返回的 JSON。有一次一个会话进行到第 10 轮单次请求的 token 数已经接近模型上下文一半回答质量反而明显下降。这是因为模型对超长上下文的处理能力是有限的越靠后的内容越容易“淹没”前面的关键信息。我的做法是给 Agent 的上下文做分级管理系统提示词始终保留占很小比例。核心事实保留本会话已确认的关键信息比如订单号、客户诉求、上一步工具结果。历史对话只保留最近两轮完整对话更早的压缩成摘要。实现摘要可以用一个小模型做也可以用规则截断。我优先级推荐规则截断起步因为小模型额外调用会引入延迟和成本规则截断立竿见影。6.4 版本升级带来的兼容性波动AgentScope 从 0.9 到 2.x 走得不慢Java 版的 API 有过几次调整。比如早期工具注册方式和现在 2.x 的注解方式就不同知识库组件的包名也换过。如果你在升级版本后发现工具不被识别、知识库不生效请优先去查官方迁移文档里的 Breaking Changes。一个规避升级痛苦的小偏方把工具层和知识层封装在你的业务模块里不直接依赖 AgentScope 内部的类型。这样即使框架升级你只需要修改集成层的适配代码业务方法本身几乎不用动。我在几个项目里都用了这招实测能省掉大量踩坑时间。常见问题可能原因排查手段模型不调用工具工具描述不清晰、参数过多打印请求日志检查 JSON Schema知识检索结果不可用向量模型不一致、切块不当核对入库与查询的 Embedding 模型多轮对话越走越偏上下文过长、历史信息挤压压缩历史对话只保留核心事实并发一高就超时线程池配置不当或外部接口过慢单独配 Agent 线程池加缓存降级最后再分享一点实际体会把知识与工具层接入 AgentScope Java本质上是在给 Agent 设计“边界”。工具定义了这个 Agent 能做什么知识库定义了这个 Agent 知道什么。这两件事做得越清楚Agent 的表现就越稳定而不是偶尔灵光一现、经常翻车。如果你也是刚开始做 Agent我建议先别急着接十几个工具、灌一堆文档可以像我一样先拿 5 个工具加一个 30 篇文档的小知识库把完整链路跑通再逐步扩展。等你看到模型准确调用工具、又从知识库深处找到一段关键资料、最后组织出近乎完美的回答时你会觉得前面这些打磨都是值得的。