AgentScope Java · 中文源码精读教程

AgentScope Java · 中文源码精读教程

双子星:一颗是 5459 行的纯内核 ReActAgent,一颗是 2989 行的工程层 HarnessAgent——对照拆解一个 57 万行的企业级 Java Agent 框架

这本教程讲什么

这是一份带读源码的 AgentScope Java 2.0 精读教程。

AgentScope Java 是阿里巴巴开源的生产级分布式企业 Agent 框架(Apache-2.0,JDK 17+,Maven 多模块,版本 2.0.x,2026-07 GA)。它的定位是"为构建分布式、企业级 Agent 提供基本抽象,随模型能力进化,并内置对长时间运行、安全可控的 Agent 执行的支持"。体量约 57 万行 Java:内核(core 11.7 万)+ 工程层(harness 8.6 万)+ 平台(service 3.1 万含 Go 控制面)+ 扩展生态(extensions 27.3 万,21 类扩展 + 11 个 Spring Boot starter)+ 50 个教学示例与 3 个完整应用。

这个框架最独特的结构是双子星:

💡 内核星:ReActAgent(agentscope-core 的单巨类,5459 行)——纯推理-行动循环:Reactor 反应式全栈、流式事件发射、HITL 暂停/恢复、failover、中断与优雅停机,全部浓缩在一个类里。它不依赖任何基础设施,是"裸 Agent"的完整实现。

💡 工程星:HarnessAgent(agentscope-harness,2989 行 + 20 个工程包)——在内核之上叠加生产所需的工程能力:Workspace 工作区、沙箱(本地/Docker/K8s/E2B)、技能自进化、子 Agent 与团队、消息网关(钉钉/飞书/企微/GitHub)、上下文压缩、定时协调。它是"裸 Agent"到"生产 Agent"的桥梁。

本教程采用双子星式:全书围绕这两颗星的对照展开——先深入解剖内核星(ReAct 循环/消息/事件/工具/模型/权限/中间件/状态),再进入工程星(沙箱/技能/多 Agent/网关),然后看环绕它们的扩展星云(21 类扩展+11 个 Spring starter),最后登上 Service 平台(Go 控制面+DAG Workflow)。每章讲清"这一能力在内核星怎么实现、工程星怎么加固"。

⚠️ 与官方文档的关系:官方 docs(v2/zh 约 115 篇)是高质量原生中文(非机翻),但偏 API 手册。本教程的差异化在源码剖析(ReActAgent 5459 行逐段拆解、Toolkit 1073 行、事件体系 35 文件)与企业落地主线。根目录 SKILL.md(31KB 框架编码避坑规则)会被融入各章"避坑"提示。

双子星架构图

十章双子星路径

第 1 章 AgentScope Java 全貌与双子星架构 ── 定位/57万行四层地图
第 2 章 内核星:ReActAgent 与推理-行动循环 ★ ── 5459行解剖/反应式
第 3 章 消息与内容块 ── Msg/ContentBlock 多模态体系
第 4 章 事件系统 ★ ── 31 种类型化事件/流式三段式
第 5 章 工具体系 ── @Tool 注解/Toolkit/MCP 三传输
第 6 章 权限与中间件 ★ ── 五模式三态决策/五切点洋葱
第 7 章 状态检查点与记忆 ── AgentStateStore/零停机恢复
第 8 章 工程星:HarnessAgent ── 沙箱/技能/网关
第 9 章 多 Agent 与扩展星云 ── 子Agent/Team/11个starter
第 10 章 Service 平台与全书回顾 ── Go控制面/DAG/完整应用
​

第 2、4、6 章是内核星的三个高点(★)。

章节目录

第 1 章 AgentScope Java 全貌与双子星架构
AgentScope Java 是什么(阿里/JDK17+/2.0.x GA/生产级分布式);2.0 三大主题(Harness 工程化/分布式部署/核心抽象升级);四层地图(core 11.7万/harness 8.6万/service 3.1万含 Go/extensions 27.3万);双子星架构总览(ReActAgent vs HarnessAgent);50 示例+3 完整应用;README_zh 高质量中文与 Hello 示例;配 landscape 全景图。

第 2 章 内核星:ReActAgent 与推理-行动循环 ★(全书高潮)
ReActAgent.java 5459 行逐段解剖(框架心脏);Reactor 全面反应式(Mono/Flux,call 与 streamEvents 共享执行核心);ReAct 循环(推理→行动→观察);流式事件发射;HITL 暂停/恢复(RequireUserConfirm 事件挂起循环等用户确认);failover 与重试;中断与优雅停机(shutdown 包 10 文件);RuntimeContext(sessionId/userId/typed attributes 多租户键)。

第 3 章 消息与内容块
message 包(23 文件);Msg 与四种角色(MsgRole);ContentBlock 多模态体系(TextBlock/ThinkingBlock 思考链/ToolUseBlock/ToolResultBlock/ImageBlock/AudioBlock/VideoBlock/DataBlock/HintBlock + Source Base64/URL);结构化输出(formatter/JsonSchema/ResponseFormat + StructuredOutputReminder);与 OpenAI/Anthropic 消息格式的映射。

