6.HarnessAgent:为 ReActAgent 装上操作系统
ReActAgent 是一颗纯粹的 CPU——只懂"取指→译码→执行"的无限循环。但单靠 CPU 跑不了任何业务程序,它需要操作系统来管理进程、调度内存、隔离文件。HarnessAgent 就是 ReActAgent 的操作系统内核。

HarnessAgent:为 ReActAgent 装上操作系统——从 CPU 到操作系统,Harness 的四大子系统深度解析
在上一篇文章中,我们掌握了让 Agent 直接返回 Java 对象的技巧,体验了 ReActAgent 在结构化输出上的便利。但不知道各位小伙伴有没有注意到一个关键细节——我们所有的 Demo,无论使用 ReActAgent 还是 HarnessAgent,call() 方法都需要传入一个 RuntimeContext。
那么问题来了——为什么?因为 ReActAgent 是无状态的。它像 CPU 一样不保存任何进程上下文,每次执行只关心当前输入的指令。同一个 ReActAgent 实例可以同时为 Alice 和 Bob 服务,互不干扰,因为它根本不"记住"任何东西——所有状态都通过 RuntimeContext 外置,随着 Reactor 上下文在调用链中传递。
这种设计优雅、高效,但现实世界的 Agent 应用,需要的远不止一个"取指→译码→执行"的循环。它还需要:
- 进程管理:多个用户同时使用,状态不能串;会话中断后能原地恢复
- 文件系统:Agent 需要读写文件、保存中间产物,不同用户之间相互隔离
- 内存管理:对话长了会爆 Token,需要自动压缩和交换(Swap)
- 安全隔离:Agent 执行的代码不能直接操作宿主机,必须扔进"容器"里
- 进程间通信(IPC):一个 Agent 需要委派子任务给其他专门的 Agent
这些正是操作系统要解决的核心问题——而 HarnessAgent,就是 Agent 世界的操作系统内核。它不是一个新的推理引擎,而是在 ReActAgent 这个"CPU"外面包裹了一层工程化的操作系统内核。
一、从 CPU 到操作系统:为什么要分层?
1. 现状回顾:无状态的 ReActAgent
一般来讲,当我们用 ReActAgent 的时候,使用姿势是这样的:
// ReActAgent —— 纯粹的计算核心
ReActAgent agent = ReActAgent.builder()
.name("assistant")
.sysPrompt("你是一个有帮助的助手。")
.model("glm:glm-4-flash")
.build();
// 同一个实例,通过 RuntimeContext 区分不同进程(用户/会话)
agent.call(List.of(new UserMessage("你好")),
RuntimeContext.builder().userId("alice").sessionId("session-1").build()).block();
agent.call(List.of(new UserMessage("Hi there")),
RuntimeContext.builder().userId("bob").sessionId("session-2").build()).block();
这种设计下,Agent 实例本身是"无状态的计算单元",所有上下文都通过 RuntimeContext 传递。调用结束,状态即消失。
2. 痛点提炼:裸 CPU 无法直接跑业务
如果我们要构建一个持续运行数小时甚至数天的 Agent(比如自动代码审查、多轮需求澄清、数据分析流水线),就会面临一系列工程挑战。不夸张的说,如果用裸 ReActAgent 去跑这种场景,估计会敲得键盘原地爆炸了。下面这张表清晰地展示了 ReActAgent 的短板与生产环境的刚需:
| 能力维度 | ReActAgent(裸 CPU) | 生产环境刚需(操作系统) |
|---|---|---|
| 状态管理 | 仅在单次调用内有效,调用结束即销毁 | 跨会话持久化,宕机也能恢复 |
| 会话隔离 | 依赖调用方手动传入 SessionId | 自动创建、隔离、恢复会话上下文 |
| 长期记忆 | 无,每次都是"初次见面" | 拥有持久化的"堆内存"和"硬盘" |
| 文件系统 | 无内置工作区 | 持久化工作目录,自动管理文件生命周期 |
| 安全执行 | 直接在 JVM 进程执行,无隔离 | 容器化隔离,限制资源与权限 |
| 子任务委派 | 不支持 | 主 Agent 自动 Fork 子 Agent 处理专项任务 |
3. 设计哲学:微内核架构(薄包装)
那么问题来了——HarnessAgent 是怎么设计的呢?
HarnessAgent 的核心设计理念是关注点分离,在操作系统领域,这被称为微内核架构。
- ReActAgent(CPU/内核):专注于"如何推理"这一算法问题。
- HarnessAgent(操作系统外壳):专注于"在哪里推理、以什么状态推理、结果如何持久化"等工程问题。
这种分层带来的最大好处是可测试性与可替换性——你可以单独验证 ReActAgent 的推理正确性,也可以单独测试 HarnessAgent 的隔离与持久化机制。两者互不干扰,且业务代码在两者之间切换的成本几乎为零。

