第 1 章 · 01 AgentScope Java 定位与 2.0 三大主题

第 1 章 · 01 AgentScope Java 定位与 2.0 三大主题

本节摘要：本节回答"AgentScope Java 是什么、凭什么值得精读"。它是阿里巴巴开源的生产级分布式企业 Agent 框架（Apache-2.0，JDK 17+，Maven 多模块，2.0.0 GA 于 2026-07 发布，文档站 java.agentscope.io），定位是"面向企业级、分布式、生产环境的智能体框架"。README_zh 用三大主题概括 2.0 的跃迁：Harness 工程化、企业级分布式部署、底层核心抽象升级。本节逐条拆解这三大主题，并跑通 README 里的第一个 Hello 示例。

内容来源：原项目源码 README_zh.md、pom.xml 与 docs/v2/zh/ 官方原生中文文档。

⚠️ 注意：本教程对照源码为 2.0.3-SNAPSHOT（2026-09 快照，GA 版本 2.0.1），个别行号与接口在后续版本可能微调；阅读时以类名/方法名定位为准，不要死记行号。

学习目标

阅读完本节，你应当能够：

1. 说清 AgentScope Java 的定位：阿里出品、JDK 17+、Apache-2.0、2.0.x GA、生产级分布式企业 Agent 框架。
2. 复述 2.0 三大主题：Harness 工程化、企业级分布式部署、核心抽象升级。
3. 解释"裸 ReAct 循环"与"Harness 工程底座"的分工。
4. 理解它与 Python 版 agentscope 的同源关系与差异。
5. 跑通 README_zh 的 Hello 示例，区分 call() 与 streamEvents() 两种消费模式。

一、定位：生产级分布式企业 Agent 框架

README_zh.md 开篇一句话给出身份：

"AgentScope Java 2.0 是面向企业级、分布式、生产环境的智能体框架，提供与模型能力相匹配的核心 Harness 抽象，可支持长期、稳定、安全可控的智能体任务执行。"

这句话里的四个关键词，每个都对应可验证的工程事实：

基础参数：Apache-2.0 协议、JDK 17+（README 明示"需要 JDK 17 及以上版本"）、Maven 多模块（io.agentscope groupId 发布到 Maven Central）、版本线 2.0.x。根 pom.xml 聚合了 agentscope-core、agentscope-harness、agentscope-service、agentscope-extensions、agentscope-examples 等模块，合计约 57 万行 Java。

版本时间线（README 新闻区）能看出 2.0 的打磨节奏，每条都对应本教程的一章：

注意"RC2：Agent 完全无状态改造"与"RC3：共享执行核心"两条——它们是第 2 章两大主题（多会话并发、一次实现两种消费）的版本化石，说明这不是设计稿上的漂亮话，而是真实演进出来的能力。

与 Python 版 agentscope 的关系：同属 agentscope-ai 组织（GitHub agentscope-ai/agentscope-java），共享品牌与核心理念（消息驱动的多 Agent 系统），但 Java 版不是移植——它以 Project Reactor 反应式全栈重新实现，并率先落地了 2.0 的 Harness/权限/事件流抽象。Python 版是"构建一个智能体的工具箱"，Java 版 2.0 明确转向"面向生产环境运行智能体的完整平台"（README_zh"核心设计"一节原话）。对 Java 团队还有一层实际意义：它与 Spring 生态原生兼容（11 个 Spring Boot starter，第 9 章），可以像引入一个普通中间件那样把 Agent 能力嵌进既有企业系统。

一个容易忽略的宝藏：README_zh.md 与 docs/v2/zh/（约 115 篇）都是原生中文（非机翻），质量极高，是 API 层面的最佳参考；本教程的差异化在源码剖析与企业落地主线。

二、2.0 三大主题逐条拆解

README_zh"核心设计"一节把 2.0 的升级组织为三大主题，这也是全书章节地图的骨架。

主题一：Harness 工程化——长期运行、复杂任务的工程底座

README_zh 的原话是理解双子星架构的钥匙："裸的 ReAct 循环只解决'一次推理'。HarnessAgent 在 ReActAgent 之上通过 Middleware 与 Toolkit 叠加工程基础设施，核心推理循环原样保留，能力按需叠加"。叠加的内容包括：

• 自进化与技能仓库：成功模式自动沉淀为 Markdown 技能，跨会话共享、按需加载。
• 分层记忆：上下文对话 + agent 自维护的 MEMORY.md + 磁盘事实流水账，自动压缩控制 prompt 体量。
• 子智能体：Markdown 声明子 agent 规格，agent_spawn / agent_send 按需启动。
• 上下文自动管理：结构化压缩保留目标/状态/关键发现/下一步；超大工具结果落盘只留占位符。
• Plan Mode：只读规划态编排长任务，计划文件持久化并驱动执行。

注意"核心推理循环原样保留"九个字——工程星不重写内核星，这是第 8 章精读 HarnessAgent 时反复验证的事实。

主题二：企业级分布式部署

"生产环境的智能体要服务多租户、安全执行不可信代码、滚动发布不丢上下文"，对应四组能力：

