AgentScope Java 2.0 的核心思路，是基于 ReActAgent 推理内核基础上，增加 Harness 工程化层。开发者既可以继续使用轻量的 ReAct 循环，也可以按需启用 Workspace、持久记忆、Session、Sandbox、Skill 和 Subagent 等能力，将同一套 Agent 逻辑落地部署到企业级分布式服务中。

AgentScope Java 2.0 GA 版本已经正式发布：

• 文档：https://java.agentscope.io
• GitHub：https://github.com/agentscope-ai/agentscope-java
• Release Notes：https://github.com/agentscope-ai/agentscope-java/releases/tag/v2.0.0

AgentScope2.0 介绍

AgentScope 框架推出已经有两年的时间了，agentscope在上半年发布了 2.0 版本，2.0 版本主要的一个核心能力，就是把 Harness 整套方案内置到了框架里面。这也意味着agentscope面向的场景，主要是企业级的分布式智能体这样一个场景。

本文主要从三部分来给大家介绍。第一部分是大家都关心的 2.0 主要有哪些核心能力。有一些开发者包括企业内已经非常重度地用 AgentScope 1.0 构建了很多生产级的应用和智能体，这套设计理念的差异和怎么迁移，会简单介绍一下。中间一大部分是介绍整个 Harness 的核心设计和到底有哪些能力。最后是几个示例，agentscope来看一下它能做真正企业级的事情。

先从全景图开始。大家可以直观地把 AgentScope 理解为一个框架，也就是图中蓝色的这一部分。作为一个框架，agentscope现在有 Python、Java 和 TypeScript 三个语言实现，Go 语言的实现也在开发当中，所以整个框架已经基本涵盖了所有主流的语言实现。

框架这一层更多定义的是 Agent 怎么开发、怎么定义。比如中间就是整个 Agent Loop 的循环，里面的 Reasoning、Tool Call 都有非常好的设计，这些实现大家不需要去关心。包括里面的 Model，以及整个 Event、Message 的传递，这些都是内置的。

在 2.0 里agentscope加了 Workspace 这样一个非常核心的抽象，同时也做了更多上下文管理的事情。这就是中间蓝色部分的框架。

往外延伸的，是agentscope围绕 Agent 的构建过程做的很多生态适配。比如模型这一侧，左边这部分就是国内的 DeepSeek、OpenAI 兼容的这些模型，还有 Qwen 模型，都是支持的。

观测这一块，整个框架现在有默认的 OpenTelemetry 埋点，所以观测数据可以上报到任何兼容 OpenTelemetry 的平台，比如开源的 LangFuse，或者阿里云上的产品 —— 以前微服务时代叫 ARMS，现在有一款专门针对 Agent 时代的 AgenLoop 的产品，都是可以接进去的。

然后是 Higress，前面讲 Agent Teams 的时候提到过，不论是模型的代理还是 MCP 的代理，包括用 Nacos 做 Skill 或者 MCP 市场的管理，整个 Agent 生态都已经完整对接了。

再往上，QwenPaw 和 AgentTeams 都是agentscope基于这个框架生态衍生出来的具体产品和企业级的 Agent 管理能力。

ReactAgent 内核与核心组件

看完大图，agentscope回到 AgentScope 框架本身。整个 2.0 对底层来说是不变的，也就是 ReAct Agent 这套核心的推理和工具之间的循环，这个没有变。

这里列了几个核心能力，和 1.0 区别不太大，底层能力这一层是没变的，顶多是做了一些设计上的优化。或者看下面加了一个 Permission，就是工具调用权限这块额外的设计，因为以前是没有工具权限管控能力的。

中间还有个 Middleware 中间件，这个和以前的 Hook 是对等的，只不过在新版本中agentscope对整个事件的传递和中间的介入做了一些优化。所以整体看起来，Model、Tool 定义、中间的上下文（上下文这块对应的就是agentscope以前产生的内容），整体来说是差不多的，就是整个 ReActAgent 这一块。