接下来,我们将操作系统的四大经典子系统一一映射到 HarnessAgent 的能力上。
二、进程管理(Session):让 Agent 状态像进程一样可恢复
操作系统通过进程控制块(PCB) 保存每个进程的状态(寄存器、程序计数器、内存映射等),从而实现进程的切换与恢复。HarnessAgent 的 Session 就是 Agent 世界的 PCB。
1. 从临时 Context 到持久化 PCB
ReActAgent 的 RuntimeContext 是一次性的,相当于 CPU 的寄存器——只在当前指令周期有效。HarnessAgent 将其升级为持久化的 Session,支持 Redis 等分布式存储后端。使用姿势如下:
// 配置 Redis 分布式 Session(相当于将 PCB 存储在共享存储中)
var jedis = new JedisPooled(System.getenv("REDIS_URI"));
var session = RedisSession.builder()
.jedisClient(jedis)
.build();
HarnessAgent agent = HarnessAgent.builder()
.name("coding-assistant")
.model("glm:glm-4-flash")
.workspace(workspace)
.session(session) // 注入进程管理器
.distributedStore(RedisDistributedStore.fromJedis(jedis)) // 分布式共享存储
.build();
2. 进程快照与热迁移(自动恢复)
操作系统的进程可以休眠到磁盘(Hibernate),唤醒后原地继续执行。HarnessAgent 的 Session 机制实现了类似的能力——即使应用重启,只要 SessionId 不变,Agent 就能从 Workspace/Redis 中恢复全部状态:
// 第一次调用 —— 正常对话
agent.call(List.of(new UserMessage("我们正在讨论微服务拆分方案")),
RuntimeContext.builder().userId("yihuihui").sessionId("project-arch").build()).block();
// ... 服务因发布重启了 ...
// 第二次调用 —— 同一个 sessionId,Agent 自动加载 PCB,恢复现场!
agent.call(List.of(new UserMessage("刚才我们聊到哪了?")),
RuntimeContext.builder().userId("yihuihui").sessionId("project-arch").build()).block();
输出结果如下:
➜ 根据我们的对话记录,我们之前正在讨论微服务拆分方案,
已经确定了使用领域驱动设计(DDD)来划分限界上下文。
要继续吗?
重点关注——HarnessAgent 的 ensureSessionDefaults() 方法会在每次调用时检查 SessionId。若未传入则使用 Agent 名称作为默认值。随后从分布式存储中加载 AgentState(包含历史消息、工具调用结果、记忆索引等),调用结束后再将更新后的状态持久化回去。这就像操作系统在进程时间片用完时保存上下文,下次调度时恢复。
3. 分时复用与多租户隔离
在操作系统中,分时复用让一个 CPU 核心服务多个进程。HarnessAgent 的 Session 机制同样支持一个 Agent 实例服务成千上万个用户,状态通过 (userId, sessionId) 组合键完美隔离。贴心的一灰灰博主给大家整理了一张对照表:
| 概念 | 操作系统 | HarnessAgent |
|---|---|---|
| 进程标识符 | PID | (userId, sessionId) |
| 进程控制块 | PCB | AgentState (Redis/DB) |
| 上下文切换 | 保存/恢复寄存器 | 保存/恢复消息历史与记忆 |
| 进程迁移 | 热迁移 | 分布式 Store + Session 恢复 |
三、文件系统与内存管理:Workspace 与 Memory Compaction
操作系统为每个进程提供虚拟文件系统和虚拟内存。HarnessAgent 的 Workspace 和 Memory Compaction 正是对应这两大基础设施。
1. Workspace:Agent 的持久化根目录
Workspace 是 Agent 的专属工作目录,相当于给每个 Agent 挂载了一块独立的硬盘。其标准目录结构如下:
/var/agentscope/workspace/
├── AGENTS.md # 进程环境变量与配置(人格设定)
├── MEMORY.md # 进程堆内存(长期记忆,自动维护)
├── memory/ # 内存映射文件(记忆碎片)
├── skills/ # 动态链接库(自学习技能)
├── plans/ # 计划缓存
├── agents/ # 子进程定义(Subagent 配置)
└── sessions/ # 进程日志(会话审计日志)
请注意——AGENTS.md 是工作区的灵魂文件。这相当于操作系统的 /etc/environment 或进程的启动配置文件。它定义了 Agent 的角色、行为规范和背景知识。HarnessAgent 启动时会自动读取此文件注入 System Prompt。
<!-- AGENTS.md -->
# 角色定位
你是一个 Java 代码评审专家,专长于 Spring Boot 微服务架构。
# 行为准则
- 聚焦:代码可读性、性能、安全性、可测试性
- 输出:具体行号和修复建议
- 语言:中文
# 背景知识(环境变量)
- 技术栈:Spring Boot 3.x, JDK 17+, MySQL 8.0
- 部署:Docker + K8s
关于这个 AGENTS.md 有啥用,简单的说——它就是 Agent 的"人格设定文件"。没有它,Agent 每次启动都是一张白纸;有了它,Agent 一上来就知道"我是谁、我要做什么、我有哪些约束"。这个机制的具体细节,在后续的文章中会展开介绍,这里就不赘述了。
2. Memory Compaction:内存压缩与交换(Swap)
进程跑久了,内存(上下文)会越来越臃肿,导致"内存溢出"(Token 超限)或"性能下降"(注意力分散)。操作系统通过内存交换(Swap) 将不活跃的页面移到磁盘。HarnessAgent 的 Memory Compaction 机制与此如出一辙:
HarnessAgent agent = HarnessAgent.builder()
.name("coding-assistant")
.model("glm:glm-4-flash")
.workspace(workspace)
.compaction(CompactionConfig.builder()
.triggerMessages(50) // 消息超过 50 条时触发压缩
.keepMessages(20) // 保留最近的 20 条
.model("dashscope:qwen-turbo") // 用轻量模型做压缩,省钱
.build())
.toolResultEviction(ToolResultEvictionConfig.defaults()) // 大工具结果自动淘汰
.build();
工作原理:当上下文消息数超过阈值,HarnessAgent 会调用轻量级模型对历史进行摘要压缩,将压缩后的摘要作为新的"系统提示"注入(相当于写入 Swap 分区),同时保留最近 N 条完整消息在"物理内存"中。
最佳实践:长链路 Agent 必须配置 Compaction,不然就像不给操作系统配置 Swap 分区一样,迟早会 OOM(Token 爆掉)。当然配置的时候建议指定一个轻量模型来做压缩,别用主模型——不然压缩一次的成本比推理还高,那就有点鬼畜了。
四、进程间通信(Subagent):实现 Agent 的 fork() 系统调用
操作系统通过 fork() 创建子进程,通过管道(Pipe)或消息队列进行 IPC。HarnessAgent 的 子 Agent 编排 正是这套机制的完美映射。
1. 声明式配置:像 systemd 一样定义子服务
操作系统通过 .service 文件定义子服务。 HarnessAgent 通过 工作区 spec 文件声明子 Agent:(AgentId就是移除.md后缀的文件名)
# subagents/reviewer.md(相当于 /etc/systemd/system/reviewer.service)
---
description: 代码评审专家 # 服务描述,主 Agent 据此判断是否调用
workspace:
mode: isolated # 独立地址空间(isolated)或共享内存(shared)
path: ./defs/reviewer # 子进程工作目录
model: glm:GLM-4-Flash # 子进程专属资源
steps: 8 # CPU 时间片(最大推理步数)
tools: [read_file, grep_files] # 允许访问的系统调用(工具白名单)
---
你是一个专注代码评审的子 Agent。你的职责是:
- 检查代码质量、安全性、性能问题
- 给出具体的修改建议
- 输出评审报告
2. 编程式 Fork
除了声明式配置,也可以在代码中动态"Fork"子 Agent:
HarnessAgent agent = HarnessAgent.builder()
.name("orchestrator") // 主进程
.model("glm:glm-4-flash")
.workspace(workspace)
.subagent(SubagentDeclaration.builder()
.name("reviewer")
.description("代码审查专家")
.workspace(Path.of("./defs/reviewer"))
.workspaceMode(WorkspaceMode.ISOLATED)
.model("glm-4-flash")
.steps(8)
.tools(List.of("read_file", "grep_files"))
.build())
.build();
3. 通信模式:独立地址空间 vs 共享内存
| 模式 | 操作系统类比 | HarnessAgent 适用场景 |
|---|---|---|
| isolated | 独立进程,地址空间隔离 | 代码评审、安全扫描(防止子进程破坏父进程数据)-- 默认方式 |
| shared | 共享内存(同一个工作区) | 文档处理、数据转换(需要共享中间产物) |
当主 Agent(Orchestrator)接收到复杂请求时,它会自动进行任务分解,通过 fork()(子 Agent 调用)将子任务委派出去,并通过管道(内存消息传递)收集结果,最终汇总返回给用户。整个过程对开发者完全透明。

