AgentScope 拆解 · 01 入门篇
写给那些感受到了 AI 浪潮、却被 Python 劝退的 Java 程序员
我想先问你一个问题。
你最近是不是经常刷到这样的内容——"我用 AI Agent 自动写代码"、"Agent 帮我分析数据"、"多智能体协作完成复杂任务"……你看着这些 demo，心里有个声音：AI 时代真的来了，我得跟上。
然后你点开教程，第一行代码：
Python。你关掉了页面。
如果你经历过这个瞬间——不是你不想学，是所有的教程都不说你的语言——那这个专题是写给你的。
我是 Java 程序员，写了多年后端。几个月前我和你一样，想搞懂 Agent 到底是什么，但满世界找不到一份用 Java 程序员能懂的话把它讲清楚的资料。所以我决定自己拆——从阿里开源的 AgentScope-Java 源码开始，一行行读，一篇篇写。
这是这个专题的第一篇。我不灌概念，不堆术语，只回答一个问题：AgentScope-Java 到底是个什么东西？
· · ·
1一句话说清楚它是什么
一句话定义
AgentScope-Java 是一个让你不用写死流程，而是让大模型自己决定调用什么工具的框架。
这句话里有最关键的一个词：自己决定。
我换一种你更熟悉的方式说。你写了这么多年代码，本质上一直在干一件事——替程序把所有分支都想好。用户点这个按钮，走这个分支；参数是 null，走那个分支；数据库查不到，抛异常。每一行 if，都是你在替程序做决定。
而 Agent 框架，把这个权力交出去了一部分——交给大模型。
你不再写"如果用户问天气，就调天气接口"。你只做两件事：
1. 告诉模型："你有这些工具可以用"（比如查天气、查数据库、发邮件）
2. 然后等模型自己说："用户问天气，我决定调查天气工具"
决策的那一步，不是你写的 if，是模型自己想的。这就是 Agentic（智能体）范式和传统编程的根本区别。
💡 一个让你脑洞大开的认知：写 Agent 代码，你从"替程序做所有决定"，变成了"给程序一些工具，让它自己看着办"。你的角色，从流程的设计者，变成了工具的提供者。
· · ·
2它和我天天写的 Spring，是什么关系？
这是 Java 程序员问得最多的一个问题。我知道你心里在想：Spring Boot 已经能搞定一切了，我为什么还要学个新框架？
这里必须提一下阿里的另一个框架——Spring AI Alibaba。它和 AgentScope-Java 经常被放在一起比较，但它们其实是两种完全不同的思路：
Workflow 思路
Spring AI Alibaba
你画好流程图：第一步干嘛、第二步干嘛、条件分支怎么走。模型只在节点里填空。本质还是你在写流程，只是某些节点接了 AI。偏固定、清晰的流程。
Agentic 思路
AgentScope-Java
你只给目标：给模型一些工具，让它自己决定先做什么、后做什么、用什么工具。流程是模型现场生成的，不是你预设的。
打个比方，可能更直观：
• Spring AI Alibaba 像是你给员工写好了一份 SOP（标准操作流程），第 1 步到第 10 步都写死，员工照着做就行。
• AgentScope-Java 像是你招了一个聪明人，告诉他"这是你的工具箱，这是你的目标，你自己想办法完成"。
✅ 怎么选？如果你的业务流程是固定、清晰的（比如审批流、报表生成），用 Spring AI Alibaba，画流程图更可控。如果任务是开放的、需要临场判断的（比如"帮我分析这个项目有没有风险"），用 AgentScope，让模型自己规划。两者不冲突，甚至可以配合用。
所以 AgentScope-Java 不是要替代 Spring，而是补上了 Spring 生态里"让模型自主决策"这块拼图。
· · ·
310 分钟，跑起来你的第一个 Agent
概念讲完了，来点实在的。我现在带你跑起来一个真正的 Agent——不用 Python，不用复杂的配置，纯 Java。
你需要准备什么
• JDK 17 或以上（AgentScope 用了 Records、模式匹配这些新特性，老项目要升级）
• 一个 DashScope API Key（阿里通义的 API，去 dashscope.console.aliyun.com 免费申请）
核心代码，就这么多
别被"框架"两个字吓到。构建一个 Agent，核心代码比你写一个 Controller 还短：
先加依赖（两个都要，版本以 Maven Central 最新为准）
<!-- pom.xml --><dependency> <groupId>io.agentscope</groupId> <artifactId>agentscope-core</artifactId> <version>2.0.2</version></dependency><dependency> <groupId>io.agentscope</groupId> <artifactId>agentscope-extensions-model-dashscope</artifactId> <version>2.0.2</version></dependency>import io.agentscope.core.ReActAgent;import io.agentscope.core.event.TextBlockDeltaEvent;import io.agentscope.core.message.UserMessage;import io.agentscope.core.tool.Toolkit;// 构建 Agent —— 核心配置就这几行ReActAgent agent = ReActAgent.builder() .name("Assistant") // 给它起个名 .sysPrompt("你是一个友好的 AI 助手") // 系统提示词 .model("dashscope:qwen-plus") // 用哪个模型（自动读 API Key） .toolkit(newToolkit()) // 工具箱（先空着） .build();// 跟它说句话 —— 流式输出（逐字打印回复）agent.streamEvents(newUserMessage("你好，介绍一下你自己")) .doOnNext(event -> {if (event instanceofTextBlockDeltaEvent delta) { System.out.print(delta.getDelta()); } }) .blockLast();就这些。一个能跟你对话的 Agent，构建 + 调用 + 逐字打印，满打满算 20 行上下——核心其实只有 builder 那几行。
这里有几个细节值得你注意：
1..model("dashscope:qwen-plus") 这一行——你传的是一个字符串，框架会自动解析出用哪个模型供应商，并从环境变量里读 API Key。你不用自己 new 一堆配置对象。
2..toolkit(new Toolkit()) 现在是空的，意味着这个 Agent 还只能聊天，不能调工具。后面几篇我们就给它装上工具。
3.streamEvents() 返回的是一个事件流（Flux）。我们只过滤出 TextBlockDeltaEvent（文本片段）打印，Agent 的回答就会像打字机一样逐字往外吐——就像你用 ChatGPT 时看到的那样。
// 运行结果：回复会像打字机一样逐字打出你好！我是一个 AI 助手，可以帮助你回答问题、提供建议。请问有什么我可以帮你的？看到这个输出的那一刻，你就拥有了自己的第一个 Java Agent。
⚠️ 想真跑起来，就差一步（依赖见上方 Maven 配置）
设环境变量：export DASHSCOPE_API_KEY=你的key
· · ·
4你可能会问：它到底比 ChatGPT 强在哪？
看到这里，你可能有个疑问："这不就是个套壳聊天机器人吗？我自己调 API 也能实现，为什么要用框架？"
好问题。如果你只是要"模型回复一段话"，确实直接调 API 就行，不需要任何框架。
但 Agent 要做的事，远比"聊天"复杂。试想这个场景：
你对 Agent 说："帮我看看数据库里昨天的订单，如果有异常的，生成一份报告发到我邮箱。"一个真正的 Agent，需要自己拆解这个任务：
1. 查数据库（调用工具）
2. 分析结果，判断哪些算"异常"（模型推理）
3. 如果有异常，生成报告（调用工具）
4. 发送邮件（调用工具）
5. 如果中间某步失败了，自己想办法处理（模型决策）
这里面有"推理"、有"调工具"、有"根据结果决定下一步"——这三件事交替循环，直到任务完成。这就是大名鼎鼎的 ReAct 模式（Reasoning + Acting）。
如果你自己用裸 API 实现这套逻辑，你要写：工具调用的解析、多轮上下文的管理、循环的控制、错误处理、流式输出、并发控制……这些又脏又累的活，AgentScope 全帮你做好了。框架的价值，就在这里。
🎯 一句话总结框架的价值：裸调 API，你得到的是"一个会说话的模型"。用 Agent 框架，你得到的是"一个会思考、会用工具、能自主完成任务的智能体"。前者是嘴巴，后者是员工。
📌 划重点：今天你该记住的 3 件事
① AgentScope-Java 是"给工具、让模型自己决定"，不是"写死流程"。
② 它补的是 Spring 生态里"模型自主决策"那块拼图，不替代 Spring。
③ 框架的价值 = 帮你干掉工具解析、循环控制、流式输出这些脏活。
5这个专题，我会带你走到哪？
这是第一篇，我不会在这里把所有东西讲完。我规划了一条完整的路线——不抠代码，而是讲透 AgentScope 每一块的设计：它解决什么问题、为什么这么设计、关键决策权衡了什么。
• 主题一 · 核心机制：讲透 core 层——ReAct 循环、工具系统、消息、记忆、中间件。学完你不只会用，更懂它"为什么是这样"。
• 主题二 · 工程落地：讲透 harness 层——沙箱、文件系统、多 Agent 协作、消息通道、水平扩展。学完你能把它跑在生产。
• 主题三 · 生态对比：跳出框架看生态——模型供应商、RAG、MCP/A2A 协议、和其他框架横评。学完你具备全局判断力。
整个过程，我都用Java 程序员能懂的话来讲。Spring 的拦截器、CompletableFuture、Bean 容器——这些你烂熟的概念，都会被我用来翻译 Agent 里的新东西。
因为一年前的我，就希望有人这样讲给我听。
💬 你被 Python 劝退过吗？或者你更想看我拆哪块源码？评论区聊聊，下一篇的选题听你们的。
▶ 下一篇预告
今天我们只回答了"AgentScope 是什么"。
下一篇，我会用一张图，带你俯瞰 AgentScope 的三层架构——Core（怎么思考）、Harness（怎么干活）、Extensions（怎么连接外部世界）。
关注我，Java 程序员的 Agent 之路，咱们一篇一篇搞定。
如果这篇对你有用
点个 关注，下篇带你用一张图看懂三层架构
「AgentScope 源码拆解」专题 · 持续更新