模块	核心内容
Agent 智能体	ReAct 推理 - 行动循环引擎；多用户 / 多会话并发安全；流式事件 & 结构化输出；中断 / 恢复 & 人机交互
Model 模型层	Credential + ChatModel 两层架构；5 大厂商：DashScope / OpenAI / Anthropic / Gemini / Ollama；Streaming & Thinking & 多模态；可扩展自定义 Provider
Tool 工具系统	@Tool 注解 / ToolBase 继承；MCP 协议集成（STDIO / SSE / HTTP）；Skill 热加载 Markdown 指令集；Tool Group 按需激活 / 自管理
Context 上下文	无状态引擎 + AgentState 持久化；RuntimeContext per-call 元数据；Redis / MySQL 分布式状态共享；跨节点故障转移 & 会话恢复
Middleware 中间件	5 个生命周期 Hook 位置；洋葱式 (Onion) 变换式 (Transformer)；OpenTelemetry 全链路追踪；限速 / 回退 / 动态 Prompt
Permission 权限	Rules + Mode + Built-In Checks；5 种模式：DEFAULT / EXPLORE / BYPASS / ACCEPT_EDITS / DONT_ASK；建议规则自动生成 & 持久化；危险路径不可绕过保护
Message & Event	Msg 类型内容块体系；AgentEvent 流式增量传输；Start → Delta → End 生命周期；SSE 推送 & 断点重建消息

AgentScope Harness 核心设计与功能详解

接下来讲今天比较重要的一部分，就是 AgentScope 整套 Harness 的设计。agentscope先看整个 Harness 在 AgentScope 上的总体架构。

总体架构

快速体验

这里用一个 Java 版本的示例来讲。AgentScope Java 里如果要用 Harness 这一层怎么用？

第一，你要加一个依赖。因为agentscope在 ReActAgent 上面又加了一层，你要把这一层的依赖加进来。

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>${agentscope.version}</version>
</dependency>

其次是开发的入口。ReActAgent 的 API 入口还在，但现在多了一层新的 API 入口，叫 HarnessAgent。你可以直接用它构建一个 Agent—— 它底层还是用的 ReActAgent，但在 API 的感知上你可以直接使用 HarnessAgent。

agentscope可以看它们中间的差异：前面是一样的 ——Name、System、Model；下面你可以看到它有了 Workspace 的概念，可以指定它的 Workspace，可以指定一些压缩策略，还有更多的配置，包括 Sandbox 隔离的配置，都可以在这一层直接用 API 来做。

下面的区别就是调用的时候需要前面提到的 Context 上下文。这里定义了一个 RuntimeContext，接下来调用时主要是传递 User 和多租户隔离的一些信息。

public class FirstAgent {
    public static void main(String[] args) {
        HarnessAgent agent = HarnessAgent.builder()
                .name("note-taker")
                .sysPrompt("你是一个帮助用户做笔记的助手。")
                // 字符串形式由 ModelRegistry 解析 — 自动读取 DASHSCOPE_API_KEY;
                // 切换其他厂商时改用 "openai:gpt-5.5"、"anthropic:claude-sonnet-4-5"、
                // "gemini:gemini-2.0-flash" 或 "ollama:llama3"。
                .model("dashscope:qwen-plus")
                .workspace(Paths.get(".agentscope/workspace"))
                .compaction(CompactionConfig.builder()
                        .triggerMessages(30)
                        .keepMessages(10)
                        .build())
                .build();

        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId("demo-session")
                .userId("alice")
                .build();

        // 第一轮: 自我介绍 + 当天的事
        agent.call(new UserMessage("我叫agentscope，今天准备一个关于 AgentScope的技术分享。"), ctx).block();

        // 第二轮: 同 sessionId，自动恢复上一轮状态后回答
        agent.call(new UserMessage("我叫什么？我今天要干什么？"), ctx).block();
    }
}

AgentScope 2.0 支持全局单例模式 HarnessAgent 或者 ReActAgent 承载所有不同用户请求，所以每个请求必须通过 RuntimeContext 进行状态隔离。如果保持 1.x 版本每个请求生成一个 ReActAgent 实例的用法也没有问题。

Workspace-- 智能体进化的 Source of Truth

Workspace 是现在主流的 Agent—— 不论是 Agent 产品还是 Agent 框架 —— 的一个核心设计。agentscope可以把它理解为一个逻辑概念。它里面有哪些资产呢？

