1. 为什么要在 RuoYi-Vue-Plus 里塞进一个 AI 编排引擎RuoYi-Vue-Plus 这套脚手架在国内中小团队里的普及率相当高权限模型清晰、代码生成器好用、多租户和缓存层都给你铺好了很多团队拿它当后台基座业务代码往上堆就行。但这两年有个明显的变化后台系统不再只是增删改查越来越多的需求开始往智能体方向靠——比如让系统自动根据工单内容分派处理人、让运营在后台配置一个能查数据能调接口的对话助手、让审批流里插入一个能读文档做摘要的节点。这些需求本质上都需要一个Agent 编排层而 RuoYi-Vue-Plus 本身并不提供。AgentScope 是阿里开源的一套多智能体编排框架Python 版本用得比较多但它同时提供了 Java 实现AgentScope Java / Harness 相关模块核心能力包括 Agent 定义、消息总线、工具调用Tool Calling、ReAct 推理循环、多 Agent 协作等。问题在于AgentScope 的 Java 侧设计是框架优先的它假设你自己管理生命周期、自己搭 Web 层而 RuoYi-Vue-Plus 是应用优先的Spring 容器托管一切、Sa-Token 管权限、MyBatis-Plus 管数据。把这两者拼在一起不是加个依赖就完事中间有一堆工程问题要处理。这篇内容面向的是已经用过 RuoYi-Vue-Plus、想在里面落地 AI 能力的后端同学。我会把整个集成过程拆开讲从依赖引入的坑、Agent 生命周期怎么和 Spring 对齐、工具调用怎么复用现有的 Service 层、流式输出怎么和前端 SSE 对接一直到多租户场景下 Agent 上下文怎么隔离。全程是纯 Java 路线不依赖 Python 服务也不搞那种起一个 Python 微服务再 HTTP 转发的绕路方案——那种方案在中小团队里维护成本太高多一个运行时就是多一份运维负担。需要先说明一点AgentScope 的 Java 生态还在演进不同小版本的 API 会有差异我下面提到的类名和调用方式基于我实际跑通的那一版你在自己项目里落地时以官方仓库的当前文档为准思路是通用的。另外本文所有示例中的业务名称、模块名都做了脱敏处理你替换成自己项目里的实际命名即可。2. 依赖引入与版本对齐第一个容易翻车的地方2.1 AgentScope Java 的依赖坐标与传递依赖冲突AgentScope 的 Java 构件在 Maven 中央仓库里能直接拉到但它的传递依赖里带了几个和 RuoYi-Vue-Plus 现有栈容易打架的东西。最典型的是 JSON 处理库和 HTTP 客户端AgentScope 内部可能依赖某个版本的 Jackson 或者 OkHttp而 RuoYi-Vue-Plus 默认用的是 Hutool 的 HTTP 工具加 Jackson版本号一旦错开启动时就会出现NoSuchMethodError或者ClassNotFoundException而且报错位置往往在很深的调用栈里排查起来费劲。我的做法是在父 POM 的dependencyManagement里显式锁定 AgentScope 相关构件的版本然后在业务模块里引入时排除掉它自带的 JSON 和 HTTP 依赖统一走项目已有的。具体操作如下dependency groupIdio.agentscope/groupId artifactIdagentscope-java-core/artifactId version${agentscope.version}/version exclusions exclusion groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /exclusion exclusion groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId /exclusion /exclusions /dependency排除之后要确认项目里已经有等价的实现。RuoYi-Vue-Plus 默认带 JacksonHTTP 客户端这块如果你用的是 Hutool 的HttpUtil那 AgentScope 内部如果强依赖 OkHttp 的某些 API就得单独保留 OkHttp 但锁定版本不能一刀切全排掉。这里有个判断方法先排除启动看报错如果报的是NoClassDefFoundError: okhttp3/OkHttpClient说明它确实在用那就把 OkHttp 加回来但锁版本如果没报说明走的是别的路径可以彻底去掉。提示版本对齐这件事建议在集成前先跑一次mvn dependency:tree把 AgentScope 引入前后的依赖树 diff 一下冲突一目了然比启动报错后再回头找要省事得多。2.2 Spring Boot 版本与 JDK 版本的隐性约束AgentScope Java 对 JDK 版本有要求我实测下来 17 是稳妥的11 上部分模块会因为用了较新的语言特性而编译不过。RuoYi-Vue-Plus 较新的版本本身就是 JDK 17 Spring Boot 3.x这一块基本吻合。但如果你手上的项目还是 Spring Boot 2.7 JDK 8 的老版本那集成前先评估升级成本硬上的话会遇到 Jakarta EE 命名空间javax.*到jakarta.*的问题AgentScope 内部如果用了jakarta包在 JDK 8 环境下直接编译失败。另一个隐性约束是 Spring 的TaskExecutor。AgentScope 的 Agent 执行默认可能是同步阻塞的但实际业务里你肯定不希望一个对话请求把 Tomcat 线程占满几十秒。所以要么用 AgentScope 自带的异步执行能力要么把它包在 Spring 的Async或者自定义线程池里。这里我倾向于后者因为线程池参数可以统一在 RuoYi-Vue-Plus 的配置里管理和现有的异步任务共用一套监控。3. Agent 生命周期与 Spring 容器的对齐策略3.1 把 Agent 定义成 Bean 还是工厂产出最直觉的做法是给每个 Agent 加Component让 Spring 直接托管。但实际做下来会发现两个问题一是 Agent 往往需要携带会话状态比如对话历史、当前工具调用上下文做成单例 Bean 会导致多个用户共享同一份状态这是灾难性的二是 Agent 的构造参数比如绑定哪些工具、用哪个模型可能需要根据租户或业务线动态变化写死在 Bean 定义里不够灵活。我的方案是Agent 的模板用 Bean 管理Agent 的实例用工厂按会话创建。具体来说定义一个AgentTemplate配置类把模型客户端、工具注册表、系统提示词这些无状态的部分做成单例然后写一个AgentFactory在每次会话开始时根据模板 会话 ID 创建一个独立的 Agent 实例实例内部持有该会话的Memory对话记忆。这样既复用了 Spring 的依赖注入又保证了状态隔离。Component public class AgentFactory { private final ModelClient modelClient; private final ToolRegistry toolRegistry; public AgentFactory(ModelClient modelClient, ToolRegistry toolRegistry) { this.modelClient modelClient; this.toolRegistry toolRegistry; } public Agent createSessionAgent(String sessionId, String tenantId) { Memory memory new InMemoryMemory(); return Agent.builder() .name(assistant- sessionId) .model(modelClient) .memory(memory) .tools(toolRegistry.resolveForTenant(tenantId)) .sysPrompt(buildSystemPrompt(tenantId)) .build(); } }这里toolRegistry.resolveForTenant是关键它决定了不同租户能看到哪些工具。比如租户 A 只买了基础版那涉及数据导出的工具就不该注册进去避免越权调用。3.2 会话状态存哪里内存、Redis 还是数据库InMemoryMemory只适合单机 demo生产环境必须考虑持久化和多实例部署。RuoYi-Vue-Plus 自带 Redis最自然的做法是把对话记忆序列化后存 Rediskey 用agent:session:{tenantId}:{sessionId}设置合理的过期时间比如 30 分钟无活动就过期。但要注意AgentScope 的Memory对象不一定实现了Serializable直接往 Redis 塞可能报错。我的处理方式是自定义一个RedisMemory实现内部不存整个 Memory 对象而是存消息列表ListMsg每条消息转成 JSON 存进去。读取时反序列化重建 Memory。这样虽然多了一层转换但可控性强也方便你在后台直接查 Redis 看某个会话聊了什么排查问题很直观。public class RedisMemory implements Memory { private final StringRedisTemplate redisTemplate; private final String key; private final ObjectMapper objectMapper; Override public void add(Msg msg) { String json objectMapper.writeValueAsString(msg); redisTemplate.opsForList().rightPush(key, json); redisTemplate.expire(key, Duration.ofMinutes(30)); } Override public ListMsg getMessages() { ListString raw redisTemplate.opsForList().range(key, 0, -1); return raw.stream() .map(s - objectMapper.readValue(s, Msg.class)) .collect(Collectors.toList()); } }注意消息列表无限增长会撑爆 Redis也浪费 token。建议在add里加一个截断逻辑比如只保留最近 20 轮对话更早的做摘要压缩或者直接丢弃。这个阈值要根据你用的模型上下文窗口来定别拍脑袋。4. 工具调用让 Agent 复用 RuoYi-Vue-Plus 的 Service 层4.1 工具注册的两种粒度与选择依据AgentScope 的工具调用机制本质上是把 Java 方法暴露给模型模型决定什么时候调、传什么参数。工具注册的粒度有两种粗粒度一个工具对应一个完整的业务动作比如查询用户列表和细粒度一个工具对应一个原子操作比如按 ID 查用户、按条件搜用户。粗粒度工具数量少、模型选择压力小但灵活性差细粒度灵活但工具一多模型容易选错。在 RuoYi-Vue-Plus 这种业务系统里我建议走中等粒度按业务域划分工具每个工具内部封装该域的几个常用查询。比如用户域就注册一个queryUser工具参数里带userId或username或deptId内部根据传参走不同的 Service 方法。这样工具总数可控一般不超过 15 个模型选择准确率也高。工具的实现直接注入现有的 Service 即可不需要重写数据访问逻辑Component public class UserQueryTool { private final ISysUserService userService; public UserQueryTool(ISysUserService userService) { this.userService userService; } Tool(name queryUser, description 根据用户ID、用户名或部门ID查询用户信息) public String queryUser( ToolParam(name userId, required false) Long userId, ToolParam(name username, required false) String username, ToolParam(name deptId, required false) Long deptId) { // 复用现有 Service注意这里要处理权限 // ... } }4.2 工具调用中的权限校验不能省这是最容易出安全问题的地方。模型生成的工具调用参数是不可信的用户完全可以通过精心构造的对话让 Agent 去查它本不该查的数据。比如一个只有本部门查看权限的用户诱导 Agent 传一个别的部门 ID 进去。所以工具方法内部必须做权限校验不能因为是 Agent 调的就放行。我的做法是在工具方法里显式调用 RuoYi-Vue-Plus 的权限工具类或者干脆把当前登录用户的信息通过ThreadLocal传进来RuoYi-Vue-Plus 的SecurityUtils就是干这个的在工具内部用SecurityUtils.getUserId()拿到当前用户再结合数据权限注解或手动校验。如果 Agent 是在异步线程里执行的ThreadLocal会丢这时候需要在创建 Agent 实例时把用户上下文快照传进去工具执行时从 Agent 上下文里取。Tool(name queryUser, description ...) public String queryUser(ToolParam(name deptId) Long deptId) { Long currentUserId AgentContextHolder.getCurrentUserId(); if (!permissionService.hasDeptPermission(currentUserId, deptId)) { return 无权查询该部门数据; } // 正常查询 }提示返回给模型的错误信息也要注意措辞不要泄露哪个部门存在但你没权限这种信息统一返回无权访问即可避免被用来探测数据边界。5. 流式输出与前端 SSE 的对接细节5.1 为什么必须做流式Agent 的推理过程可能涉及多轮工具调用一次完整响应动辄十几秒甚至更久。如果等全部生成完再返回前端就是一个转圈圈用户体验极差而且网关层可能因为超时直接断开。流式输出让用户能实时看到 Agent 的思考过程和部分结果体感上快很多。RuoYi-Vue-Plus 的前端是 Vue对接 SSE 很成熟后端用 Spring 的SseEmitter或者 WebFlux 的Flux都行。考虑到 RuoYi-Vue-Plus 默认是 Servlet 栈用SseEmitter改动最小。5.2 SseEmitter 的超时与线程管理SseEmitter默认超时时间比较短Agent 场景下要显式设置长一点比如 5 分钟。但光设超时不够还要注意SseEmitter的发送是在独立线程里做的如果 Agent 的执行线程和 SSE 发送线程是同一个一旦 Agent 阻塞SSE 心跳就发不出去连接会被中间层掐断。所以正确做法是Agent 在业务线程池里跑每产生一个 token 就通过SseEmitter.send()推给前端同时起一个定时任务定期发心跳注释行。GetMapping(/chat/stream) public SseEmitter chatStream(RequestParam String sessionId, RequestParam String message) { SseEmitter emitter new SseEmitter(300_000L); executor.execute(() - { try { Agent agent agentFactory.createSessionAgent(sessionId, tenantId); agent.stream(message).forEach(chunk - { emitter.send(SseEmitter.event().data(chunk)); }); emitter.complete(); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; }前端那边用EventSource接收注意EventSource只支持 GET如果你的消息体比较大得把消息放 query 参数或者先 POST 存到服务端再 GET 拉流。RuoYi-Vue-Plus 的前端请求封装默认走 axiosSSE 需要单独处理不能用 axios 拦截器那套。5.3 工具调用过程中的中间态怎么展示流式输出不只是把最终答案吐出来工具调用的中间态正在查询用户数据...也应该推给前端否则用户看到的就是长时间空白然后突然一大段文字。AgentScope 的流式接口一般会区分text和tool_call类型的事件你在后端根据事件类型组装不同的 SSE event name前端按 event name 分别渲染。比如event: thinking显示在思考区event: answer显示在正文区。6. 多租户场景下的上下文隔离与资源控制6.1 租户维度的模型配置与配额RuoYi-Vue-Plus 的多租户是核心特性Agent 集成必须尊重这个模型。不同租户可能用不同的模型供应商、不同的 API Key、不同的调用配额。我的做法是在租户配置表里加几个字段model_provider、model_name、api_key_encrypted、daily_token_limit。AgentFactory创建实例时根据tenantId查配置动态构造ModelClient。配额控制这块每次工具调用和模型调用前都要检查当日已用量超了就拒绝并返回友好提示。用量统计可以异步写不要阻塞主流程。这里有个坑流式输出时 token 数是逐步产生的你得在流结束时才拿到准确用量所以扣减配额要放在流结束的回调里而不是开始时。6.2 工具可见性的租户隔离前面提到toolRegistry.resolveForTenant这里展开说。工具注册表应该支持按租户过滤实现方式可以是一个MapString, ListToolkey 是租户 IDvalue 是该租户可用的工具列表。默认租户有一套基础工具特殊租户可以额外开通。这样做的另一个好处是当某个工具出问题时可以快速对特定租户下线该工具而不影响其他人。注意租户隔离不只是数据隔离还包括提示词隔离。不同租户的系统提示词可能不同比如行业术语、回复风格这些也要按租户配置不能写死在代码里。7. 实测中踩过的几个坑与排查思路7.1 Agent 卡死不返回先看线程池再看模型超时集成完成后我遇到过一次 Agent 请求卡死前端一直转圈后端日志没有任何异常。排查顺序是这样的先看线程池发现业务线程池的队列满了任务在排队再往上查发现是模型调用没有设超时某个请求卡在了网络层。AgentScope 的ModelClient如果不显式设超时默认可能是无限等待。解决办法是给模型客户端设一个合理的超时比如 60 秒同时线程池的拒绝策略改成CallerRunsPolicy或者直接返回错误别让请求无限堆积。7.2 工具调用参数解析失败模型输出的 JSON 不合法模型生成工具调用参数时偶尔会输出不合法的 JSON比如多了个逗号、少了引号导致反序列化失败。AgentScope 内部一般有重试机制但重试也可能连续失败。我的处理是在工具注册时给每个参数加严格的类型约束和描述描述里明确告诉模型参数格式比如用户ID纯数字能显著降低解析失败率。另外在工具执行外层包一层 try-catch解析失败时返回参数格式错误请重新生成让模型自己纠正。7.3 多轮对话后响应变慢记忆膨胀对话轮次多了之后每次请求都要把全部历史消息发给模型token 消耗线性增长响应越来越慢。解决办法是滑动窗口 摘要保留最近 N 轮完整对话更早的对话用一个小模型做摘要摘要作为一条 system 消息放在最前面。这样既保留了长期上下文又控制了 token 量。摘要的触发时机可以设在消息数超过阈值时异步执行不阻塞当前对话。7.4 前端 SSE 断连重试导致重复请求EventSource在连接断开后会自动重连如果后端没有做幂等处理重连会导致同一条消息被处理两次Agent 重复回复。解决办法是在前端生成一个requestId重连时带上后端用 Redis 记录已处理的requestId重复的直接返回缓存结果或者忽略。这个requestId也可以用来做流式输出的断点续传体验更好。8. 关于这套集成方案的一些个人体会把 AgentScope 塞进 RuoYi-Vue-Plus技术上没有不可逾越的障碍真正的成本在于边界划分哪些逻辑放 Agent 层、哪些放 Service 层、哪些放 Controller 层。我的经验是Agent 层只负责理解意图和编排调用所有涉及数据读写和权限判断的逻辑一律下沉到 Service 层Agent 通过工具调用去触发。这样职责清晰出问题时也容易定位——是模型理解错了还是 Service 执行错了一看日志就知道。另外别指望一次集成就能覆盖所有场景。我建议先挑一个最简单的场景跑通全链路比如查一下当前用户的部门信息把依赖、生命周期、流式、权限这几条线都验证一遍再逐步加工具、加租户、加配额。上来就搞复杂多 Agent 协作很容易在调试阶段迷失方向。工具的数量也要克制每加一个工具都要问自己模型真的需要它吗能不能合并到现有工具里工具越多模型选错的概率越大这是实测下来的规律。
