AgentScope Java 架构揭秘：阿里为什么用 Java 重写 AI Agent 框架？

某大厂 AI 团队用 Python 搭了一套 Agent 系统，跑实验效果很好。

然后他们要接生产：要跟现有的 Spring Boot 微服务集成，要对接 Dubbo RPC，要接入公司的统一监控体系，还要过安全部门的代码审查……

Python 的同学看着这堆需求，沉默了三秒，然后说：

"要不，咱们用 Java 重写一遍？"

这就是 AgentScope Java 存在的理由。

Java 开发者占全球开发者的 35%，企业后端几乎都是 Java 的天下。但 AI Agent 框架的生态里，Java 长期是个"局外人"——要么用 Python，要么接 API，能做的事情极为有限。

AgentScope Java 是阿里巴巴开源的 Java 原生 AI Agent 框架，2026 年 5 月发布 1.0 版本，目标只有一个：

让 Java 工程师不用切换语言，也能构建生产级 AI Agent 应用。

今天这篇文章，就来把它的核心架构拆个干净。

先看全貌：四层架构

AgentScope Java 的整体架构是经典的分层设计，但每一层的选型都颇有讲究：

AgentScope Java 四层架构

从上到下：

• 核心层：ReActAgent、HarnessAgent、Memory —— JDK 17 的 Records 和 Sealed Classes 在这里大显身手
• 服务层：Project Reactor 全链路非阻塞，Mono/Flux 搭建异步消息路由
• 集成层：MCP 协议、A2A 协议、Spring Boot、Nacos——Java 生态该有的都有
• 部署层：GraalVM 原生镜像，200ms 冷启动，K8s + HPA 弹性扩缩

为什么选 JDK 17？因为 Records、Sealed Classes、Pattern Matching 这些特性，对于构建不可变消息模型和类型安全的 Agent 状态机，效果拔群。后面会详细说。

核心一：ReAct 推理引擎

ReAct 是什么？

ReAct（Reasoning + Acting） 是 Agent 的核心推理范式，2022 年由 Google 提出。

简单说，就是让 LLM 交替做两件事：想一步、动一步、看结果、再想——不是一次性生成答案，而是循环逼近。

这个循环最大的好处是：模型每一步都能看到工具的真实返回，不会"幻觉出"一个没有的结果。

ReAct 推理循环

AgentScope Java 的 ReActAgent

最简洁的用法：

ReActAgent 核心代码

关键设计：每次工具调用的结果会作为新消息追加到历史里，LLM 下一步能看到"自己做了什么、结果是什么"，这就是 ReAct 比普通 Prompt 强的地方。

核心二：不可变消息系统

这是 AgentScope Java 和大多数 Python 框架最不一样的地方。

为什么要"不可变"？

Python 框架里，消息通常就是个 dict，随时可以改。在多线程、响应式场景下，这是灾难——你永远不知道这个 dict 被谁改了。

AgentScope Java 的消息是不可变的 Record，由一组 Sealed ContentBlock 组成：

不可变消息 & ContentBlock 类型体系

四种 Block 各司其职：TextBlock 承载文本，ThinkingBlock 记录 CoT 推理过程，ToolUseBlock 描述工具调用意图，ToolResultBlock 携带执行结果。

处理起来是什么感觉？

ContentBlock 模式匹配

Java 17 的 Pattern Matching + Sealed Classes，把"多态消息处理"变得既安全又优雅。编译器强制你处理每一种 Block 类型，漏掉一个就编译报错——这才叫真正的类型安全。

核心三：@Tool 注解系统

这是让 Java 工程师"宾至如归"的设计。

极简工具定义

Tool 注解系统

整个系统的核心流程：写方法 → 加注解 → 框架反射生成 Schema → LLM 调用 → 框架执行 → 结果封装。开发者只需要关心业务逻辑，框架搞定其余一切。

代码长这样：

Tool 注解代码示例

ToolExecutionContext 是框架注入的，不会出现在发给 LLM 的 Schema 里。干净利落地解决了"工具需要请求上下文但不能暴露给 LLM"的经典矛盾。

核心四：响应式基础设施

为什么 AgentScope Java 用 Project Reactor？

这是整个框架最重要的架构决策，也是最容易被忽视的。

Agent 调用的典型瀑布

一次 Agent 调用可能是这样的：

1  LLM 推理（100-3000ms）→ 工具 A（10-50ms）→ 工具 B（200-500ms）→ LLM 推理 → 工具 C → 最终 LLM 推理

全程都是 I/O 等待。 如果用传统阻塞线程，一个 Agent 会话就会占用一个线程，撑死几千个并发。

Project Reactor 的非阻塞模型让同一线程池可以服务数万个并发 Agent 调用。

编程规范：

响应式编程规范

核心规则只有一条：.block() 只在 main() 或测试代码里用。 在 Agent 内部任何地方调用 .block() 都会死锁。

核心五：九种多智能体模式

单个 Agent 能力有限。AgentScope Java 内置了 9 种多智能体协作模式，覆盖主流业务场景：

九种多智能体协作模式

三种最核心的模式代码：

多智能体编排代码

选择逻辑很简单：

• 流程固定 → Pipeline
• 任务类型不固定 → Supervisor
• 角色边界清晰 → Handoffs

核心六：企业级集成能力

企业级集成能力

三个关键数字：

• 200ms 冷启动（GraalVM 原生镜像，JVM 版约 5s）
• 全链路非阻塞（Project Reactor，支撑高并发 Agent 服务）
• 无状态设计（Redis Session + OSS 工作区，任意副本恢复同一用户上下文）

MCP 协议让你用一套 API 接入任意工具（Python 脚本、本地进程、外部服务），A2A 协议让不同 Agent 之间跨进程、跨机器互相调用，就像调本地方法一样自然。

和 Python 版本的关系

很多人会问：AgentScope 已经有 Python 版，Java 版是不是就是翻译过来的？

答案是：不是。

两个版本共享核心概念（ReAct、Harness、多智能体模式），但实现是独立的，不是相互翻译。

Python 版适合： 快速验证 Idea，做学术实验，个人项目。

Java 版适合： 接入公司现有 Java 微服务，需要横向扩展，要过安全审查的生产系统。

总结

AgentScope Java 的五大核心设计决策，以及把它们串联起来的三个胶水对象：

五大核心设计决策

整个框架的设计哲学只有一句话：每一层只做自己的事，通过明确的接口协作。

• 不可变消息让并发安全；
• @Tool 注解让工具接入变成写业务代码；
• Project Reactor 让高并发不再是线程数的问题；
• Harness 可选装配让复杂能力零侵入地叠加；
• MCP + A2A 让 Agent 生态不再是孤岛。

Java 生态的 AI Agent，终于有了一个真正工程化的选择。

项目地址： https://github.com/agentscope-ai/agentscope-java

官方文档： https://java.agentscope.io/