第一部分是偏静态的资产，就是 Agent 定义相关的，比如 AGENTS.md、Skills 或者 Sub-Agent，相当于定义了我这个面向业务的 Agent 里都有哪些东西。这是我定义的、会随着我的镜像打包走的，叫静态资产。

还有一部分是运行时的数据。这部分数据是 Agent 在运行过程中自己产生的，是用户和它交互沉淀下来的 —— 不论是一些实时的 Session 状态记录、Task 任务状态等信息，还是 MEMORY.md 这种沉淀下来的记忆。所有这些静态的或运行时的资产都沉淀在 Workspace 里。这就是 Workspace 的核心概念。

抽象文件系统 - Workspace 的物理载体

并且在 AgentScope 中，对 Workspace 做了更细粒度的处理。比如一个 Agent 有一个 Workspace，但一个 Agent 会被很多用户使用。对于不同的用户，在这一个 Workspace 里做了逻辑上的多租户隔离 —— 可以是用户维度的隔离、Session 维度的隔离，或者是 Agent 维度的。这是不同的隔离维度。

在底层，说 Workspace 是一个逻辑概念，那它的物理存储是什么呢？最直观的理解一定是磁盘，这是最直接的。但磁盘有一个问题：比如 On-premise 场景它就只能在你本地的磁盘上，这就是 Workspace 绑定磁盘的限制。

为了解决这个问题 —— 尤其面向的是企业级分布式场景 —— 把 Workspace 的上层逻辑实现往底层物理实现走的时候抽象了一个接口，就是中间黑色的部分，叫做 Abstract File System，一个抽象的文件系统接口。

Agent 操作 Workspace 时，物理层面使用的就是这个抽象文件系统接口。agentscope为它提供了默认的三种实现，当然你也可以任意拓展：

1. 第一种是左边的本地 On-premise，装在本机，直接操作的是磁盘。如果你要做用户的隔离，就是树形文件系统，一个树状的结构。
2. 在生产环境部署时，因为一个 Agent 要多实例部署，每个实例都要看到同一个 Workspace，这时你可以把抽象文件系统接口接到数据库比如 MySQL 或者 Redis，或者是阿里云的 OSS。这就实现了 Workspace 的共享 —— 同一个 Workspace 实例能够被不同的 Agent 实例看到。
3. 如果你对 Workspace 的隔离有更高的要求 —— 比如工具的执行（工具执行也是在 Workspace 的空间里进行的），你可以把它接到 Sandbox。一个 Workspace 映射一个 Sandbox，这时只要做好 Sandbox 的生命周期管理，就可以实现多租户隔离了。

这就是 Harness 中 Workspace 的逻辑概念和物理存储实现，这样也就支持了分布式的场景。

内置上下文压缩策略 - 四道防线

在 Workspace 里怎么管理所有的上下文呢？第一，内置提供了一些压缩策略。Agent 在一个会话运行的过程中，模型是有上下文窗口限制的，怎么保证上下文在这个限制之内呢？

这里提供了几种压缩策略，图中只展示了其中一部分，实际还有更多详细的配置。比如工具执行的结果大于多少之后，agentscope有截取加落盘的实现 —— 落盘以后给到文件引用的路径；工具入参过大时，也有一些字数上的截断策略，这些都是基本的措施；还包括对过往消息进行压缩、保留最近几条，这些都是大家熟悉的常规压缩策略。

在压缩的过程中，还是有一些注意事项的。最典型的就是：压缩的时候尽量不能丢信息。哪些信息是尽量不能丢的呢？

比如整个任务执行的规划 —— 有些复杂任务是要做规划的，这个规划可能在你消息的前几条，如果不做特殊处理直接压缩，规划就丢掉了。

还有基于这个规划agentscope可能拉起了一些子 Agent，有些子 Agent 是异步的，或者任务是异步的。异步的情况下任务很可能还没有返回，要持续地追踪任务状态。这时如果直接粗暴地压缩，这个子 Agent 的状态可能就丢掉了。

因此，像这种需要在全局进行更新的状态 —— 不论是规划的详情、子 Agent 的异步任务状态、我的清单，还是各种工具的权限授权记录 —— 这些信息都要保证不被压缩。所以这两部分内容要进行区别处理。

