Java 17+ 专属！一款阿里达摩院开源的 Java AI Agent 生产级框架，非常丝滑

阅读全文

⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 http://www.iocoder.cn/Fight/agentscope-java-framework-view/ 「芋道源码」欢迎转载，保留摘要，谢谢！

🙂🙂🙂关注微信公众号：【芋道源码】有福利：

RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表

RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址

您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。

新的源码解析文章实时收到通知。每周更新一篇左右。

认真的源码交流微信群。

说真的，Java 开发者在 AI Agent 这事上，憋屈了不是一天两天。

LangChain、AutoGen、LlamaIndex，主流框架清一色 Python 生态。你平时写 Java、用 Spring Boot 搭服务，想上 Agent，路无非三条，硬学新语言；起 Python 服务搭桥给 Java 调；或用 Spring AI，把大模型当高级接口塞进工作流调一调。

第二条路的日常，大概长这样。

// Java 侧手动调 Python 侧 LangChain 服务
String body = "{\"messages\":[{\"role\":\"user\",\"content\":\"查一下这笔订单的风险等级\"}]}";
String result = rest.postForObject("http://python-agent:8000/run", entity, String.class);
// 拿回一坨 String 自己解析成对象，超时、重试、鉴权各写各的

一个 Agent 调用，两个运行时，一套手搓的序列化。Python 侧一升级，Java 侧跟着改。

第一条费人，第二条费架构，业务还没动笔，系统图上先多出一个运行时、一条易碎的桥。第三条最省事，但离真正有自主决策能力的 Agent 差一层。

AgentScope Java 就是冲这个空档来的，一个专门为 Java 生态做的 Agent 开发框架，GitHub 上攒了 5000 多个 Star，Apache 2.0 协议，维护方是阿里通义实验室。

AgentScope 官方 Logo

这篇我把它讲透，机制、版本坑、上手步骤，还有什么时候不该用。

什么来头，十个月从 0.1 跳到 2.0

先给定位。专门为 Java 生态设计的 AI Agent 开发框架，目标一句话，构建生产级别的 LLM 应用。背后是阿里通义实验室，先做了 Python 版 AgentScope，Java 版移植同一套设计理念，再把 Java 生态特有的东西全接上了，Maven 依赖管理、响应式编程、GraalVM 原生镜像。

版本节奏值得单看。2025 年 9 月项目放出 v0.1，11 月就到 v1.0 正式版，今年 4 月迭代到 1.0.12，7 月发了 2.0 正式版，现在最新是 2.0.1。十个月从 0.1 跳到 2.0，投入是真金白银。

AgentScope Java 版本演进时间线

但节奏快也意味着，你得搞清楚自己站在哪个版本里。2.0 起推荐坐标换成 agentscope-harness（自动引入 core），模型拆成独立扩展模块。拿 1.x 坐标拉 2.0 新特性拉不下来。这个坑，动手那节用两条路写清。

对了，JDK 17 起步，还停在 JDK 8 的朋友正好顺手升个级。跑起来报 Key 的错，先查环境变量。

别再给 Agent 画流程图了

多数框架让你画流程图，先做 A，再做 B，调工具 C，拿结果走分支 D。可控但僵硬，任务跑出预设路径，Agent 要么卡死，要么乱来。

AgentScope Java 走 ReAct 路线（Reasoning and Acting），不规定步骤，让大模型每一轮自己想。

现在情况是什么 → 我该做什么 → 调什么工具 → 拿到结果再想下一步

观察、推理、行动，循环往复，没有硬编码的执行顺序。工具返回意外结果，它能自己琢磨怎么处理，不是当场崩掉。这是用模型的判断力换掉你手画的流程图；代价是路径不可预知，”叫停机制”那节你得认真看。

框架里的 ReActAgent 就是这个范式的实现，builder 配三样，名字、系统提示词、模型。模型用通义千问 qwen-max 走 DashScope 接入；框架不锁定模型。完整可运行代码放在《动手跑通》那节，照抄就能跑。

放养也有兜底。官方在掘金写过，ReAct 循环超过最大迭代轮数会触发 summary 机制，自动总结收尾，不会无限跑飞。自主框架必须回答”跑不动了怎么办”，它答了。

流程图式与 ReAct 循环对比

能叫停，才敢放手

