AgentScope-Java v2.0 版本 ReActAgent vs HarnessAgent 差异解析与场景选择- 惊觉

本文基于 AgentScope Java v2 官方文档分析总结，帮助理解两个核心 Agent 抽象的设计意图、能力边界和选型策略。

一、本质定位

官方原文：HarnessAgent 是 ReActAgent 的一层薄包装，把长期运行 agent 必备的工程能力打包进单一 builder。

┌─────────────────────────────────────────────────────────┐
│                    HarnessAgent                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │              ReActAgent（核心推理引擎）              │  │
│  │  一次请求 → 推理 → 工具调用 → 回复                  │  │
│  └───────────────────────────────────────────────────┘  │
│  + 工作区  + 会话持久化  + 长期记忆  + 压缩               │
│  + 子Agent编排  + 沙箱隔离  + 技能装配  + 计划模式        │
└─────────────────────────────────────────────────────────┘

一句话区别：

抽象	解决什么问题
ReActAgent	「一次请求 → 推理 → 工具 → 回复」
HarnessAgent	「下一轮怎么接着上一轮、上下文如何保持有界、多用户如何隔离、危险操作如何先 review 再执行、可复用能力如何沉淀」

二、架构层面三大核心差异

2.1 能力是「叠加」而非「改写」

ReActAgent 的核心算法（推理-行动循环）没有被修改，Harness 只是在 ReAct 循环的关键时机通过 middleware 注入额外能力：

ReActAgent 主循环:
  输入 → 推理 → LLM调用 → 工具调用 → 结果 → 循环/返回

Harness 叠加后:
  输入 → [工作区注入] → 推理 → [压缩检查] → LLM调用
       → [权限审查] → 工具调用 → [沙箱执行] → 结果
       → [记忆沉淀] → 循环/返回

2.2 三个共享对象实现能力解耦

ReActAgent 是无状态的（除非手动配 Session），而 Harness 通过三个共享对象让所有能力互不依赖地协作：

共享对象	作用	持久化
`RuntimeContext`	当前调用身份：`sessionId`、`userId`、自定义 extra	❌ 不持久化，per-call
工作区（Workspace）	谁读写哪些文件，落盘到哪由配置决定	✅ 持久化
`Session`	跨调用恢复运行时状态	✅ 持久化

2.3 Middleware 注册顺序

Harness 在构建期按固定顺序串起所有内置 middleware，用户通过 .middleware(...) 加的自定义 middleware 跑在所有 Harness 内置之前。

三、能力对比清单

能力	ReActAgent	HarnessAgent	说明
推理-行动循环	✅	✅	Harness 直接复用
工具调用（Tool / MCP）	✅	✅	两者一致
权限系统	✅	✅	两者一致
人机交互（HITL）	✅	✅	两者一致
流式输出（streamEvents）	✅	✅	两者一致
Middleware 钩子	✅	✅	Harness 多了内置链路
Session 持久化	⚠️ 需手动配置	✅ 默认开启	ReActAgent 需 `.session()` 手动配
工作区驱动人格	❌	✅ `.workspace(path)`	AGENTS.md / MEMORY.md / skills/ / tools.json
双层长期记忆	❌	✅ `.compaction(...)`	事实自动沉淀到 MEMORY.md
对话压缩	❌	✅ `.compaction(...)`	上下文有界，溢出时强制重试
大工具结果卸载	❌	✅ `.toolResultEviction(...)`	超 80K 字符落盘 + 占位符
子 Agent 编排	❌	✅ `.subagent(...)`	同步/后台，自动反向通知
可插拔文件系统	❌	✅ `.filesystem(...)`	本机/共享存储/沙箱无缝切换
沙箱隔离	❌	✅ `.filesystem(new DockerFilesystemSpec()...)`	Docker 级文件与命令隔离
计划模式（Plan Mode）	❌	✅ `.enablePlanMode()`	只读思考 + HITL 退出
技能装配	❌	✅ `.skillRepository(...)`	Git/Nacos/MySQL/classpath/工作区
MCP 工具白名单	❌	✅ `workspace/tools.json`	声明式配置允许/拒绝

四、状态管理差异

ReActAgent 只有调用内状态，而 Harness 有三层状态自动流转：

┌──────────────────────────────────────────────────────┐
│  ReActAgent: 仅调用内状态                              │
│                                                      │
│  AgentState (对话上下文 + 权限 + 工具状态)              │
│  RuntimeContext (sessionId, userId)                   │
│  → 调用结束即丢失（除非手动配 Session）                  │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│  HarnessAgent: 三层状态自动流转                         │
│                                                      │
│  第一层: 调用内状态                                     │
│    AgentState + RuntimeContext                        │
│                                                      │
│  第二层: 跨调用状态（自动持久化）                        │
│    agents/<agentId>/context/<sessionId>/              │
│    sessions/<sessionId>.log.jsonl (永不压缩)           │
│    子任务记录、沙箱元数据                               │
│                                                      │
│  第三层: 长期记忆（跨 Session 累积）                    │
│    memory/YYYY-MM-DD.md (只追加)                       │
│    MEMORY.md (周期合并，注入 system prompt)             │
└──────────────────────────────────────────────────────┘

三个值得记住的规律：

system prompt 每轮重新拼 — 修改 AGENTS.md 或 MEMORY.md 立刻生效，无需重启
压缩/记忆提炼/后台维护都有节流闸门 — 不会每轮都跑，避免性能损耗
AgentState 由 core 的 ReActAgent + Session 自动持久化 — Harness 不再额外做这件事

五、Maven 依赖差异

<!-- 只用 ReActAgent：轻量 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-core</artifactId>
    <version>2.0.0-RC1</version>