双层长期记忆 - 事实自动沉淀

还有一个是长期记忆的沉淀。前面讲的压缩瞬时状态—是运行当中瞬时状态的管理和控制。做压缩的时候必然会丢掉一些信息，这些信息可以把它沉淀为长期记忆。

框架里的策略：在会话压缩以前，可以做一次 Flush 分拣。第一层是记到每天专属的一个文件里，这个结构其实和 QwenPaw 是差不多的，可以记录进去。

同时agentscope还有一个后台任务，它会定期回去扫描当天的、整个 Memory 下沉的记忆，把它蒸馏为全局的 MEMORY.md。这个 MEMORY.md 在每次请求进来的时候都会全局加载到你的 System Prompt 里，所以它的大小和里面数据的质量就非常重要。

所有这些环节 —— 不论是做每日流水的 Memory 提取，还是定时蒸馏 MEMORY.md，还是做压缩 —— 里面的 Prompt 提示词都是可以定制的，方便大家在不同场景引导做更优化的提取和记忆。

子智能体编排、委派、并行、异步通知

主 Agent 通过 agent_spawn / agent_send 拉起子 Agent，支持四类子 Agent：

1. 同步子 agent：timeout > 0，阻塞等结果、流式转发
2. 后台任务：timeout = 0，返回 task-id・反向通知
3. 远程子 agent：url + headers，Agent Protocol HTTP
4. 暴露给用户：expose_to_user=true，用户可直接连子 agent

▲ system-reminder 自动反向注入

关键能力：

• ISOLATED / SHARED workspace
• 流式事件携带 source 路径
• persistSession 复用实例
• 递归 3 层硬上限
• DENY 权限自动继承
• Plan Mode 自动只读

Harness 当中还有一个非常重要的点，是关于智能体的编排。这张图要表达的是：主 Agent 直接指导所有的子 Agent。

一个任务进到主 Agent 以后，agentscope内置了 Agent Spawn、Agent Send 等工具，主 Agent 会根据需求来拉起子 Agent。拉起的子 Agent 首先有两种类型：一种是同步的子 Agent，一种是异步的子 Agent。异步的子 Agent 适用于处理时间比较长的任务，并且现在agentscope支持它在完成以后，主动把结果通知回主 Agent。

还有一种特殊类型是远程的子 Agent，这种模式现在也是支持的，可以拉起一个远端的子 Agent。同时agentscope给主 Agent 配套了一个叫 Task List 的 Toolkit，覆盖了所有的配套工具。主 Agent 可以主动去看有哪些子 Agent、每个子 Agent 处于什么状态，这些都有配套的工具。

还有一点值得一提，也是很多企业用户的核心诉求：通常来说用户直接对话的是主 Agent，主 Agent 拉起所有子 Agent 是它自己的事情，它管理子 Agent 是为了完成自己的任务。但实际上有很多用户（包括agentscope用 Claude Code 的时候也是），会希望直接切到主 Agent 拉起的某个子 Agent，和这个子 Agent 对话，来引导它完成自己的子任务。

同样在 AgentScope 中agentscope也支持你直接和子 Agent 进行对话。虽然这个子 Agent 是主 Agent 拉起来的，但有一种方式可以把它暴露出来，让你直接和它对话。

子 Agent 的整套设计还有一些细节：比如主 Agent 和子 Agent 之间的上下文是不是共享的；包括子 Agent 的事件怎么通过主 Agent 透传出来、怎么区分是哪个子 Agent 的还是主 Agent 的（因为大家的事件流都混在一起），agentscope都是有标记的。

然后是权限问题 —— 主 Agent 拉起子 Agent 以后，子 Agent 的权限是什么、是不是继承主 Agent 的权限，这些比较细节的事情，在整个框架里都有一套机制存在。

沙箱管理：隔离、恢复与分布式

把危险操作关进容器，把安装状态快速快照

1. 执行边界

   文件与 shell 命令都在隔离容器内执行，宿主机完全不参与

2. 跨调用恢复

   pip install /npm install 临时文件快照保留，下次 call 无需重装

3. 多副本可用

   通过分布式 store + 远端快照，任意节点都能 resume 出同一份工作区

