Agent Scope Java 2.x 系列【42】2.0 GA 正式发布：从透明开发迈向智能体系统工程

文章目录

• [1. 核心设计概要](#1. 核心设计概要)
• • [1.1 双层 Agent 架构：解耦推理核心与工程能力](#1.1 双层 Agent 架构：解耦推理核心与工程能力)
  • [1.2 标准化消息与全生命周期事件流](#1.2 标准化消息与全生命周期事件流)
  • [1.3 三态权限管控系统（HITL 人工介入）](#1.3 三态权限管控系统（HITL 人工介入）)
  • [1.4 五阶段混合扩展中间件机制](#1.4 五阶段混合扩展中间件机制)
  • [1.5 智能化上下文工程优化](#1.5 智能化上下文工程优化)
  • [1.6 可插拔 Workspace 执行环境抽象](#1.6 可插拔 Workspace 执行环境抽象)
  • [1.7 全场景模型容错与多模型适配](#1.7 全场景模型容错与多模型适配)
  • [1.8 企业级分布式部署能力](#1.8 企业级分布式部署能力)
  • [1.9 标准化协议互通体系](#1.9 标准化协议互通体系)
  • [1.10 声明式多智能体编排与技能体系](#1.10 声明式多智能体编排与技能体系)
• [2. GA 版本增量更新（2.0.0-RC5 → 2.0.0 GA）](#2. GA 版本增量更新（2.0.0-RC5 → 2.0.0 GA）)
• • [2.1 ✨ 新增能力](#2.1 ✨ 新增能力)
  • [2.2 🛠 核心修复与优化](#2.2 🛠 核心修复与优化)
  • • [2.2.1 核心 Agent 能力](#2.2.1 核心 Agent 能力)
    • [2.2.2 模型适配层](#2.2.2 模型适配层)
    • [2.2.3 沙箱与工具执行](#2.2.3 沙箱与工具执行)
    • [2.2.4 通信与路由](#2.2.4 通信与路由)
• [3. 各 RC 版本完整迭代日志](#3. 各 RC 版本完整迭代日志)
• • 2.0.0-RC5（2026-07-07）
  • • [🔥 重大变更](#🔥 重大变更)
    • [✨ 新增能力](#✨ 新增能力)
    • [🛠 核心修复](#🛠 核心修复)
    • [📚 文档优化](#📚 文档优化)
  • 2.0.0-RC4（2026-06-18）
  • • [✨ 新增能力](#✨ 新增能力)
    • [🛠 核心修复](#🛠 核心修复)
    • [📚 文档修复](#📚 文档修复)
  • 2.0.0-RC3（2026-06-11）
  • • [✨ 新增能力](#✨ 新增能力)
    • [🔥 核心变更](#🔥 核心变更)
    • [🛠 关键修复](#🛠 关键修复)
  • 2.0.0-RC2（2026-06-09）
  • • [✨ 新增能力](#✨ 新增能力)
    • [🔥 重大架构变更](#🔥 重大架构变更)
    • [🛠 核心修复](#🛠 核心修复)
  • 2.0.0-RC1（2025-05-28）
• [4. 版本总结与升级建议](#4. 版本总结与升级建议)

1. 核心设计概要

发布版本 ：2.0.0 (GA 正式版)

发布日期 ：2026-07-10

AgentScope Java 2.0.0（General Availability）正式官宣发布！作为 1.x 到 2.0 迭代的首个正式版本，本次版本完成了框架架构级重构与工程化能力全面升级 ，标志着 AgentScope Java 彻底从「原型式透明开发」迈入「企业级智能体系统工程」新阶段，核心围绕让智能体稳定、可控、可落地完成复杂任务完成全链路能力升级。

AgentScope Java 2.0 摒弃 1.x 轻量化原型定位，聚焦企业级智能体落地痛点，重构底层架构、扩展工程化基础设施、完善可观测与管控能力，十大核心设计全面赋能生产级智能体搭建：

1.1 双层 Agent 架构：解耦推理核心与工程能力

创新性拆分双层智能体架构，兼顾推理纯粹性与工程扩展性，实现核心能力与拓展能力完全解耦：

• ReActAgent（无状态推理核心）：纯推理能力载体，标准化实现「推理 → 工具调用 → 结果回复」ReAct 循环。2.0 版本实现完全无状态改造 ，所有单次调用可变状态通过 Reactor Context 透传，单个 Agent 实例可安全并发服务多组 (userId, sessionId) 会话，大幅提升服务并发能力。

• HarnessAgent（工程化增强层）：基于 ReActAgent 内核扩展，通过 Middleware 中间件 + Toolkit 技能工具集 双扩展通道，叠加工作区、持久化记忆、安全沙箱、子智能体编排、计划模式等企业级基础设施，仅叠加、不替换核心推理逻辑，保证推理稳定性的同时，补齐生产落地能力。

1.2 标准化消息与全生命周期事件流

重构消息与事件体系，实现智能体执行全流程可观测、可交互、可干预：

• 统一 ContentBlock 消息模型：封装 TextBlock、DataBlock、ToolUseBlock、ToolResultBlock、HintBlock 等标准化消息单元，适配文本、多模态、工具调用、状态提示等全场景消息。

• 定义 28 种类型化 AgentEvent 事件流：通过 streamEvents() 对外暴露智能体全生命周期事件，支持文本增量输出、工具调用启停、用户审批确认、状态变更等实时推送，完美适配前端 UI 动态渲染、流程监控、人工干预等业务场景。

1.3 三态权限管控系统（HITL 人工介入）

全新自研 PermissionEngine 权限引擎 ，为工具调用构建「允许 / 人工审批 / 拒绝」三态决策机制。支持结合静态权限规则、工具类型、输入内容动态判定风险，敏感操作自动触发 HITL（Human-In-The-Loop）人工审批流程，彻底解决生产环境智能体高危操作不可控问题。

1.4 五阶段混合扩展中间件机制

创新「洋葱模型 + 管道模型」混合扩展架构，定义五大执行阶段钩子：onAgent / onReasoning / onActing / onModelCall / onSystemPrompt。在保障框架核心逻辑稳定不变的前提下，为日志链路追踪、安全校验、业务策略拦截、上下文动态注入、模型参数定制等场景提供灵活、有序、可插拔的扩展能力。

1.5 智能化上下文工程优化

针对性解决长会话、多轮工具调用导致的上下文冗余、超限、推理低效问题：

• 结构化上下文压缩：精准保留任务目标、当前执行状态、关键推理结论、下一步执行计划，剔除无效冗余信息；

• 超大工具结果自动落盘：超长工具返回结果本地化存储，上下文仅保留占位标识，大幅降低 Token 消耗；

• 文件读写安全策略：内置缓存机制，强制「先读后改」执行规范，避免文件操作冲突与数据异常。

1.6 可插拔 Workspace 执行环境抽象

实现「智能体业务逻辑」与「执行环境」完全解耦，统一各类运行环境接口规范。原生支持本地文件系统、Docker 容器、K8s 集群、E2B 云沙箱等多类执行后端，内置环境预热池机制，完美适配 RL 迭代、批量任务并行等高性能场景。

1.7 全场景模型容错与多模型适配

统一 Credential 凭证管理 + ModelRegistry 模型注册中心 抽象层，全面兼容通义千问、OpenAI、Anthropic、Gemini、DeepSeek、Ollama 等主流大模型。支持自定义重试次数、主备模型自动切换，主模型异常时无缝降级，大幅提升智能体服务稳定性。

1.8 企业级分布式部署能力

全新 DistributedBackend 一键分布式配置 ，原生适配 Redis、OSS、MySQL、PostgreSQL、腾讯云 COS 等主流存储组件。基于 (userId, sessionId) 二元组实现会话状态自动分桶持久化，支持多副本会话恢复、沙箱状态快照、子智能体跨副本路由，彻底适配集群化、高可用生产部署场景。

1.9 标准化协议互通体系

内置三大标准化协议适配，打通智能体内外通信壁垒：

• A2A（Agent-to-Agent）：智能体之间点对点通信协议，支持多智能体协同交互；

• MCP（Model Context Protocol）：模型上下文标准协议，打通外部生态工具与上下文互通；

• AG-UI：前端交互协议，标准化智能体与可视化界面的事件、消息交互规范。

1.10 声明式多智能体编排与技能体系

• 多智能体编排 ：支持 YAML/Markdown 声明式子智能体规格定义，运行时动态实现 agent_spawn（智能体生成）、agent_send（消息推送），同步阻塞、后台委派双模式适配不同协同场景，子智能体事件可实时转发至父级事件流。

• 四层技能系统 ：整合类路径、文件系统、Nacos、市场源四层技能加载机制，支持 SkillFilter 细粒度权限过滤，构建「技能提案 → 筛选优化 → 正式上线」的自学习闭环，实现技能动态迭代与复用。

2. GA 版本增量更新（2.0.0-RC5 → 2.0.0 GA）

本次正式版基于 RC5 候选版本迭代，聚焦细节优化、问题修复与场景补齐，新增多项实用能力，修复全链路潜在问题，大幅提升版本稳定性。

2.1 ✨ 新增能力

• 新增 AllToolsDeniedEvent 钩子：HITL 人工拒绝全部工具调用时自动触发，方便业务层统一监听、处理全拒绝场景；

• 优化 wait_async_results 异步等待机制，新增阻塞防护，避免长时间无意义阻塞占用资源；

• 新增 PostgresDistributedStore，原生支持 PostgreSQL 作为分布式持久化后端，丰富企业存储选型；

• Spring Boot Starter 新增 OpenAI、DashScope、Anthropic 模型 Builder 定制器，简化自动化配置成本。

2.2 🛠 核心修复与优化

2.2.1 核心 Agent 能力

• 重构 seedSystemMsg 为响应式实现，规避 NIO 线程阻塞问题；

• 修复权限审批状态消息渲染问题，确保 ASKING 状态下 ToolUseBlock 正常展示；

• 修复 Skill 分组激活逻辑，通过activateOnSkill 精准激活对应技能组；

• 支持用户中断会话时自动持久化智能体状态，解决会话数据丢失问题。

2.2.2 模型适配层

• 适配 Anthropic 模型并行工具调用规范，自动拆分交替排列消息，完全符合官方 API 要求；

• OpenAI 原生结构化输出能力改为可配置项，提升场景适配灵活性。

2.2.3 沙箱与工具执行

• 修复外部工具执行状态异常，确保正确返回 suspended 暂停状态；

• 优化计划模式（Plan Mode），支持技能加载工具正常调用；

• 完善子智能体中断机制，父订阅取消时自动回收孤儿子智能体资源；

• 统一多环境工作区路径解析规则，修复 Windows、Docker、K8s 路径适配异常；

• 优化 MCP 响应解析，支持嵌套 JSON 与横幅前缀格式适配。

2.2.4 通信与路由

• 修复群组消息路由异常，OutboundAddress 新增 PeerKind 节点类型标识；

• 优化 A2A 流式文本分片合并逻辑，解决消息碎片化问题。

3. 各 RC 版本完整迭代日志

本节完整还原 2.0.0 从 RC1 至 RC5、再到 GA 正式版的全部迭代明细 ，包含每一个版本的新增能力、架构变更、问题修复与文档更新，完整对齐官方 Release 记录。

2.0.0-RC5（2026-07-07）

版本定位 ：模块化拆分、多模态补齐、生态适配强化，为 GA 做最后能力收口

🔥 重大变更

模型提供商完全模块化拆分：OpenAI、Gemini、Anthropic、DashScope、Ollama 从 agentscope-core 内核拆分为独立扩展包 agentscope-extensions-model-*，业务项目需按需引入对应依赖，实现核心轻量化、模型可插拔 (#1890, #1916, #1947, #1972)。

✨ 新增能力

• 全模型统一支持 DataBlock 多模态内容 ，覆盖单智能体、多智能体协同、工具返回结果全链路 (#1933)。

• 原生结构化输出（Structured Output）与工具调用深度协同，支持模型原生 JSON Schema 强约束校验 (#1904)。

• DashScope 模型原生支持结构化输出能力 (#1935)。

• McpClientBuilder 新增 httpRequestCustomizer，支持动态 Token 注入、OAuth 自动刷新等鉴权扩展场景 (#1992)。

• AguiEvent 完整对齐 AG-UI 官方协议规范，补齐全部缺失事件类型，前端交互更规范 (#1862)。

• 子智能体支持技能白名单细粒度过滤，精准控制子 Agent 可用技能范围 (#1873)。

• Nacos 技能仓库支持 knownSkillNames 精准匹配，提升技能加载效率 (#1853)。

• 新增腾讯云 COS 分布式持久化组件：CosAgentStateStore、CosBaseStore、CosDistributedStore，补齐公有云存储选型 (#1857)。

• ChatUsage 暴露缓存 Prompt Token 统计字段，完善计费与观测指标 (#1868)。

🛠 核心修复

• 会话中断恢复场景自动持久化 Agent 状态，彻底解决重启会话数据丢失问题 (#2008)。

• 修复降级模型绑定逻辑，确保 Fallback 模型正常挂载至 ReActAgent 推理链路 (#1851)。

• 修复流式事件 Block 结束顺序错乱问题，保证前端流式渲染有序性 (#1829)。

• 工具结果数据更新后再写入上下文，避免上下文状态滞后异常 (#1886)。

• 复用 Classpath 技能 JAR 文件系统，修复长期运行资源泄漏问题 (#1981)。

• 修复 Flux 回调中 serializeOnKey 导致的网关资源泄漏 (#1796)。

• 模型层：适配 OpenAI 兼容 API 的 thinkingBudget 参数映射、修复 Anthropic 流式思考事件解析异常、补齐 Ollama 配置序列化完整性 (#2028, #1943, #2011)。

• DashScope 思考模式自动降级强制工具调用，适配模型能力边界 (#1882)。

• 沙箱与持久化：修复远程快照反序列化丢失客户端实例、记忆节流模式失效、父子上下文传播异常、路径空格转义、Windows 路径归一化、K8s 退出码空值判定等十余项稳定性问题 (#2013, #1788, #2001, #2031, #1892, #1903)。

• 可观测性：修复 OTel 链路追踪父子 Span 断裂、上下文无法透传问题，全链路追踪完整闭环 (#1940, #1909, #1923)。

• 多智能体：完整透传父级 RuntimeContext 与中间件链路，保证父子 Agent 执行环境一致 (#1833, #1843)。

• A2A 通信：修复流式背压阻塞、消息角色丢失问题，提升多 Agent 协同稳定性 (#1734, #1995)。

📚 文档优化

• 明确流式事件 blockId 语义规范，统一业务开发理解 (#2016)。

• 重构模型提供商接入文档，优化示例与配置说明 (#1986)。

• 清理无效 API 引用、修复分布式部署示例配置错误 (#1921, #1869)。

2.0.0-RC4（2026-06-18）

版本定位：异步能力增强、分布式会话优化、沙箱稳定性升级

✨ 新增能力

• Harness 全面支持异步工具执行 ，新增消息总线、异步工具注册、定时唤醒调度能力，支撑后台异步任务场景 (#1802)。

• Agent 调用新增 String / Message 便捷重载方法，开发调用更简洁；全部格式化器支持 HintBlock 提示消息 (#1802)。

• 持久化子 Agent 注册中心，支持子智能体跨副本路由、服务重启后会话恢复 (#1817)。

• DynamicSkillMiddleware 实现 Toolkit 感知，可动态解析运行时工具集，适配动态技能变更场景 (#1828)。

• Kubernetes 沙箱支持 Pod 环境变量注入，适配容器化定制部署场景 (#1789)。

🛠 核心修复

• 修复 K8s 文件上传 SIGKILL 竞态问题，采用双阶段归档策略，彻底解决文件上传偶发失败 (#1826)。

• 超时子 Agent 未及时中断导致的资源泄漏、重试状态异常问题 (#1784)。

• 修复 RuntimeContext 复制丢失 Typed 属性，保证上下文完整透传 (#1813)。

• 修复 MySQL utf8mb4 字符集下表初始化失败问题，适配全量中文与特殊字符 (#1781)。

• 会话 JSONL 落盘改为幂等写入，避免重复数据堆积 (#1774)。

• 修复 OpenTelemetry 上下文传播异常，完善链路追踪完整性 (#1799)。

• 修复 Ollama 工具调用 Option 空指针 NPE 异常 (#1803)。

• 补齐本地沙箱快照 Jackson 序列化注解，修复状态持久化解析失败 (#1825)。

• 修复沙箱 Glob 递归匹配 / 规则失效问题，完善文件权限匹配 (#1684)。

• 修复 SkillFilter 仅匹配名称、不匹配复合 ID 的精准度问题 (#1771)。

• 多模态工具支持自定义默认视觉模型，灵活适配不同算力场景 (#1701)。

📚 文档修复

• 修正中间件文档钩子签名错误、废弃接口示例 (#1835)。

• 清理文档中不存在的 API 与错误方法名引用 (#1792, #1760)。

2.0.0-RC3（2026-06-11）

版本定位：事件体系标准化、调用链路统一、分布式一致性优化

✨ 新增能力

• 新增 AgentResultEvent ：Agent 执行结束、AgentEndEvent 触发前推送，业务可从事件流直接获取最终结果，无需额外订阅 Mono 返回值。

• 新增 CustomEvent 通用自定义事件：支持中间件推送业务级状态变更、团队变更等自定义通知，无需硬编码事件枚举。

• 新增 HintBlockEvent 提示事件：专门承载后台结果、用户中断、团队消息等一次性提示内容，区分流式文本增量输出。

• 新增 WorkspacePathNormalizer 路径归一化工具，统一本地/沙箱路径解析规则，杜绝跨环境路径误匹配。

• 全部工具事件新增 toolCallName 字段，前端无需缓存映射关系，直接精准关联工具调用事件。

🔥 核心变更

• 统一 call() 与 streamEvents() 底层执行内核，通过 buildAgentStream 统一调度，保证所有调用路径中间件执行一致性。

• 分布式环境强制从 StateStore 加载会话状态，彻底解决多副本部署状态缓存漂移问题。

• 优化 ToolResultEvictionMiddleware 执行时机，从 Acting 阶段迁移至 Reasoning 阶段，保证工具结果落盘后再执行淘汰逻辑。

• 简化本地文件系统路径解析逻辑，精简冗余代码，提升文件操作性能。

🛠 关键修复

• 修复测试场景 RuntimeContext 缺失 UserId，导致多用户隔离失效问题。

2.0.0-RC2（2026-06-09）

版本定位：无状态架构落地、分布式能力重构、权限与编排能力升级

✨ 新增能力

• 新增 projectWritable 项目可写模式，智能区分工作区元数据与业务文件写入路径，适配代码生成类 Agent 场景。

• 权限引擎支持运行时动态切换权限模式，单会话可按需调整管控策略。

• 子 Agent 事件全量实时转发，事件新增 source 来源标识，精准区分主 Agent / 子 Agent 事件流。

• 记忆压缩、上下文淘汰支持独立模型与自定义 Prompt，可配置轻量模型降低成本。

• 原生支持 Qwen3.7 全系模型解析与调用适配。

• 支持直接向声明式子 Agent 主动发消息对话，无需经过父 Agent 推理循环。

• 新增 Channel 扩展模块，开箱即用支持钉钉、飞书、企业微信、GitHub、GitLab 平台接入。

🔥 重大架构变更

• ReActAgent 完全无状态重构 ：移除所有会话级可变字段，全部状态通过 Context 透传，单实例安全支撑高并发多会话。

• 统一持久化体系：废弃旧 SessionManager、StatePersistence 接口，全面切换 AgentStateStore 统一存储抽象。

• 分布式能力收口：新增 DistributedBackend 一键分布式配置，统一 Redis/OSS/MySQL/COS 部署模式。

• 模块拆分重构：沙箱实现、扩展能力全部拆分为独立扩展包，核心内核极致轻量化。

🛠 核心修复

• 修复跨会话权限状态丢失问题，保证分布式会话恢复后权限策略一致。

• 修复全量扩展包依赖缺失问题，补齐各类沙箱默认实现。

2.0.0-RC1（2025-05-28）

版本定位 ：2.0 架构首个可用候选版，完成全量工程化底座落地

首次落地 2.0 核心架构体系：双层 Agent 架构、工程化 Harness 基础设施、多租户分布式部署、安全沙箱隔离、中间件扩展体系、HITL 人工审批权限系统、标准化事件流与多智能体编排能力，完成从 1.x 轻量原型到企业级工程框架的架构跨越。

4. 版本总结与升级建议

AgentScope Java 2.0.0 GA 版本通过架构重构、工程补齐、生态适配、稳定性优化 四大核心迭代，彻底解决了 1.x 版本状态不可控、扩展能力弱、无法集群部署、生产稳定性差等痛点，成为一套完备的企业级 Java 智能体开发框架 ，可全面支撑复杂 Agent、多智能体协同、长周期任务、生产级高可用场景落地。

升级建议 ：所有 1.x、2.0 RC 版本用户建议统一升级至 2.0.0 GA 正式版，参考官方「V1 迁移指南」完成依赖适配与代码改造，享受完整工程化能力与长期版本维护支持。