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

1. 核心设计概要

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

发布日期：2026-07-10

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

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暴露缓存PromptToken统计字段，完善计费与观测指标 (#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 迁移指南」完成依赖适配与代码改造，享受完整工程化能力与长期版本维护支持。