第 4 章 事件系统 ★(全书高潮)
event 包 35 文件;31 种类型化事件(Agent 生命周期/ModelCall/Text/Thinking/DataBlock 的 Start-Delta-End 三段式/ToolCall/ToolResult/RequireUserConfirm HITL/RequireExternalExecution/CustomEvent/HintBlock/SubagentExposed/ExceedMaxIters);流式三段式协议(Start→Delta→End 支持前端实时渲染);事件流与 HITL 的统一;streaming 示例群;accumulator 流式累积器(Text/Thinking/ToolCalls)。

第 5 章 工具体系
tool 包 38 文件+5 子包;@Tool/@ToolParam 注解(ReflectiveFunctionTool 反射实现);ToolSchemaGenerator(方法签名自动生成 JSON Schema,victools);Toolkit 1073 行(registerTool/ToolGroup/MCP 客户端管理/流式 emitter);ToolGroupManager 元工具自主激活(LLM 自己决定激活哪组工具);ToolSuspendException(工具执行中挂起);MCP 子包(StdIO/SSE/Streamable HTTP 三传输);内置工具(file/coding/subagent 的 agent_spawn/agent_send/builtin)。

第 6 章 权限与中间件 ★(全书高潮)
权限系统:PermissionEngine/PermissionRule/PermissionDecision 三态(allow/require approval/deny);PermissionMode 五模式(DEFAULT/ACCEPT_EDITS/EXPLORE/BYPASS/DONT_ASK);敏感操作强制 HITL;中间件 AOP:MiddlewareBase/MiddlewareChain 五切点(onAgent/onReasoning/onActing/onModelCall/onSystemPrompt)洋葱式+Transformer 式;v1 hook 21 类与 LegacyHookDispatcher(v1→v2 演进史);OtelTracingMiddleware 观测。

第 7 章 状态检查点与记忆
state 包 16 文件;Session/检查点(AgentState/AgentStateStore/VersionedState);内存/JSON 存储 + extensions 的 MySQL/Redis/PG/OSS/COS;ConflictPolicy 与 ConcurrentSessionModificationException(并发会话修改);滚动发布零停机(检查点恢复长任务);memory 包(Memory/InMemoryMemory/StateBackedMemory/LongTermMemory);上下文压缩 compaction;记忆分层。

第 8 章 工程星:HarnessAgent
HarnessAgent 2989 行(工程层叠加);DistributedStore/IsolationScope;Workspace 工作区(本地/远端共享/沙箱可插拔);沙箱体系(22+docker+snapshot 文件:本地/Docker/K8s/E2B/Daytona/AgentRun + 快照);技能自进化(SkillBox/DynamicSkillMiddleware/curator 23 文件/Git/MySQL/PG 技能仓库);Gateway Channel(钉钉/飞书/企微/GitHub/GitLab 13 文件);coordination(PeriodicGate 定时唤醒);planmode。

第 9 章 多 Agent 与扩展星云
多 Agent 协作:Markdown 声明子 agent;agent_spawn/agent_send;SubagentEventBus;跨副本远程路由与恢复(subagent/protocol/task);Team(11 文件);扩展星云:extensions 27.3 万行 21 类(模型/RAG/沙箱/存储/通道/调度/训练);11 个 Spring Boot starter(core/a2a/admin/agui/chat-completions-web/dashscope/openai/anthropic/gemini/ollama/nacos)——Java 企业生态的杀手锏;SKILL.md 编码避坑规则精选。

第 10 章 Service 平台与全书回顾
AgentScope Service(控制面:service-common/gateway/dataplane/scheduler + Go 的 aistio + Vite/React 前端 + docker/helm);DAG Workflow(预览特性:agent/team/condition/join/approval/timer/signal/subrun 八种节点、无环校验、CEL 表达式数据映射、不可变 revision);控制台截图之旅(配 svc- 系列图);3 个完整应用(codingagent 9487 行类 Claude Code/dataagent 23387/paw 16806);全书回顾。

适合读者

• 用 Java 技术栈构建企业级 Agent 的后端工程师(尤其 Spring 背景)
• 想学习"反应式全栈(Mono/Flux)设计大型框架"的 Java 架构师
• 研究 HITL 人机协同、权限门禁、检查点恢复的 Agent 工程师
• 对多 Agent 编排(子 Agent/Team/DAG)与生产部署(分布式/多租户)感兴趣的团队

前置知识:Java 17+(能读接口/泛型/注解/Optional);反应式编程基础(Mono/Flux 概念,第 2 章会补);Agent 基本概念(ReAct/tool calling);可选:Spring Boot(第 9 章 starter)。

注意事项

• 双子星主线:每章标注属于内核星/工程星/星云/平台哪一层
• 源码带行号引用如 ReActAgent.java:1234、Toolkit.java:1073
• > 💡 **双星要点**:... 标注每节精华
• > ⚠️ **注意**:... 融入 SKILL.md 的官方避坑规则(禁 .block()/ThreadLocal 等)

⚠️ 重要说明:官方 v2/zh 文档(115 篇原生中文)是使用层最佳参考,本教程聚焦源码剖析与企业落地,两者互补。DAG Workflow 是预览特性,API 可能变化。

关于源码版本

对照源码来自 agentscope-java-main(Apache-2.0,阿里巴巴),版本 2.0.3-SNAPSHOT(GA 2.0.1,2026-09 快照)。模块:core(499 文件 11.7 万行)/harness(414 文件 8.6 万)/service(209 文件 3.1 万)/extensions(1201 文件 27.3 万)/examples(359 文件 6.3 万);测试类 802 个。文档 docs/ 约 470 个 md(v1/v2 中英双版本)。