ReAct 给了 Agent 自主权。但生产环境里，你敢让一个能自己决策、能调工具的程序在线上随便跑吗？

这块它做了一整套运行时干预机制，也是和一堆”Demo 友好”框架的核心区别。

安全中断，任意时刻暂停 Agent，上下文和工具调用状态全部保留，之后无缝恢复
优雅取消，工具跑太久、或明显不对劲，直接终止，不破坏整体状态，可立即重新调度
Hook 系统，推理过程任意步骤插钩子，人工审核、注入信息、强制调整方向，敏感操作场景的刚需

我的判断浓缩成一句话。一个框架能不能上生产，从来不看顺的时候有多丝滑。真到出事的时候，你能不能叫停它、恢复它、说清楚它干了什么。

2.0 又推了一层，权限系统做成三态，直接允许、需用户批准、直接拒绝，像极了手机 App 的权限弹窗；中间件在 onAgent、onReasoning、onActing、onModelCall、onSystemPrompt 五个阶段留钩子，推理每一步都能被你的代码拦住。

四件苦力活，框架已经替你干了

Agent 开发有几件反复出现的脏活，框架内置四个模块，一个个过。

PlanNotebook，治 Agent 的”执行失忆症”，复杂任务干到一半忘了自己在干嘛。方案是结构化任务清单，自己拆子步骤，完成打勾，可暂停、修改、恢复。计划外置成清单，不是塞上下文靠记忆硬撑。

结构化输出，管 Java 开发者最较真的类型安全。模型吐的本质是文本，业务要的是对象；手写解析脆，格式抖一下就崩。模块带自纠错，偏了自动检测、引导重生成，最后映射成 POJO。类型安全不是加分项，是基本要求。

长期记忆，默认的 Agent 对话一结束就失忆。这里是持久化存储加语义搜索，跨会话能找回存过的内容。管理模式三种，全自动、Agent 自己决定记什么、混合；企业场景还做多租户隔离，多用户共用一个实例，记忆不互串。

RAG，检索增强生成内置。自建 Embedding 检索能接，阿里云百炼这类托管服务也能接，让回答基于你的知识库，不是只靠模型参数里那点旧知识。

再补一个容易被低估的，上下文管理。社区管这叫”上下文焦虑”，窗口参数涨得飞快，可关键信息放中间位置，检索效果照样掉，跟人记东西一个毛病，记得开头结尾、忘中间。2.0 在框架层做了上下文工程，结构化压缩、超大工具结果落盘、先读后改。这活交给框架，比每人自己抠提示词靠谱。

AgentScope Java 三层能力地图

MCP、A2A，还有你熟悉的 Nacos

生态集成，两个协议值得认识。

MCP（Model Context Protocol）是 Anthropic 推的标准，规定 LLM 应用和外部工具怎么通信。数据库、浏览器、文件系统、代码解释器……大量工具已有服务端实现。AgentScope Java 原生支持，工具实现了 MCP 服务端，Agent 接上就能用，不用逐个写适配。生态越大，杠杆越长。

A2A（Agent-to-Agent）管多 Agent 协作，Agent 能力注册到 Nacos 或类似注册中心，别的 Agent 走服务发现直接调，像调微服务。Java Agent 能和 Python 等语言的 Agent 协同，不被绑死。

你应该品出味儿了，注册中心、服务发现，这套语法 Java 团队用了十几年。别的框架让你学新概念，这里是把你的存量经验平移进 Agent 时代。

接生态用 MCP，接自己的业务更简单，方法标 @Tool、参数标 @ToolParam，就成了 Agent 能调用的工具。

社区还真有人拿它开了家 AI 奶茶店。架构 Supervisor-Worker，店长 Agent 接客分活，店员 Agent 各管一摊；Agent as Tool 把子 Agent 当工具调；配上 Mem0 长期记忆和 AutoContextMemory 上下文管理，K8s Helm 部署上线。从单 Agent 到多 Agent 编排，路被踩通了。

奶茶店多 Agent 架构

上生产前的三道验收

把它当生产候选，建议按三道验收来。

第一道，并发。底层 Project Reactor 响应式，非阻塞执行，大量 Agent 同时跑，线程不傻等 LLM 响应，资源利用率高一截。

