6.HarnessAgent:为 ReActAgent 装上操作系统

一灰灰blogAgentScope Java新手村进阶架构HarnessAgent 工程底座AgentScopeJavaHarnessAgentAI Agent约 5372 字大约 18 分钟

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 的隔离与持久化机制。两者互不干扰,且业务代码在两者之间切换的成本几乎为零。

fa0XZClwI.jpeg
fa0XZClwI.jpeg

接下来,我们将操作系统的四大经典子系统一一映射到 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)
进程控制块PCBAgentState (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.mdopen in new window 有啥用,简单的说——它就是 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 调用)将子任务委派出去,并通过管道(内存消息传递)收集结果,最终汇总返回给用户。整个过程对开发者完全透明。

image.webp
image.webp

五、安全隔离(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 同样有严格的优先级顺序。

具体顺序分析:

  1. CompactionHook(优先级 10):最先执行,检查上下文是否超限。如果满了,先压缩历史,腾出空间。这就像操作系统先初始化 MMU。
  2. SubagentsHook(优先级 80):随后注入子 Agent 列表到上下文。这相当于加载系统调用表。
  3. WorkspaceContextHook(优先级 900):最后执行,将压缩后的摘要、子 Agent 列表、AGENTS.mdopen in new window 一同拼装进最终的 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.mdopen in new window长期记忆、环境配置、持久化存储
内存管理 (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. 下篇预告

第一阶段:新手村 —— 核心概念与快速起步

第二阶段:进阶架构 —— 掌握 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

Loading...