1. 多租户隔离：RuntimeContext 的 (userId, sessionId) 键贯穿工作区、KV 命名空间、沙箱状态槽。
2. 安全沙箱：本地子进程 / Docker / Kubernetes / E2B 云沙箱任选，支持快照恢复。
3. 权限管控：三态决策（允许/审批/拒绝），敏感操作强制 HITL 审批。
4. 会话恢复：AgentStateStore（内存/JSON 文件/MySQL/Redis/PostgreSQL）支撑零停机滚动发布。

主题三：核心抽象升级——更轻、更正交

"消息、事件、扩展机制更小、更正交；HITL 与事件流式是框架运行的一部分，不是外挂层"：

• 事件流：31 种类型化事件，模型调用、文本增量、工具执行、用户确认全部实时流出。
• 消息模型：文本/文件/图片/音视频/工具结果统一收敛到 ContentBlock，按 role 严格校验。
• Middleware：onAgent/onReasoning/onActing/onModelCall/onSystemPrompt 五阶段取代 v1 扁平 hook。
• HITL 一等公民：确认工具参数、审批敏感操作、交给外部系统执行，智能体在暂停点精确恢复。

💡 双星要点：三大主题其实就是"内核星怎么变纯（主题三）、工程星怎么变厚（主题一）、两颗星怎么协作着上生产（主题二）"。全书每讲一个能力，都会回到这条主线：它在 core 里是一个纯抽象，在 harness 里是一次工程加固。

三、Hello 示例：两行入口看清架构

README_zh 的快速开始示例（节选）：

// README_zh.md「Hello AgentScope!」
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;

HarnessAgent agent = HarnessAgent.builder()
        .name("assistant")
        .sysPrompt("你是一个有用的 AI 助手。")
        .model("dashscope:qwen-plus")   // ModelRegistry 按字符串解析，自动读环境变量
        .workspace(Paths.get(".agentscope/workspace"))
        .build();

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

// 阻塞式调用
agent.call(new UserMessage("你好！"), ctx).block();

// 或者流式获取事件，用于实时 UI 渲染
agent.streamEvents(new UserMessage("帮我把今天的关键点列三条。"), ctx)
        .doOnNext(event -> { /* 按 event.getType() 分发 */ })
        .blockLast();
​

这个 30 行的示例浓缩了全书要拆的四件事：

1. Builder 模式是框架的统一构造入口：模型可以用字符串 id（ModelRegistry 解析并自动读 DASHSCOPE_API_KEY 等环境变量），也可以传入显式 ChatModel。模型字符串支持 "openai:gpt-4.1"、"deepseek:deepseek-v4-flash"、"dashscope:qwen-plus"、"anthropic:claude-sonnet-4-7"、"ollama:llama3" 等——换厂商只改一个字符串。
2. call() 与 streamEvents() 是同一执行核心的两个消费入口——前者阻塞等最终 Msg（.block() 只允许出现在 main()/测试里），后者流式消费 AgentEvent，switch (event.getType()) 按类型分发：TEXT_BLOCK_DELTA 打印文本增量、TOOL_CALL_START 显示工具调用。这是第 2 章的重点。
3. RuntimeContext 携带 (userId, sessionId) 多租户键，是分布式部署的最小单元；.workspace(Paths.get(...)) 则是工程星的工作区目录（第 8 章）。
4. 示例用的是 HarnessAgent；README 同时注明"只想跑裸 ReActAgent（不需要工作区/持久化/沙箱），单独依赖 agentscope-core 即可"——双子星从依赖关系上就是可分的。

依赖侧：2.0 把模型提供商拆成了独立扩展模块（agentscope-extensions-model-dashscope 等），核心包不捆绑任何厂商 SDK。Maven 坐标：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
</dependency>
<!-- 再按需加一个模型扩展，如 agentscope-extensions-model-dashscope -->
​

上图是官方 landscape 全景图：左侧是模型与工具生态，中间是 ReAct 循环与消息/事件/权限核心抽象，右侧是 Workspace/沙箱/多 Agent 编排的 Harness 层，底层是分布式 session 与状态存储。第 2 章起我们就钻进中间那颗最亮的星。

本节要点回顾

1. AgentScope Java：阿里开源、Apache-2.0、JDK 17+、Maven 多模块、2.0.x GA（2026-07）、约 57 万行，定位"生产级分布式企业 Agent 框架"。
2. 与 Python 版同源不同实现：Java 版以 Reactor 反应式全栈重写，并率先落地 2.0 抽象。
3. 三大主题：Harness 工程化（裸循环只解决一次推理，工程能力按需叠加）、分布式部署（多租户/沙箱/权限/会话恢复）、核心抽象升级（31 种事件、ContentBlock、五阶段 Middleware、HITL 一等公民）。
4. Hello 示例四要素：Builder 构造、call()/streamEvents() 双入口、RuntimeContext 多租户键、core 与 harness 依赖可分。
5. README_zh.md 与 docs/v2/zh/ 是原生中文高质量参考，本教程专注源码剖析，两者互补。

下一节，我们给 57 万行代码画一张四层体量地图（core 11.7 万 / harness 8.6 万 / service 3.1 万 / extensions 27.3 万行），并正式引出贯穿全书的双子星：5459 行的 ReActAgent 对照 2989 行 + 20 工程包的 HarnessAgent。