第二道，冷启动。支持 GraalVM 编译原生镜像，1.x 口径冷启动 200ms 级，2.0 官方在 Quarkus 下给到 100ms 内。要跑 Serverless 或 K8s 弹性扩缩容，这是入场券，JVM 那几秒冷启动在函数计算里真的难受。

第三道，安全与追责。AgentScope Runtime 给工具代码隔离执行环境，防 Agent 越权操作系统资源，预置 GUI 自动化、文件系统、移动设备几类沙箱；2.0 演进成 Workspace 抽象，本地磁盘、Docker、K8s、云沙箱任选。

可观测性上，OpenTelemetry 分布式追踪，每步推理、每次调用都有数据；AgentScope Studio 能可视化看思维链，调试时特别香。背后是官方说的”透明度第一性”，Agent 每走一步都该看得见。

状态管理单独说，2.0 默认 JsonFileAgentStateStore 落本地文件，开发单机够用；上生产换 RedisAgentStateStore。状态外置，服务重启会话还在，安全中断后”无缝恢复”，地基在这。

官方口径是，阿里集团内部使用最广泛的智能体框架，十余条核心业务线在生产用。这是官方自述，有参考价值，但别当第三方审计看。

动手跑通，1.x 老坐标和 2.0 新坐标别拿混

前提是 JDK 17+ Maven。

1.x 老路，第一步加依赖。

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version>1.0.12</version>
</dependency>

第二步写 Agent。

ReActAgent agent = ReActAgent.builder()
    .name("MyAgent")
    .sysPrompt("You are a helpful assistant.")
    .model(DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen-max")
        .build())
    .build();

Msg response = agent.call(
    Msg.builder().textContent("帮我列出 Java 17 的主要新特性").build()
).block();

System.out.println(response.getTextContent());

第三步设 DASHSCOPE_API_KEY（通义 Key，百炼控制台申请），打印回复即成功。

2.0 新路换 harness，加 io.agentscope:agentscope-extensions-model-dashscope（2.0.1）。

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
</dependency>

模型 .model("dashscope:qwen-plus") 自动读 Key；跑通后多出 .agentscope/workspace。

它和 Spring AI，根本不是二选一

聊到这必须说清 Spring AI。流行说法是它做 Agent”力不从心”，这话得修正，不是能力问题，是定位问题。

Spring AI 的逻辑，LLM 是一个节点，你定义整体工作流，让模型在特定节点干特定的活。控制权在你手里，流程可预期、好测试，适合把业务的某个环节换成 AI。

AgentScope Java 的逻辑，LLM 是大脑，给它目标和工具，让它自己规划怎么干。控制权在 Agent 手里，适合任务路径不固定、要临场判断的场景。

所以实操里两者是配合，Spring AI 管整体流程，需要自主决策的节点挂一个 AgentScope Java 构建的 Agent。一个管骨架，一个管脑子，谁也不抢谁的活。

Spring AI 与 AgentScope Java 分工对比

三种情况，先别急着上

夸了这么多，收尾必须泼冷水，不然不配当决策参考。

第一种，任务路径固定、追求强可预期。固定格式的生成、标准流程的问答，画好流程图的 Spring AI 甚至传统服务更合适，别为 Agent 而 Agent。

第二种，想直接压核心业务。2.0 官方 FAQ 自己承认有 API 不兼容变更，项目开源才一年左右、节奏飞快，API 大概率还会变。现在 all-in 就得做好跟着升级的准备，从非核心业务试点更稳。

第三种，指望看两篇文档就精通。社区作者观察很实在，光看文档和单一 Example 效率不够，组合使用得自己啃。学习成本真实存在。

还有个诚实的边界，把它写成上手长文的作者自己也坦白，还没在正式项目里跑通。设计完成度和生产验证是两回事。但类型安全、生产可控、与现有 Java 生态的集成这三件刚需，它确实都想到了。

如果决定试，路径可以很短，装 2.0 新坐标，跑通一个 ReActAgent，盯三个信号，控制台正常回复、workspace 目录出现、Studio 里能看到思维链。然后挑个非核心业务挂个真实小任务跑两周，再决定扩不扩。

三种先别上与试点决策路径

开源地址在 https://github.com/agentscope-ai/agentscope-java ，文档在 java.agentscope.io，中英双语。自己去看，比听谁说都强。