这半年我们团队被反复问到同一个问题能不能在现有的 Java 后台管理系统里直接跑 Agent 评估任务以前的做法是把 AI 能力单独部署成 Python 服务再给 Java 侧留一套 HTTP 接口结果运维上多了一堆要盯的进程和端口。这次我们换了一个思路——把 AgentScope Harness 作为子进程直接交给 RuoYi-Vue-Plus 来拉起、监控和回收让它成为后台里的一个任务模块。整个过程走下来才发现纯 Java AI 平台并不是让 Java 去跑模型而是让 Java 去管 Agent 的运行生命周期。这篇就完整记录这次集成实践任务状态机、进程生命周期、日志回传、权限绑定以及那些文档里不会写的坑给同样想在传统 Java 后台里接入多智能体能力的团队做个参考。1. 需求源头管理后台要的是任务工厂不是聊天框1.1 传统 Java 后台接入 AI 的第一反应往往是加一个对话页面大多数 Java 团队接到 AI 需求第一反应就是在 RuoYi-Vue-Plus 里加一个菜单前端塞一个聊天框后端对接 LLM API。对单轮问答这种场景这条路确实最快。但一旦需求变成让多个 Agent 协同完成一个目标跑一批测试用例看评估结果把每次执行记录留档审计单纯聊天框就完全不合适了。聊天框是人来发起、人来看结果而这类需求要的是系统自动发起、自动汇聚结果、可追溯可重跑——本质上是把 Agent 变成后台批处理任务。RuoYi-Vue-Plus 这类脚手架本身已经解决了权限、数据隔离、操作日志、定时任务这些通用能力。我们要做的不是另造一套 AI 调度平台而是把 Agent 任务嵌进现有的管理后台流程里。用户打开菜单能看到任务的创建时间、执行状态、日志、结果文件管理员能按部门或角色限制谁能启动任务审计员能在操作日志里看到谁在什么时间动了哪些任务。这些能力恰恰是 Java 后台的强项。1.2 为什么选中 AgentScope Harness而不是自己写一套 Agent 编排自己写 Agent 编排最大的问题是你以为你只需要调模型实际上还要处理多轮上下文、工具注册、结果解析、并发压测、评估指标归一化。Harness 这个词在 AgentScope 里更像是装载与运行底座它把 Agent 的启动、协作流程、结果收集、压测与评估封装成一套可重复执行的结构。直接使用 Harness我们可以把精力放在什么时候跑、跑完怎么归档上而不是重新发明怎么跑。我们的场景里还有一个硬指标同一套多智能体应用要在不同配置下反复执行用来做回归对比。Harness 天然支持配置化输入和结构化输出跑完一轮就是一份结果文件非常适合接任务系统。如果从零自己开发编排至少要多花两到三周去处理并发、超时、结果标准化而这些 Harness 已经替你兜底了。1.3 三种集成方案对比旁路服务、内嵌解释器、子进程真正动手前我们对比了三条路方案优点缺点结论Python 独立服务 Java HTTP 调用边界清晰Python 生态自由多一套进程要运维接口协议要自己设计部署成本高不差钱不差人可选我们不选JVM 内嵌 Python 解释器看起来纯 Java最彻底解释器与 Java 版本兼容风险高调试和内存管理是灾难直接否决Java 拉取 Python 子进程部署整体仍在一个应用体系里生命周期可控失败可回收Java 侧要处理进程监、日志、超时最终选择子进程方案看起来不够高级但生产环境里最稳。我们把 AgentScope 的依赖和虚拟环境固定在一个目录RuoYi-Vue-Plus 通过进程管理模块去启动和回收它。对团队来说仍然只需要部署一套主程序对运维来说不需要额外开着另一个 service对审计来说所有进程启动记录都能落在 Java 侧的任务表里。2. 动手前的三个关键设计路径、契约、生命周期2.1 依赖目录与 Python 虚拟环境不要把 Harness 塞进 JAR 包第一个容易踩的坑就是想着把 AgentScope 的 Python 代码打包进 Spring Boot 的 resources 里。千万不要这样做。JAR 包一旦被重新构建Python 依赖就得重新装路径还容易乱。我们采用独立目录方案/opt/agent-platform/ ├── harness/ │ ├── venv/ # Python 虚拟环境 │ ├── requirements.txt # 固定版本依赖 │ ├── task_templates/ # 各类 Harness 配置文件 │ └── runtime/ │ ├── {taskId}/ # 每个任务独立运行目录 │ │ ├── input.json │ │ ├── logs/ │ │ └── results/ │ └── .lock创建虚拟环境时一定用python3 -m venv venv然后venv/bin/pip install -r requirements.txt。Java 侧启动进程时可执行文件写死为venv/bin/python不要写python3避免踩到系统 Python 版本。这属于常见的生产环境加固手段不是花活。2.2 任务输入输出契约不要用控制台文本当 APIJava 和 Python 子进程之间最忌讳把 stdout 当通信协议。Harness 跑起来后往控制台打一堆进度文本解析既脆弱又不好扩展。我们的约定是Java 侧把任务参数写成 JSON 文件Harness 读取该文件执行执行结果也写在 JSON 文件里Java 侧通过退出码 结果文件是否存在 JSON 是否合法来判断成功。这样解析逻辑只跟文件打交道跟打印内容无关。一个最小化的input.json长这样{ task_id: task_20250921_001, agent_pipeline: multi_agent_writing, goal: 基于给定材料生成一份产品发布说明, max_rounds: 10, timeout_seconds: 600, output_dir: /opt/agent-platform/harness/runtime/task_20250921_001/results, extra_params: { temperature: 0.7 } }这个设计坚持下来以后收益非常大。后面无论前端怎么改Java 侧处理逻辑都不用动因为契约是文件不是接口。2.3 状态机后台任务必须异步HTTP 请求不能等 Agent 跑完管理后台里的任务本质上都是异步的。用户点击启动任务HTTP 接口只负责落库和投递真正的执行逻辑要放到线程池或者消息队列里。否则一个 Agent 跑 5 分钟HTTP 连接就挂 5 分钟网关层早就超时了。我们定义了五态任务状态机PENDING - RUNNING - SUCCESS |- FAILED |- TIMEOUT状态流转完全由 Java 侧驱动。进程启动后置 RUNNING正常退出且结果合法置 SUCCESS退出码非零置 FAILED超过最大执行时间就强制杀进程并置 TIMEOUT。这个状态机虽然简单但足以覆盖后台管理场景。后续要加 CANCELED 或 PAUSED也只是在这个基础上扩展。3. Spring Boot 侧落地从 ProcessBuilder 到任务状态机3.1 最容易被忽视的细节进程输出流必须异步消费用 ProcessBuilder 启动外部进程时新手最常犯的错误是启动后不读输出流。子进程写满 stdout 缓冲区后会被阻塞Java 侧看到的假象是进程卡死其实是没人消费输出。正确的做法是启动后立刻用独立线程消费 stdin/stdout/stderr。我们用的是CompletableFuture.runAsync把输出逐行写入任务日志文件。核心启动代码如下public class HarnessProcessRunner { private final ThreadPoolTaskExecutor taskExecutor; public StartedProcess start(AgentTask task) throws IOException { ProcessBuilder pb new ProcessBuilder( /opt/agent-platform/harness/venv/bin/python, -m, agentscope.harness, --config, task.getInputFile().toAbsolutePath().toString() ); pb.directory(task.getRuntimeDir().toFile()); pb.environment().put(PYTHONIOENCODING, utf-8); pb.redirectErrorStream(true); Process process pb.start(); Path logFile task.getLogFile(); CompletableFutureVoid ioFuture CompletableFuture.runAsync(() - { try (BufferedReader reader new BufferedReader( new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) { String line; while ((line reader.readLine()) ! null) { Files.writeString(logFile, line System.lineSeparator(), StandardCharsets.UTF_8, StandardOpenOption.CREATE, StandardOpenOption.APPEND); } } catch (IOException ignored) { // 进程退出时中断读取属正常情况 } }, taskExecutor); return new StartedProcess(process, ioFuture); } }3.2 状态轮询与超时回收Java 侧要当监工进程启动只是第一步后台还要有守护逻辑。我们用一个ScheduledExecutorService定时轮询每个 RUNNING 任务每次检查process.isAlive()。如果存活时间超过任务的timeout_seconds执行process.destroyForcibly()并把状态置为 TIMEOUT。如果进程已退出则根据退出码做最终状态判定。这里有一个很重要的细节destroyForcibly()杀掉的是当前 Process 对象对应的进程但如果 Harness 内部又 fork 了子进程那些子进程可能变成孤儿进程。我们的临时方案是写一个包装脚本用exec替换当前进程然后在 Java 侧按进程组处理#!/usr/bin/env bash # run_harness.sh cd /opt/agent-platform/harness exec ./venv/bin/python -m agentscope.harness --config $1exec是关键。它让 Harness 进程直接接管脚本的 PID这样 Java 侧拿到的process.pid()就是真正要监控的 Python 进程。配合kill -- -PID杀整个进程组能解决大部分孤儿进程问题。这是实际生产环境验证过的做法。3.3 任务表设计把进程信息落库才能做审计任务表要同时承担业务和运维两类信息。我们最终设计成如下核心字段字段说明id任务IDtask_code业务编号如 AGT-20250921-001task_name任务名称前端展示用pipeline_code对应 Harness 配置模板statusPENDING / RUNNING / SUCCESS / FAILED / TIMEOUTpidJava 侧记录的子进程 PIDexit_code进程退出码input_path输入 JSON 路径result_path结果 JSON 路径log_path日志文件路径error_msg失败原因摘要creator_id创建人create_time / finish_time时间记录落库的意义不只是列表展示更重要的是事故追溯。某天线上出问题运营说我没跑过这个任务后台一查 creator_id、启动时间、进程 PID、日志路径整条链路都摆在眼前。这正是 RuoYi-Vue-Plus 这类管理平台的价值。3.4 权限接入菜单、按钮和数据权限三件套RuoYi-Vue-Plus 的权限模型是现成的菜单决定能不能看到页面按钮权限决定能不能操作数据权限决定能看到哪些数据。我们新增了一个Agent 任务管理菜单下面挂启动、取消、删除三个按钮权限权限标识类似agent:task:add、agent:task:cancel、agent:task:delete。所有接口在 Controller 层加PreAuthorize注解。数据权限要特别提一下。任务不能是全局共享的否则某部门创建的任务其他部门也能看到。我们在任务表里加上部门字段并接入 RuoYi 的DataScope注解让列表接口按当前用户所属部门过滤。这是把 AI 能力接入管理后台时最容易被忽略但最不能省的设计。4. 跑通一个最小示例多智能体任务从创建到结果归档4.1 准备最小 Harness 配置我们以一个检索 写作的双 Agent 协作为例。Harness 配置文件里定义两个 agent一个负责检索材料一个负责汇总成文。配置模板放在task_templates/目录Java 侧启动任务时用实际参数替换模板变量。# multi_agent_writing.yaml harness: name: multi_agent_writing agents: - name: researcher role: 信息检索与材料整理 model: ${RESEARCHER_MODEL} - name: writer role: 根据材料撰写最终稿件 model: ${WRITER_MODEL} pipeline: - step: researcher.run output: research_notes - step: writer.run input: research_notes output: final_document output: format: json path: ${OUTPUT_DIR}/result.json这里的变量RESEARCHER_MODEL、WRITER_MODEL、OUTPUT_DIR通过 Java 侧启动任务时写入环境变量来注入。写死在 YAML 里的只有流程结构具体跑哪次任务由运行时决定。4.2 Java 侧启动任务的完整过程整个启动动作在用户点击启动按钮后发生链路如下前端提交任务表单后端把参数写入input.json创建任务记录状态置 PENDING。线程池从PENDING队列取出任务构建 ProcessBuilder调用start()。记录process.pid()到任务表状态置 RUNNING。启动独立线程消费输出流写入日志文件。调度线程每 2 秒检查一次状态超时则回收进程。代码实现上我们把这个启动方法放在AgentTaskService里用Async注解异步执行Async(agentTaskExecutor) public void runTaskAsync(AgentTask task) { try { StartedProcess started runner.start(task); task.setStatus(RUNNING); task.setPid(started.getPid()); taskService.updateById(task); boolean finished started.getProcess().waitFor( task.getTimeoutSeconds(), TimeUnit.SECONDS ); if (!finished) { started.getProcess().destroyForcibly(); task.setStatus(TIMEOUT); } else if (started.getProcess().exitValue() 0 resultFileExists(task)) { task.setStatus(SUCCESS); parseAndStoreResult(task); } else { task.setStatus(FAILED); task.setErrorMsg(lastLines(task.getLogFile(), 20)); } task.setFinishTime(LocalDateTime.now()); taskService.updateById(task); } catch (Exception e) { task.setStatus(FAILED); task.setErrorMsg(e.getMessage()); taskService.updateById(task); } }4.3 用户在页面看到的完整闭环用户在 RuoYi-Vue-Plus 的Agent 任务管理页面新建任务选择模板填写参数点击启动。列表里状态从待启动变成运行中再变成成功或失败。点击查看日志能看到实时追加的 Harness 输出点击查看结果能看到结构化 JSON 结果文件。整个交互和平时跑报表任务完全一样不需要用户理解底层是 Python 还是 Java。这一点在生产中极其重要。业务方不关心技术栈他们只关心任务能不能看到、能不能查、能不能撤销。AgentScope Harness 提供了 Agent 运行能力RuoYi-Vue-Plus 提供了任务管理能力两者各司其职。5. 踩坑清单从路径乱码到孤儿进程的实战记录5.1 虚拟环境路径问题可执行文件必须指向 venv 内 Python有同事图省事启动命令写python3 -m agentscope.harness结果子进程用的是系统 Python依赖全部丢失。更隐蔽的问题是 cron 或 systemd 环境里 PATH 和手动终端不一样可能意外切到另一个解释器。后来我们统一改为绝对路径venv/bin/python配置里写死并在启动脚本第一行做环境检查。这个坑的根因是你以为的 Python 和实际运行的 Python 不是同一个。凡是涉及子进程调用的系统都建议把可执行文件路径写成绝对路径不要依赖 PATH。5.2 中文日志乱码必须同时设置环境变量与读取编码Agent 的输出经常带中文第一次集成时日志文件里全是乱码。问题出在两个地方一是 Python 侧输出编码不是 UTF-8二是 Java 侧读取流时用了系统默认编码。解决方案是双管齐下pb.environment().put(PYTHONIOENCODING, utf-8); pb.environment().put(PYTHONUNBUFFERED, 1);读取端统一用StandardCharsets.UTF_8构造InputStreamReader。设置PYTHONUNBUFFERED1也很关键否则 Python 的 print 会走块缓冲Java 侧看日志总感觉延迟好几秒。5.3 超时杀进程后仍有残留用进程组兜底线上第一次遇到超时任务时Java 侧执行了destroyForcibly()状态置为 TIMEOUT。结果 5 分钟后发现机器上还挂着孤儿进程在跑继续消耗 GPU 显存。原因就是 Harness 内部可能拉起子进程destroyForcibly()只杀了父进程。我们最终用进程组方式兜底启动进程时让它成为独立的进程组组长回收时执行kill -- -PID把它和所有后代进程一起结束。Java 侧代码如下private void killProcessGroup(long pid) { try { Runtime.getRuntime().exec(new String[]{kill, --, - pid}); } catch (IOException e) { log.error(kill process group failed, pid{}, pid, e); } }这里补充说明先destroy()发送 SIGTERM等 5 秒再destroyForcibly()发送 SIGKILL最后如果进程组还存在再用kill -- -PID。多一级优雅退出结果文件更完整。5.4 并发任务资源竞争每个任务必须独立运行目录多个任务同时跑如果共用同一个工作目录日志和结果文件会互相覆盖。我们规定每个任务运行时目录为/runtime/{taskId}/所有中间文件都在该目录下。另外还要在 Java 侧限制最大并发数我们用的是线程池大小为 4配合信号量做任务级排队。AgentScope Harness 本身可能有自己的并发控制但 Java 侧这一层兜底仍然需要因为进程数和资源占用必须由平台掌握。5.5 命令注入风险用户入参永远不能直接拼进命令行RuoYi-Vue-Plus 这类平台通常有多个租户、多个角色。如果用户输入的任务 ID 或者其他参数直接拼进 ProcessBuilder 命令理论上存在命令注入风险。我们的做法是进程启动命令固定只有一条用户能配置的只有 JSON 文件里的参数绝不把前端传参拼到new ProcessBuilder(...)里。具体来说启动命令永远是new ProcessBuilder(harnessPythonPath, -m, agentscope.harness, --config, configFilePath)configFilePath是后端根据任务 ID 生成的固定路径不是用户传参。这算是最基础的输入校验但每次接新的外部进程时都要重新检查一遍。6. 从跑任务到沉淀能力下一步的扩展思考6.1 别丢掉 Harness 本身的评估语义集成过程中最容易犯的错误是把 Harness 当成万能执行器然后在 Java 侧重新实现一堆评估逻辑。实际上 Harness 的价值在于它自带可复用的评估、压测和结果归一化。我们后续要做回归对比时直接复用 Harness 的评测能力Java 侧只负责把历史结果拉出来做交叉比对。自己的业务系统永远只解决什么时候跑、结果怎么归档这两个问题至于怎么评估交给 Harness。6.2 任务模板中心让业务人员自己配模板现在每个任务模板都写在task_templates/目录里新增模板需要后端改代码。下一步我们计划做成数据库里的任务模板表前端可视化管理模板字段。业务人员选择模板、填参数、保存为模板再基于模板批量创建任务。这样 Agent 的运行能力就能逐步下沉给业务侧Java 后台退化为纯粹的流程编排与权限管理。6.3 结果回调与业务联动从异步任务到自动化流程现在的流程在结果归档就结束了。更进一步的玩法是Harness 跑完的结果写入某个业务表触发后续的人工审批或自动通知。比如多智能体生成了一份分析报告跑完后自动给负责人推一条待办负责人审阅后可以一键发布。这是把 AI 能力真正嵌入企业流程的关键一步也是 RuoYi-Vue-Plus 这类平台的天然主场。最后再分享一个我们后期一定会保留的设计习惯任务结果文件里除了最终的评估输出尽量把 Agent 的运行轨迹原始数据也一起落盘。这些原始轨迹现在看没什么用等你想做任务回放、异常分析或者换模型对比时就知道当时的决策有多划算了。集成 AgentScope Harness 到 RuoYi-Vue-Plus 这个过程本身不难难的是把进程、状态机、权限和安全边界都想清楚。这套链路跑通之后Java 平台管理 AI 能力就不再是一个别扭的伪命题而是一条非常务实的落地路径。