call () 生命周期 → 沙箱决策：

• 有 → 复用（快照留存）
• 无容器 有快照 → 恢复（快速重建）
• 都没有 → 冷启动（WorkspaceSpec 全新初始化）

可选后端：Local、Redis、OSS/S3 多副本；底层矩阵：Docker・Kubernetes・Daytona・E2B・AgentRun

沙箱主要解决 Agent 执行的安全问题，是其中非常重要的一环。Agent 工具执行的过程中，agentscope可以把工具执行放在沙箱里，整个框架里有一套沙箱生命周期的管理系统。这里就不展开了，感兴趣的可以进一步查阅官方文档。

Skills：四层注册中心 & 沙箱内执行

关于 Skill 有两部分可以讲一下。

第一部分是 Skill 的管理。AgentScope Harness 对于 Skill 管理，对接了类似 Nacos 这种中心化的 Skill 管理系统，可以自动地把中心化管理的 Skill 加载到本地进行识别和使用。同时基于前面讲的 Workspace 细粒度管理机制，你也可以实现不同用户之间 Skill 的隔离使用 —— 我这个用户有自己的 Skill，另一个用户有另外的 Skill，互相是看不到的。

另一部分是 Skill 的执行。Skill 有时不只是简单的流程，里面还有配套的脚本和一些资源文件，这时它的执行就要受到安全管控。agentscope现在支持把整个 Skill 投影到 Sandbox 中，让 Skill 的所有脚本都能在 Sandbox 里闭环执行。

计划模式：想清楚 -> 写下来 -> 再动手

只读思考阶段 + 计划文件 +HTL 退出

工作流（明确固化四步：设计 →写计划 →人确认 →执行）

用户请求 → plan_enter → 只读调查 → plan_write(PLAN.md) → plan_exit → HITL确认 →执行阶段工具解禁

Plan 阶段白名单

• 只读文件工具：read_file、grep_files、glob_files、list_files
• 内存查询工具：memory_search、memory_get、session_search
• Plan 三件套：plan_enter、plan_write、plan_exit
• 任务清单：todo_write
• Shell（可选）：.allowShellInPlanMode() 后开放为用途

四种终态（isPlanModeActive）

1. 未进入：模型直接 build，任务与 workspace 不匹配
2. 进入 plan_exit：成功；规划完→获批→build 模式
3. 有 - plan 无 PLAN：已起草但未退出，后续消息可继续编辑
4. 仅 - plan 无 PLAN：只说不做；文本计划但没写出

Harness 里现在也支持计划模式。熟悉 1.0 的用户应该知道，agentscope在 1.0 中也有一套叫做 Plan 的计划模式 —— 给一个任务，先规划再执行。

1.0 的实现更偏向于一个内部管理的状态机，由一套状态机来运转和执行。在 2.0 中agentscope对整个 Plan 模式做了优化：首先内置了一整套 Plan 相关的配套工具，比如 PlanEnter、PlanExit 等等。

当用户请求进来的时候，你可以直接开启 Plan。如果大家熟悉 Coding Agent，可以直接理解为和 Coding Agent 的 Plan 模式一样 —— 比如在 Codex 或者 Claude Code 中你可以打开 Plan。agentscope用 AgentScope 开发的业务 Agent 也是一样的，前面有一个接口可以调，你告诉它要开启 Plan 模式，它就开启了，接下来你问它问题，它就会生成 Plan；后面切到 Agent 模式让它执行，它就基于之前的 Plan 直接往下执行。

或者你让它进入自主识别的模式，它可以根据你的任务自己切到 Plan 模式。因为这里每个工具（PlanEnter、PlanExit）都有 Permission 权限，它切到 Plan 模式的时候可能会先问你；Plan 执行完了，就像 Coding Agent 那样，它要切换回 Agent 模式时会弹出一个弹窗来问你。整个流程上是一样的，开发者可以在前端的 UI 上把这一套串起来。

Channel：消息平台 -> Gateway-> Agent

在一些企业的业务场景里，是有对接 Channel 平台的需求的 —— 要把后台运行的任务和企业内的即时通讯系统等对接起来。这块整个框架也提供了原生的支持。