</dependency>

<!-- 用 HarnessAgent：包含 core + 全部工程能力 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.0-RC1</version>
</dependency>

六、典型代码对比

ReActAgent — 轻量单次调用

ReActAgent agent = ReActAgent.builder()
        .name("simple_agent")
        .sysPrompt("你是一个有帮助的助手。")
        .model("dashscope:qwen-plus")
        .toolkit(new Toolkit())
        .build();

Msg result = agent.call(List.of(new UserMessage("你好"))).block();

HarnessAgent — 生产级多轮对话

HarnessAgent agent = HarnessAgent.builder()
        .name("enterprise-assistant")
        .sysPrompt("你是一个企业级助手。")
        .model("dashscope:qwen-plus")
        .workspace(Paths.get(".agentscope/workspace"))
        .compaction(CompactionConfig.builder()
                .triggerMessages(30)
                .keepMessages(10)
                .build())
        .filesystem(new DockerFilesystemSpec()...)
        .enablePlanMode()
        .build();

RuntimeContext ctx = RuntimeContext.builder()
        .sessionId("user-123-session-456")
        .userId("alice")
        .build();

agent.call(new UserMessage("帮我分析上周的销售数据"), ctx).block();

七、场景选择指南

适合 ReActAgent 的场景

场景	原因
无状态工具调用	单次请求-响应，不需要记住上一轮
快速原型 / PoC	最少配置，快速验证想法
嵌入式 Agent	作为 Pipeline / Workflow 中的一个节点
自定义 Agent 编排	自己实现多 Agent、状态管理、记忆等
轻量级微服务	对依赖体积敏感
单元测试	配合 `InMemorySession` 做单元测试
简单 Chatbot	一问一答，无需持久化

适合 HarnessAgent 的场景

场景	使用的 Harness 能力
多轮长期对话	Session 自动持久化，`sessionId` 不变即恢复
多用户 / 多租户	`RuntimeContext` 天然隔离 userId / sessionId
需要记忆积累	双层记忆：对话压缩 + MEMORY.md 长期事实沉淀
生产部署	沙箱隔离、文件系统抽象、Redis/MySQL Session
子 Agent 编排	声明式子 Agent，支持同步/后台/流式
技能复用	Git/Nacos/MySQL 技能仓库，可跨 Agent 共享
安全敏感操作	Plan Mode 先思考再执行、HITL 审批、权限白名单
代码生成 / Coding Agent	沙箱隔离执行、文件系统抽象
企业级 AI 助手	工作区驱动人格、MCP 白名单、记忆系统全套

八、决策流程图

你的 Agent 需要什么？
│
├─ 只需要一次问答 ──────────────────────→ ReActAgent
│
├─ 需要多轮对话但无持久化需求 ───────────→ ReActAgent + InMemorySession
│
├─ 需要会话持久化 ──────────────────────→ ReActAgent + JsonSession/RedisSession
│                                        （手动配置 session）
│
├─ 需要长期记忆 + 对话压缩 ─────────────→ HarnessAgent (.compaction)
│
├─ 需要工作区驱动人格/技能 ─────────────→ HarnessAgent (.workspace)
│
├─ 需要子Agent编排 ─────────────────────→ HarnessAgent (.subagent)
│
├─ 需要沙箱隔离 ────────────────────────→ HarnessAgent (.filesystem + Docker)
│
├─ 需要多用户隔离 + 生产部署 ────────────→ HarnessAgent（全套）
│
└─ 需要以上多个能力的组合 ──────────────→ HarnessAgent（按需开启）

九、总结

维度	ReActAgent	HarnessAgent
类比	发动机	整辆汽车（发动机 + 底盘 + 车身）
关注点	推理质量、工具准确性	工程完备性、长期运行、生产就绪
复杂度	低，几行代码启动	中，需要理解工作区目录结构
可扩展性	通过 Middleware 自由扩展	内置能力丰富，也支持自定义 Middleware
学习路径	先学 ReActAgent → 再学 Harness	推荐：直接从 Harness 快速开始
适用阶段	原型验证、学习理解	生产部署、企业应用

官方推荐路径：先用 HarnessAgent 快速开始（依赖 agentscope-harness 即可），理解工作区、记忆、会话等概念后，再根据实际需要决定是否降级到裸 ReActAgent 做更精细的控制。

参考资料

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/catoop/article/details/161695113

AgentScope-Java v2.0 版本 ReActAgent vs HarnessAgent 差异解析与场景选择

一、本质定位

二、架构层面三大核心差异

2.1 能力是「叠加」而非「改写」

2.2 三个共享对象实现能力解耦

2.3 Middleware 注册顺序

三、能力对比清单

四、状态管理差异

五、Maven 依赖差异

六、典型代码对比

ReActAgent — 轻量单次调用

HarnessAgent — 生产级多轮对话

七、场景选择指南

适合 ReActAgent 的场景

适合 HarnessAgent 的场景

八、决策流程图

九、总结

参考资料

评论

评论列表

微信小程序

QQ小程序

关于作者

AgentScope-Java v2.0 版本 ReActAgent vs HarnessAgent 差异解析与场景选择

一、本质定位

二、架构层面三大核心差异

2.1 能力是「叠加」而非「改写」

2.2 三个共享对象实现能力解耦

2.3 Middleware 注册顺序

三、能力对比清单

四、状态管理差异

五、Maven 依赖差异

六、典型代码对比

ReActAgent — 轻量单次调用

HarnessAgent — 生产级多轮对话

七、场景选择指南

适合 ReActAgent 的场景

适合 HarnessAgent 的场景

八、决策流程图

九、总结

参考资料

相关文章

评论

评论列表

微信小程序

QQ小程序

关于作者