这半年我们团队一直在折腾一件事把 AI Agent 的管理能力塞进现有的 Java 后台里而不是另起炉灶搞一套 Python 管理端。当时手上刚好有一个基于 RuoYi-Vue-Plus 的权限中台项目业务方又提出要用多智能体编排来做一些自动化流程于是就促成了这次集成实践——把 AgentScope Harness 接进 RuoYi-Vue-Plus做一个“管理端纯 Java、执行端交给 Harness”的 AI 平台底座。整个过程踩了不少坑也总结出了一套相对稳的接法这篇文章就是这次实践的完整复盘。如果你现在的处境和我当时类似——Java 技术栈是主力但又想快速获得 Agent 编排和调度的能力而不是从零写一套 Agent 运行时那这篇文章应该能帮你少走不少弯路。我先把核心思路、关键代码、配置细节和坑位都拆开讲清楚你可以直接照着落地。1. 项目整体设计与思路拆解1.1 为什么要选 RuoYi-Vue-Plus 当底座RuoYi-Vue-Plus 这个脚手架我的评价是“拿来就能跑改起来也不疼”。它自带的基础设施相当完整Sa-Token 权限体系、菜单路由、代码生成器、定时任务、操作日志、在线用户管理这些模块在一个 AI 平台的管理端里几乎全部用得上。尤其是权限体系Agent 实例这种资源天然需要按角色划分可见范围直接用若依的SaCheckPermission注解就能解决不用自己再造轮子。另外一个重要原因是团队熟练度。我们当时项目组成员对 Spring Boot 3、MyBatis-Plus 都很熟但 Python 技术栈的人手不够。如果为了 Agent 能力硬上一套 FastAPI 管理端后续的迭代维护成本会摊到整个团队头上这显然不划算。所以“Java 管理端 独立 Agent 运行时”这种架构是我们在权衡人力、工期和业务需求之后觉得最务实的方案。1.2 AgentScope Harness 在整个架构里的角色先解释一下 Harness 这个词。直译是“马具、缰绳”但在 Agent 工程化领域它指的是给智能体应用套上的一整套“驾驶装置”——负责管理 Agent 的生命周期、运行时依赖、通信协议、工具装配和日志采集。你可以把它理解成 Agent 的“运行容器 调度器”跟 Tomcat 之于 Servlet 的关系有点像只不过 Tomcat 装的是 Web 应用Harness 装的是 Agent 应用。在我们的架构里Harness 以独立服务的形式存在对外暴露 HTTP API。Java 侧的业务系统不需要关心 Agent 内部是怎么编排的只需要通过 API 下发“创建”“启动”“停止”“查状态”“拉日志”这些操作。这种设计的好处是边界非常清晰Java 管业务、管资源权限、管流程编排Harness 管 Agent 进程、管道通信、工具注册和运行日志。两边各司其职互不侵入。1.3 集成思路为什么不直接用 Python SDK其实 AgentScope 本身提供了完整的 Python SDK如果团队里都是 Python 工程师直接在后台服务里调用 SDK 是最顺畅的方式。但我们面临一个很现实的问题现有的 RuoYi-Vue-Plus 业务系统里有大量的用户体系、工单流、审批流这些逻辑都是 Java 写的。如果让 Java 工程去依赖 Python SDK跨语言混编会导致部署流程变得极其复杂——你得保证每个节点上都有 Python 环境和依赖包还得处理 Python 进程崩溃后对 Java 进程的影响。所以最终的方案是把 Harness 独立部署HTTP 协议作为唯一通信通道。这样 Java 侧只需要一个 HTTP 客户端封装类不引入任何 Python 依赖。运维层面也简单Java 应用和 Harness 服务各自一套生命周期管理互不干扰。这也是我认为最“纯 Java AI 平台”的做法——AI 引擎本身跑在独立的运行时里但平台化管理、API 暴露、权限管控全都在 Java 侧完成。2. Harness HTTP API 对接的核心细节2.1 我们需要关注哪些 API 语义接 Harness 之前我先把它的接口语义梳理了一遍。对我们这种集成场景来说最核心的其实是五个操作注册 Agent 配置、启动实例、停止实例、查询状态、获取日志。这里要注意一个概念区分Agent 配置和Agent 实例不是一回事。配置是静态的描述这个 Agent“是什么”包括提示词模板、工具列表、模型参数实例是动态的代表一次实际运行有自己的会话上下文和运行状态。在我们的设计里RuoYi 的数据库里保存 Agent 配置信息Harness 侧只负责运行时实例。所以对接时POST 请求创建的不是“一次运行”而是“一份可运行的 Agent 模板”。启动操作才是真正产生实例的时刻。2.2 数据模型设计既然要存 Agent 配置那 RuoYi 侧就得有一张对应的表。我设计的时候参考了 Harness 的输入要求和若依本身的字段规范最终落地的表结构大致是这样CREATE TABLE agent_config ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键, agent_name varchar(64) NOT NULL COMMENT Agent 名称, agent_code varchar(64) NOT NULL COMMENT Agent 编码全局唯一, scene_type varchar(32) DEFAULT NULL COMMENT 场景类型TASK/CHAT/REASONING, prompt_config json DEFAULT NULL COMMENT 提示词与模型参数配置, tool_list json DEFAULT NULL COMMENT 工具清单, worker_num int DEFAULT 1 COMMENT 最大并发运行数, status char(1) DEFAULT 0 COMMENT 状态0草稿 1启用 2停用, create_by varchar(64) DEFAULT NULL, create_time datetime DEFAULT NULL, update_by varchar(64) DEFAULT NULL, update_time datetime DEFAULT NULL, PRIMARY KEY (id), UNIQUE KEY uk_agent_code (agent_code) ) ENGINEInnoDB COMMENTAgent 配置表;两个 JSON 字段是我刻意选的。prompt_config里存的是模型名、温度、最大 token 数、System Prompt 这些内容tool_list放 Agent 能调用的工具列表。用 JSON 而不是 text 的好处是后续如果要做配置项的局部更新、校验MyBatis-Plus 可以直接映射到实体类的 String 字段也可以在数据库层面用 JSON 函数做条件查询比 text 灵活得多。2.3 实体类与 Mapper 层实体类的写法遵循 MyBatis-Plus 的常规套路没有什么花活。唯一想提醒的是在 JSON 字段上一定要加自动映射的注解不然查询出来是字符串插入的时候又会因为类型不匹配导致 SQL 报错。Data TableName(agent_config) public class AgentConfigEntity { TableId(type IdType.AUTO) private Long id; private String agentName; private String agentCode; private String sceneType; private String promptConfig; private String toolList; private Integer workerNum; private String status; private String createBy; private LocalDateTime createTime; private String updateBy; private LocalDateTime updateTime; }Mapper 就是裸继承BaseMapperAgentConfigEntity不需要自定义 SQL。CRUD 全部靠 MyBatis-Plus 的内置方法只有在后续做分页查询的时候加了一个PageAgentConfigEntity条件的封装。这里其实也体现出选 RuoYi 系列的一个隐形好处MyBatis-Plus 的配置、分页插件、字段自动填充都已经是现成的不需要自己一个个去调。3. 实操过程从配置到 API 对接3.1 第一步把 HTTP 客户端封装成可复用的 ManagerRuoYi-Vue-Plus 里已经集成了 Hutool所以我没有额外引入 RestTemplate 或者 OkHttp直接用 Hutool 的HttpUtil完成最基础的请求。但直接到处写HttpUtil.post(...)肯定不行后续要统一加签名、加超时处理会改到吐血。所以我做了一层HarnessManager的封装所有与 Harness 的通信都走这个类。Component public class HarnessManager { private static final Logger log LoggerFactory.getLogger(HarnessManager.class); Value(${harness.base-url}) private String baseUrl; Value(${harness.api-key}) private String apiKey; Value(${harness.connect-timeout:5000}) private int connectTimeout; Value(${harness.read-timeout:60000}) private int readTimeout; public String createAgent(AgentConfigEntity config) { JSONObject body new JSONObject(); body.set(agentCode, config.getAgentCode()); body.set(agentName, config.getAgentName()); body.set(sceneType, config.getSceneType()); body.set(promptConfig, JSONUtil.parseObj(config.getPromptConfig())); body.set(toolList, JSONUtil.parseArray(config.getToolList())); return requestJson(/api/v1/agents, POST, body); } public String startAgent(String agentCode) { JSONObject body new JSONObject(); body.set(agentCode, agentCode); return requestJson(/api/v1/agents/start, POST, body); } public String stopAgent(String agentCode) { JSONObject body new JSONObject(); body.set(agentCode, agentCode); return requestJson(/api/v1/agents/stop, POST, body); } public String getAgentStatus(String agentCode) { return requestJson(/api/v1/agents/status/ agentCode, GET, null); } public String getAgentLogs(String agentCode) { return requestJson(/api/v1/agents/ agentCode /logs, GET, null); } private String requestJson(String path, String method, JSONObject body) { HttpRequest request HttpUtil.createRequest(Method.valueOf(method), baseUrl path); request.header(X-API-Key, apiKey) .header(Content-Type, application/json) .timeout(new Timeout(connectTimeout)); if (body ! null) { request.body(body.toString()); } try (HttpResponse response request.execute()) { int status response.getStatus(); if (status 200 || status 300) { log.error(Harness request failed, path: {}, status: {}, body: {}, path, status, response.body()); throw new HarnessException(Harness API error, status: status); } return response.body(); } catch (IOException e) { log.error(Harness request read timeout or connection error, path: {}, path, e); throw new HarnessException(Harness connection error: e.getMessage()); } } }3.2 第二步超时参数要单独配置不能走默认值这里有一个很值得展开的坑。我们第一次联调时read-timeout用的是 10 秒结果发现启动耗时较长的 Agent 任务经常在 Java 侧抛超时异常。查了日志才发现Harness 侧 Agent 冷启动要加载模型权重和工具包跑满 30 秒甚至更久是常有的事。HTTP 客户端默认的读超时根本不够用。所以我的建议是创建、停止这类轻操作可以给较短的读超时比如 10~15 秒但启动和日志查询这类可能耗时较长的操作必须给到 60 秒甚至更久。如果公司内部有链路追踪系统也可以在请求头里带上 traceId方便把 Java 侧的异常和 Harness 侧的执行日志串起来排查。另外Hutool 的Timeout对象需要同时设置连接超时和读写超时我当时只设置了连接超时导致读超时走的是默认值这个问题花了我一个下午才定位到。代码里现在显式地建了connectTimeout和readTimeout两个配置项并且在启动时打印出来减少后续排查成本。3.3 第三步把 Service 层的状态机做强光有一个 Manager 还不够因为 Agent 有状态流转草稿 - 运行中 - 已停止/失败。如果 Service 层不做状态判断一个已经启动的 Agent 会重复被调用 start 接口Harness 侧要么报错要么产生一堆无效的实例记录。我们的做法是在AgentConfigServiceImpl里维护一个简单的状态机public boolean changeStatus(Long id, String expectedStatus, String newStatus) { LambdaUpdateWrapperAgentConfigEntity wrapper new LambdaUpdateWrapper(); wrapper.eq(AgentConfigEntity::getId, id) .eq(AgentConfigEntity::getStatus, expectedStatus); AgentConfigEntity update new AgentConfigEntity(); update.setStatus(newStatus); update.setUpdateTime(LocalDateTime.now()); return this.update(update, wrapper); }这里用 MyBatis-Plus 的eq(status, expectedStatus)作为乐观锁条件并发操作时只有状态匹配的那条请求能成功更新从数据库层面杜绝了重复启动问题。虽然 RuoYi 自带了乐观锁插件配置但很多时候大家只把它用在版本号字段上像这种“状态即版本”的写法反而更直观也更好理解。3.4 第四步日志对接与检索Agent 运行日志是一个很容易被低估的需求。一开始我们只是把 Harness 返回的日志原样存进了一个日志表结果运行几次之后发现一个 Task 类 Agent 跑一轮下来就是几百上千行日志全部堆在 MySQL 单表里查询翻页慢得没法看。后来我们做了一步很关键的调整日志表只保留最近一天的明细历史日志由 Harness 侧负责归档。Java 侧通过定时任务每 5 分钟同步一次运行中 Agent 的状态和日志并清理超过一天的明细记录。这样数据库保持轻量用户在后台上看到的又是实时数据。如果业务量再大可以考虑把日志投递到独立的日志中心但当前阶段这种“短保留 同步归档”的模式已经够用。4. 权限、菜单与前端接入4.1 给 Agent 资源加上权限管理RuoYi-Vue-Plus 的权限体系是现成的不需要改造。我在菜单配置里加了“Agent 管理”目录下面挂了“Agent 实例”“运行日志”“工具注册”三个菜单分别配置了agent:config:list、agent:config:start、agent:log:list这些权限标识。然后给不同角色分配对应的操作权限。这里有一点需要强调不要只在菜单上隐藏接口层面也要用SaCheckPermission做二次校验。因为菜单权限只控制前端显示如果用户手动拼 URL后端没有校验的话照样能调接口。我们用注解锁住了四个核心操作SaCheckPermission(agent:config:start) PostMapping(/start/{id}) public RVoid start(PathVariable Long id) { ... } SaCheckPermission(agent:config:stop) PostMapping(/stop/{id}) public RVoid stop(PathVariable Long id) { ... }4.2 前端页面的快速搭建前端是用 RuoYi-Vue-Plus 自带的代码生成器直接生成的。我把agent_config表的实体类和 Mapper 丢给生成器自动产出了列表页、表单页、API 调用基本上开箱即用。唯一手写的前端逻辑是“启动/停止”按钮的状态联调——要根据当前行的 status 字段动态显示按钮运行中的 Agent 只显示“停止”草稿状态的只显示“启动”。前端调接口的时候我启动按钮的处理方式是handleStart(row) { this.$modal.confirm(确认启动 Agent「 row.agentName 」吗).then(() { return request({ url: /ai/agent/start/ row.id, method: post }); }).then(() { this.$modal.msgSuccess(启动任务已下发); this.getList(); }); }这里有一个交互细节启动请求返回成功不代表 Agent 已经进入运行状态因为 Harness 的启动可能是异步的。所以前端文案用“启动任务已下发”而不是“启动成功”避免误导用户。页面再通过轮询或者下个刷新周期去拉状态展示真实的运行情况。4.3 跨域问题的处理方式因为 Harness 是独立服务Java 后端的请求本身是服务端到服务端不存在浏览器跨域问题。但 Harness 可能会有一些需要前端直连的能力比如流式的日志推送、SSE 消息通道这时候就会冒出来跨域。我们直接在后端网关层做了一次转发把 Harness 的 SSE 接口统一收敛成/ai/harness/sse/**路径由 Java 后端代理转发给前端而不是让前端跨域直连 Harness。这样处理有双重好处一是前端的所有请求都只指向 RuoYi 域名配置简单二是 Harness 的 API Key 只保存在后端不暴露给浏览器安全性提升一个档次。5. 常见问题与排查技巧实录5.1 启动任务下发后状态一直不更新这个是我们在联调中最先碰到的问题。 Harness 侧的 Agent 实例确实跑起来了但 RuoYi 数据库里的状态字段一直是“0”。查到最后发现是轮询同步的定时任务配置了Scheduled注解但任务的执行被 RuoYi 自带的线程池限制住了——默认的调度线程池很小而系统里已经有不少定时任务在跑同步任务可能排队排了非常久。解决办法是把状态同步任务的调度周期调大到 1 分钟一次同时给调度线程池单独开了一个配置spring: task: scheduling: pool: size: 10其实问题的本质不是周期太长而是调度线程池没有给足资源。如果项目里有多个定时任务这个配置建议直接用起来不然任务一多单个任务的执行延迟完全不可控。5.2 删除配置失败后面还有引用当我们做一个“删除 Agent 配置”的功能时报错显示“存在运行中的实例不能删除”。这个错误其实是 Harness 侧抛出来的。我自己实现的删除逻辑是先调用 Harness 的 stop 接口确认实例停了之后再删除数据库里的配置。但有一次 stop 接口返回了失败抛出的异常信息被吞掉了导致数据库的删除操作没有被触发。后来我在 HarnessManager 里给异常处理加了一个统一出口public String stopAgent(String agentCode) { try { return requestJson(/api/v1/agents/stop, POST, body); } catch (HarnessException e) { if (e.getMessage().contains(not running)) { log.warn(Agent {} is not running, skip stop, agentCode); return {}; } throw e; } }这个“重复停止不报错”的处理逻辑很关键。因为在分布式场景下一个 agent 可能已经被另一个请求停了再调 stop 接口就会返回“not running”错误。为了保持接口的幂等性这个场景不能直接报错而是当作成功处理。否则用户重复点击“停止”按钮页面就会一直弹错误提示体验很糟糕。5.3 Hutool 连接池耗尽导致的 Full GC 问题系统运行了两天后我们注意到一个很隐蔽的问题后端的 Full GC 频率突然变高。看了堆转储发现有大量的HttpConnection对象没有被释放。原因很简单——Hutool 的HttpUtil每次请求都会走默认连接池但我们用了流式处理某些响应体没有把HttpResponse的流主动关掉。后来我把所有与 Harness 的通信全部改成了 try-with-resources 模式并统一在requestJson方法内部完成HttpResponse的关闭业务侧完全感知不到连接管理这件事。如果你在用 RestTemplate 或者 OkHttp也得注意类似的问题连接池用完要放回响应体要读完再关不然迟早会拖垮应用。5.4 配置了 API Key 却还是 401这个问题是典型的“前后端配置不一致”导致的。Harness 部署的实例有两个一个测试环境一个生产环境。我们在 RuoYi 的application.yml里配的是生产环境的 API Key但本地开发时联调的是测试环境的 Harness 服务。由于两套环境的 Key 不一样请求一直被 401。排查方法是登录 Harness 管理端生成了一个新的 Key替换到 local 环境配置后问题立刻消失。这里建议在配置中心管理环境变量不要在代码仓库里写死环境差异尤其是多个环境共享一个代码分支的时候这种低级错误非常容易发生。5.5 常见问题速查表现象可能原因解决方式请求超时读超时设置过短区分 connectTimeout 和 readTimeout启动类操作给足 60 秒状态不更新定时任务线程池不足调大spring.task.scheduling.pool.size删除时报运行中未做停止操作的幂等处理捕获“not running”错误按成功处理401 鉴权失败环境不同导致 API Key 不一致检查配置中心/环境变量Full GC 频繁HTTP 连接未释放统一 try-with-resources 关闭响应流启动成功但无日志日志同步周期过长适当调短同步周期或配合 Harness 侧归档策略6. 优化方向与扩展想法集成完成之后我又重新过了一遍整个架构觉得有三个方向是可以继续深挖的。第一个是把配置中心用起来。现在 Harness 的 base-url 和 api-key 直接写死在application.yml里环境一多就麻烦。RuoYi-Vue-Plus 本身可以对接配置中心建议把它纳入进来统一管理多环境的不同 Harness 地址。第二个是做 Agent 资源的编排调度。现在创建、启动、停止还停留在单机串行操作如果 Agent 数量多了或者启动一个 Agent 需要同时拉起多个依赖的子 Agent纯手工管理就会很累。可以在这套基础上加一个简单的任务编排引擎把启动、停止、日志采集这些操作做成可编排的流程。第三个是监控指标的接入。Harness 侧运行时的 CPU、内存、Token 消耗、请求延迟这些指标目前我们还没有接全。如果能把指标数据同步到 RuoYi 侧的监控大屏管理员就可以直观看到每个 Agent 的运行情况这对生产环境的价值很大。我个人在实际操作中体会最深的一点是集成工作的核心不是把两套系统连起来而是把两套系统之间的边界画清楚。Java 侧负责管理、权限、业务编排Harness 侧负责运行、调度、资源隔离中间用清晰、幂等的 HTTP 接口通信。边界画清楚了后续加功能、加节点、加监控都只是在这个框架里做增量而不会牵一发动全身。最后再分享一个小技巧在 HarnessManager 刚写完的时候建议先写一个简单的开关接口把 Harness 的连通性测试放到后台的一个隐藏页面里。这样每次发布配置变动、环境切换之后运维同学点一下按钮就能确认链路是否正常会省去非常多的排查成本。