五、安全隔离(Sandbox):用户态与内核态分离
操作系统通过用户态/内核态隔离保护系统安全。HarnessAgent 的 Sandbox(沙箱) 机制实现了同样的目标——将 Agent 的代码执行和文件操作隔离到 Docker 容器中,防止恶意或错误的工具调用搞崩宿主系统。
1. 容器化隔离(虚拟内存与命名空间)
使用姿势如下:
HarnessAgent agent = HarnessAgent.builder()
.name("sandbox-agent")
.model("glm:glm-4-flash")
.workspace(workspace)
.filesystem(new DockerFilesystemSpec()
.image("python:3.12-slim") // 基础镜像
.isolationScope(IsolationScope.USER) // 隔离粒度
.memorySizeBytes(512 * 1024 * 1024L) // 512MB 内存限制
.cpuCount(2L) // 2 核 CPU
.network("host") // 网络模式
.exposedPorts(8080, 3000) // 暴露端口
.snapshotSpec(new LocalSnapshotSpec("/data/snapshots")))
.build();
请注意,同一个 userId 多次执行,会自动复用同一个沙箱,避免重复创建;
2. 隔离级别(权限 rings)
操作系统有 Ring 0(内核态)到 Ring 3(用户态)。HarnessAgent 提供了三种隔离级别:
| 隔离级别 | 操作系统类比 | 适用场景 |
|---|---|---|
NONE | 内核态运行(无保护) | 本地开发测试 |
SESSION | 每个会话一个独立的虚拟机(强隔离) | 多租户 SaaS,安全要求极高 |
USER | 同一用户共享一个容器(进程组) | 同一用户的多个会话共享工作区,节省资源 |
3. 快照与休眠(Suspend to Disk)
操作系统的"休眠"功能将内存状态保存到磁盘。HarnessAgent 支持将沙箱状态快照保存到 OSS(对象存储),实现真正的"无限持久化":
var oss = new OssSnapshotSpec(
"oss-cn-hangzhou.aliyuncs.com",
System.getenv("OSS_AK"), System.getenv("OSS_SK"),
"agentscope-sandbox-snapshots", "prod/");
var sandboxSpec = new DockerFilesystemSpec()
.image("python:3.12-slim")
.executionGuard(new RedisSandboxExecutionGuard(
jedis, "agentscope:guard:", Duration.ofSeconds(30)));
HarnessAgent agent = HarnessAgent.builder()
.name("coding-assistant")
.model("glm:glm-4-flash")
.workspace(workspace)
.filesystem(sandboxSpec)
.sandboxDistributed(SandboxDistributedOptions.oss(session, oss))
.build();
这意味着即使容器被销毁,Agent 的工作区快照已保存至远端 OSS。下次请求到来时,系统自动从 OSS 拉取快照恢复容器——Agent 完全感知不到底层容器的生命周期变化,就像用户感知不到电脑休眠过一样。
4. 生命周期管理(资源回收)
HarnessAgent 通过 Reactor 的 Mono.using 模式确保沙箱资源(容器)在调用结束后被正确释放,无论是否发生异常:
// wrappedCall() 的简化逻辑
private Mono<Msg> wrappedCall(List<Msg> msgs, RuntimeContext effective,
Supplier<Mono<Msg>> inner) {
return Mono.using(
() -> {
sandboxLifecycleMw.acquireForCall(effective); // 获取容器
return effective;
},
eff -> inner.get(), // 执行推理循环
eff -> {
sandboxLifecycleMw.releaseForCall(eff); // 释放容器,保存快照
});
}
这正是操作系统保证"进程退出后回收内存和文件描述符"的健壮性体现。
六、Middleware 执行顺序:操作系统的初始化加载
为什么 HarnessAgent 能像操作系统一样井井有条?答案在于 Middleware 的优先级队列。操作系统启动时有固定的加载顺序(Bootloader → Kernel → Initrd → 根文件系统),HarnessAgent 的 Middleware 同样有严格的优先级顺序。
具体顺序分析:
- CompactionHook(优先级 10):最先执行,检查上下文是否超限。如果满了,先压缩历史,腾出空间。这就像操作系统先初始化 MMU。
- SubagentsHook(优先级 80):随后注入子 Agent 列表到上下文。这相当于加载系统调用表。
- WorkspaceContextHook(优先级 900):最后执行,将压缩后的摘要、子 Agent 列表、AGENTS.md 一同拼装进最终的 System Prompt。这类似于操作系统最后加载 init 进程,拉起用户界面。
关键原则:后执行的依赖先执行的。WorkspaceContextHook 必须最后执行,因为它依赖 Compaction 和 Subagent 处理完毕后的数据。
七、从单机到集群:三种部署场景一览
理解了四大子系统后,我们来看实际开发中如何根据场景配置。下面给出一份从"单机"到"分布式集群"的演进指南。
场景一:本地开发环境(单机操作系统)
配置最简单,无状态持久化需求,适合本地调试:
// 个人电脑调试,无需分布式存储和强隔离
HarnessAgent agent = HarnessAgent.builder()
.name("dev-agent")
.model("glm:glm-4-flash")
.workspace(Paths.get("./local-workspace")) // 本地文件系统
.build();
场景二:SaaS 多租户(分时操作系统)
一个 Agent 实例服务成千上万用户,需要进程隔离和状态持久化。类似于大型机分时系统:
// 云端 SaaS,每个用户数据隔离,进程可恢复
var jedis = new JedisPooled(System.getenv("REDIS_URI"));
var session = RedisSession.builder().jedisClient(jedis).build();
HarnessAgent agent = HarnessAgent.builder()
.name("saas-agent")
.model("glm:glm-4-flash")
.workspace(Paths.get("/cloud/workspace"))
.session(session) // 状态持久化到 Redis
.filesystem(new DockerFilesystemSpec()
.image("python:3.12-slim")
.isolationScope(IsolationScope.USER)) // 每个用户一个容器
.compaction(CompactionConfig.builder()
.triggerMessages(30).build()) // 内存管理
.build();
场景三:企业级分布式集群(集群操作系统)
多副本部署,支持宕机迁移和水平扩展:
// 生产环境集群,支持故障转移和海量数据
var jedis = new JedisPooled(System.getenv("REDIS_URI"));
var session = RedisSession.builder().jedisClient(jedis).build();
var oss = new OssSnapshotSpec(/* OSS 配置 */);
HarnessAgent agent = HarnessAgent.builder()
.name("cluster-agent")
.model("glm:glm-4-flash")
.workspace(Paths.get("/data/workspace"))
.session(session)
.distributedStore(RedisDistributedStore.fromJedis(jedis))
.filesystem(new DockerFilesystemSpec()
.image("python:3.12-slim"))
.sandboxDistributed(SandboxDistributedOptions.oss(session, oss))
.middlewares(List.of(new OtelTracingMiddleware()))
.skillRepository(MysqlSkillRepository.builder(dataSource).build())
.build();
八、小结
我们从"CPU vs 操作系统"的比喻出发,将 HarnessAgent 的复杂能力映射为操作系统的四大经典子系统,并深入了 Middleware 的执行原理与三种实战部署场景。回顾来看,ReActAgent 与 HarnessAgent 的分工明确而优雅:
| 操作系统概念 | HarnessAgent 实现 | 解决的问题 |
|---|---|---|
| 进程管理 (PCB) | Session + Redis | 多租户隔离、宕机恢复、状态持久化 |
| 文件系统 (VFS) | Workspace + AGENTS.md | 长期记忆、环境配置、持久化存储 |
| 内存管理 (MMU/Swap) | Compaction + Memory | 防止上下文爆炸(Token 溢出) |
| 安全隔离 (Ring0/3) | Docker Sandbox + OSS | 安全执行代码,故障隔离 |
| 进程间通信 (IPC) | Subagent 编排 | 任务分解、专职 Agent 协作 |
| 系统引导 (Init) | Middleware 优先级队列 | 确保组件按依赖顺序初始化 |
回到文章开头的问题——"ReActAgent 是无状态的,那状态放哪儿?"
答案已经非常清晰:ReActAgent 作为 CPU 只负责计算,而 HarnessAgent 作为操作系统负责管理所有状态与资源。这种"微内核"式的关注点分离,使得 AgentScope Java 2.0 既能保持核心推理引擎的轻量高效,又能支撑起企业级的分布式、长链路、高安全需求。
作为一个有思考的小青年,我觉得这种设计的精妙之处在于——它没有重新发明轮子,而是把计算机操作系统几十年积累的智慧直接映射到了 Agent 的世界里。下次当你看到一个 HarnessAgent 的配置时,不妨想想背后对应的是操作系统的哪个经典机制,理解起来就豁然开朗了。
下一篇文章,我们将深入 HarnessAgent 的 Workspace 工作区机制,看看操作系统之上的"文件系统"到底有多骚——通过 AGENTS.md 定义人设,通过 MEMORY.md 沉淀长期事实,实现"改文件即升级 Agent"。看到这里的小伙伴,不妨点个赞,顺手关注下微信公众号"一灰灰blog",咱们下篇见!
九、其他
0. 项目
1. 下篇预告
第一阶段:新手村 —— 核心概念与快速起步
- ✅ 第1篇:简介与环境搭建:从零搭环境,跑通第一个 Agent 对话
- ✅ 第2篇:ReActAgent 核心拆解:理解"思考→行动→观察"的推理循环
- ✅ 第3篇:你的第一个 Java Agent:Builder 模式全面解析 + 流式输出 + 思考模式
- ✅ 第4篇:工具系统(Tools)实战:用
@Tool注解将 Java 方法注册为 Agent 工具 - ✅ 第5篇:结构化输出实战 —— 让 Agent 直接返回 Java 对象
第二阶段:进阶架构 —— 掌握 2.0 的核心亮点 HarnessAgent,理解"文件即配置"的工程化理念。
- ✅ 6.HarnessAgent:为 ReActAgent 装上操作系统:对比 ReActAgent,理解 Harness 如何整合长期记忆、Session、子 Agent 编排与沙箱。
- 7. Workspace 驱动的人格与记忆(下一篇):通过
AGENTS.md定义人设,通过MEMORY.md沉淀长期事实,实现"改文件即升级 Agent"。 - 8. Skills 技能系统(核心):掌握
SKILL.md文件协议,理解"操作手册 + 资料包"的按需加载机制,节省 Token。 - 9. 多层级 SkillRepository 组合:实战 Workspace、Git、Nacos、MySQL 等 5 层仓库的组合与隔离。
- 10. 流式事件与前端交互:使用
streamEvents()实时展示 Agent 执行过程,对接 Web UI 渲染。
尽信书则不如无书,以上内容纯属一家之言。因个人能力有限,难免有疏漏和错误之处,如发现 Bug 或有更好的建议,欢迎批评指正,不吝感激。
微信公众号:一灰灰Blog