【AgentScope Java新手村系列】（1）框架简介与环境搭建

张

张建站

2026/6/10 12:30:26

10分钟阅读

第一章 AgentScope Java 2.0 入门从源码编译到第一个能对话的 Agent本章把 2.0.0-RC2 框架从 GitHub 拉下来编译安装、用纯 Java 启动工程、接入 DeepSeek 模型并跑通对话——完成你 AgentScope Java 学习之旅的第 0 步。1.1 AgentScope Java 是什么AgentScope Java 是阿里巴巴开源的 Agent 编程框架用于构建基于大语言模型LLM的智能体应用。2.0 是一次较大规模的重构在 1.x 的 ReAct 循环基础上抽出独立的HarnessAgent层把工作区、人格、长期记忆、子 agent 编排、沙箱隔离、技能装配、计划模式打包成一个工程就绪的入口同时把 1.x 的模块大杂烩拆成清晰的核心扩展。项目地址https://github.com/agentscope-ai/agentscope-java2.0 的核心能力ReActAgent核心推理循环思考 → 调用工具 → 观察结果 → 继续思考1.x 的核心类完全保留。HarnessAgent推荐入口在ReActAgent之上的一层薄包装把长期运行 agent 必备的工程能力工作区、Session、记忆、压缩、子 agent、沙箱、技能、Plan Mode用一个 Builder 串起来。工具系统通过Tool注解将任意 Java 方法注册为 Agent 可调用的工具工具元数据生成 JSON Schema 由 LLM 自动调用。多模型支持内置 OpenAI 协议DeepSeek、GLM、Ollama 等所有 OpenAI 兼容服务、DashScope通义千问、Anthropic Claude、Google Gemini。会话与状态AgentStateAgentStateStore取代了 1.x 的Memory体系跨进程、跨机器、跨副本的状态恢复统一由AgentStateStore后端承担InMemoryAgentStateStore/JsonFileAgentStateStore/RedisAgentStateStore/MysqlAgentStateStore。子 Agent 编排2.0 取代 Pipeline/MsgHubSubagentDeclaration声明一个子 agent主 agent 通过agent_spawn工具委派支持同步timeout_seconds 0和后台timeout_seconds 0后台任务完成时自动反向通知。Middleware 体系2.0 取代 HookMiddlewareBase暴露 5 个钩子位置onAgent/onReasoning/onActing/onModelCall/onSystemPrompt可在 ReAct 循环关键时机插入逻辑。工作区驱动的人格在workspace/AGENTS.md写人格、workspace/MEMORY.md沉淀长期事实workspace/subagents/id.md声明子 agent文件即配置。结构化输出让 Agent 返回指定 Java 类型的数据。MCP 集成声明式 MCP server 工具粒度允许/拒绝。1.x → 2.0 重大变更io.agentscope.core.pipeline.*Pipeline、SequentialPipeline、FanoutPipeline、MsgHub、Pipelines已移除改用子 agent 系统。io.agentscope.core.memory.*InMemoryMemory、LongTermMemoryDeprecated(forRemoval true)保留为兼容层新代码请用AgentState.getContext()AgentStateStore。io.agentscope.core.model.tts.*已移除TTS 不在 core 中提供。Hook接口Deprecated(forRemoval true)新代码请用Middleware/MiddlewareBase。agent.stream()返回FluxEventDeprecated(forRemoval true)新代码请用agent.streamEvents()返回FluxAgentEvent。技术栈技术版本Java17推荐 21Maven3.8Project Reactor2025.0.2 BOMJackson2.21.1OkHttp5.3.2DashScope SDK2.22.9OpenAI Java SDK4.28.0Anthropic Java SDK2.14.0Google GenAI SDK1.45.0MCP SDK0.17.0模块结构agentscope-java/ agentscope-core/ -- 核心框架ReActAgent、Model、Tool、Middleware、AgentState、AgentStateStore agentscope-harness/ -- HarnessAgent、工作区、沙箱、压缩、子 agent、技能、Plan Mode agentscope-extensions/ -- 扩展模块状态后端、RAG、Channel、Skill、Sandbox 等 agentscope-examples/ -- 示例代码 agentscope-dependencies-bom/ -- 依赖版本管理 agentscope-distribution/ -- 分发打包agentscope-bom2.0 之后生产应用请使用agentscope-harness学习 ReAct 循环的细节可以单独依赖agentscope-core状态持久化、多副本恢复等后端能力来自agentscope-extensions如agentscope-extensions-redis。1.2 环境准备前置条件JDK 17推荐使用 JDK 21Maven 3.8用于构建和依赖管理IDEIntelliJ IDEA 推荐API Key至少需要一个 LLM 服务的 API Key本教程使用 DeepSeek本教程统一使用DeepSeek作为示例模型OpenAI 兼容协议国内访问稳定、价格便宜。如果你用其他服务配置方法相同只是api-key/model-name/base-url不同。获取 DeepSeek API KeyDeepSeek框架内置支持的 LLM 服务任选其一即可服务商获取地址是否 OpenAI 兼容配置类DeepSeek本教程示例DeepSeek✅OpenAIChatModelbaseUrlOpenAIhttps://platform.openai.com/api-keys✅OpenAIChatModelDashScope通义千问阿里云登录 - 欢迎登录阿里云安全稳定的云计算服务平台❌ 专用协议DashScopeChatModelAnthropichttps://console.anthropic.com/❌ 专用协议AnthropicChatModelGoogle Geminihttps://aistudio.google.com/apikey❌ 专用协议GeminiChatModelOllama本地Ollama✅OpenAIChatModelbaseUrl1.3 安装框架到本地 Maven 仓库教程使用的版本是2.0.0-RC2仓库根pom.xml的revision。RC2 已发布到 Maven Central你可以在pom.xml中直接引入依赖无需本地编译dependency groupIdio.agentscope/groupId artifactIdagentscope-harness/artifactId version2.0.0-RC2/version /dependency如果你需要查看源码或自行修改编译也可以从 GitHub 拉源码在本地执行mvn install -DskipTests安装。1.3.1 克隆源码git clone https://github.com/agentscope-ai/agentscope-java.git cd agentscope-java git checkout v2.0.0-RC2 # 切到目标 tag没有 tag 就用 main 分支源码里有这些关键目录agentscope-core/— 核心框架ReActAgent、Middleware、AgentState、AgentStateStoreagentscope-harness/—HarnessAgent、工作区、压缩、子 agent、沙箱、技能、Plan Modeagentscope-extensions/— 扩展模块agentscope-extensions-redis等agentscope-distribution/— 生成agentscope-bom的地方agentscope-dependencies-bom/— 第三方依赖版本管理agentscope-examples/— 官方示例多 Agent 模式、生产部署等1.3.2 编译并安装在仓库根目录执行mvn install -DskipTests-DskipTests跳过所有模块的单元测试。首次安装会跑十几分钟要拉一堆三方依赖完成后所有io.agentscope:*工件都装进~/.m2/repository了。注意框架用revision2.0.0-RC2/revision这种动态版本号机制revision占位符所以要装根 POM 才能让 BOM 解析正常。如果只装agentscope-core不装根 POM会出现找不到 BOM的错。mvn install在根目录跑会按模块依赖顺序自动处理这个。1.3.3 验证安装是否成功ls ~/.m2/repository/io/agentscope/agentscope-harness/2.0.0-RC2/应该看到agentscope-harness-2.0.0-RC2.jar和.pom。再检查 BOMls ~/.m2/repository/io/agentscope/agentscope-bom/2.0.0-RC2/如果两个都在后面创建的应用项目才能正确解析依赖。1.3.4 常见问题Q: 报 Non-resolvable import POMA: 没装根 POM。在agentscope-java/根目录执行mvn install -DskipTests不要进子模块单独装。Q: 报 Could not find artifact io.agentscope:... 但 jar 文件明明在本地A: 缓存问题。执行mvn -U clean或在 IDE 里Reload All Maven Projects。Q: 后续git pull后代码更新了本地应用报找不到类A: 重新跑mvn install -DskipTests新版本的工件才能覆盖到本地。Q: 报Failed to execute goal com.diffplug.spotless:spotless-maven-plugin:...:check说几百个文件格式违规A: 这是Spotless 格式化检查失败不是代码错误。Windows 上最常见的原因是CRLF 换行符问题——git 检出时把 Unix 换行符LF自动转成了 Windows 换行符CRLFSpotless 期望 LF 所以报错。修复方法# 第一步让 Spotless 自动修复所有违规文件 mvn spotless:apply # 第二步重新编译 mvn install -DskipTestsmvn spotless:apply会扫描整个项目把所有文件的缩进、换行、import 顺序等按项目规范就地修复。如果用了 Windows git 且担心以后再犯可以关掉 git 的自动换行转换git config --global core.autocrlf false或者在项目根目录的.gitattributes文件里加一行* textauto eollf强制统一为 LF。1.4 创建项目使用 Maven 创建创建一个标准的 Maven 项目mkdir my-agent-app cd my-agent-apppom.xml2.0 推荐直接依赖agentscope-harness——它会传递引入agentscope-core和 Harness 自身的所有能力?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmy-agent-app/artifactId version1.0-SNAPSHOT/version packagingjar/packaging properties java.version17/java.version agentscope.version2.0.0-RC2/agentscope.version /properties dependencyManagement dependencies dependency groupIdio.agentscope/groupId artifactIdagentscope-bom/artifactId version${agentscope.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies !-- 2.0 推荐HarnessAgent 一站式入口 -- dependency groupIdio.agentscope/groupId artifactIdagentscope-harness/artifactId /dependency !-- 分布式状态后端生产用单机可省 -- dependency groupIdio.agentscope/groupId artifactIdagentscope-extensions-redis/artifactId /dependency /dependencies /project2.0 没有官方agentscope-spring-boot-starter1.x 那种开箱即用的 starter。Spring Boot 集成由你自由组合——HarnessAgent本身是个普通 Java 对象你可以用WebMvc包成 REST 接口、用CommandLineRunner启动时构建并注册到 IoC 容器或者用 Spring AI 的ChatClient风格自己写一层薄包装。详细见第九章 Spring Boot 集成。项目结构my-agent-app/ src/ main/ java/ com/example/ Application.java ← 启动入口构造 HarnessAgent controller/ ChatController.java ← 把 HarnessAgent 暴露为 HTTP 接口 resources/ application.yml ← 模型配置工作区路径 workspace/ ← HarnessAgent 的人格、记忆、技能文件运行时生成 AGENTS.md MEMORY.md pom.xml1.5 配置 LLM 模型HarnessAgent的 LLM 通过 Builder 模式配置核心就三件事字段含义DeepSeek 示例apiKey服务的 API 密钥${DEEPSEEK_API_KEY}modelName模型标识deepseek-chatbaseUrlAPI 服务地址https://api.deepseek.com1.5.1 配置 application.ymlapplication.yml写在src/main/resources/下agentscope: deepseek: api-key: ${DEEPSEEK_API_KEY:} model-name: deepseek-chat base-url: https://api.deepseek.com workspace: path: ./workspace2.0 没有了 1.x 的agentscope.spring.boot自动装配类。application.yml的字段由你自己解析——可以用 Spring 的ConfigurationProperties也可以在Application.java里直接new Yaml().loadAs(...)。设置环境变量# Windows PowerShell $env:DEEPSEEK_API_KEYsk-xxxxxxxx # Linux/macOS export DEEPSEEK_API_KEYsk-xxxxxxxxJava 代码里完全不用关心 api-key——构造Model时从环境变量/YAML 读OpenAIChatModel model OpenAIChatModel.builder() .apiKey(System.getenv(DEEPSEEK_API_KEY)) .modelName(deepseek-chat) .baseUrl(https://api.deepseek.com) .stream(true) .build();1.6 验证环境完整示例基于HarnessAgentsrc/main/java/com/example/Application.javapackage com.example; import io.agentscope.core.formatter.openai.OpenAIChatFormatter; import io.agentscope.core.model.OpenAIChatModel; import io.agentscope.harness.HarnessAgent; import io.agentscope.harness.HarnessConfig; public class Application { public static void main(String[] args) { String apiKey System.getenv(DEEPSEEK_API_KEY); OpenAIChatModel model OpenAIChatModel.builder() .apiKey(apiKey) .modelName(deepseek-chat) .baseUrl(https://api.deepseek.com) .stream(true) .formatter(new OpenAIChatFormatter()) .build(); HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(You are a helpful AI assistant. Be friendly and concise.) .model(model) .workspace(java.nio.file.Path.of(./workspace)) .build(); // 这里直接同步调用一次生产请用 Spring Controller 包成 HTTP 接口 String reply agent.call(你好请介绍一下自己) .block() .getTextContent(); System.out.println(Agent reply); } }启动# Windows PowerShell $env:DEEPSEEK_API_KEYsk-xxxxxxxx mvn exec:java -Dexec.mainClasscom.example.Application # Linux/macOS export DEEPSEEK_API_KEYsk-xxxxxxxx mvn exec:java -Dexec.mainClasscom.example.Application如果能看到 Agent 的回复说明环境搭建成功。2.0 起步的最小选择只学 ReAct 循环→ 依赖agentscope-core直接用ReActAgent.builder().build()。做生产/长期运行的应用→ 依赖agentscope-harness用HarnessAgent.builder().workspace(...).build()拿到工作区、Session、记忆、压缩、子 agent 等能力。后面的章节会逐步展开HarnessAgent的各项能力本章只验证它能跑起来。用其他模型改 YAML 改环境变量OpenAIChatModel支持所有 OpenAI 兼容服务。DeepSeek 也是改 YAML 配置出来的——api-key字段里的${DEEPSEEK_API_KEY:}是 Spring 的占位符启动时从环境变量读。换模型要做两件事改application.yml或Model的 Builder 参数里的api-key占位符 /model-name/base-url改环境变量名不同的服务商用不同的 key用官方 OpenAIOpenAIChatModel model OpenAIChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .modelName(gpt-4o-mini) .baseUrl(https://api.openai.com) .stream(true) .build();export OPENAI_API_KEYsk-xxxxxxxx用本地 OllamaOpenAIChatModel model OpenAIChatModel.builder() .apiKey(ollama) // Ollama 不校验 key .modelName(llama3) .baseUrl(http://localhost:11434) .build();Ollama 不用设环境变量。用 GLM智谱OpenAIChatModel model OpenAIChatModel.builder() .apiKey(System.getenv(GLM_API_KEY)) .modelName(glm-4-plus) .baseUrl(https://open.bigmodel.cn/api/paas/v4) .build();export GLM_API_KEYxxxxxxxxxxxxxxxx简单记Model Builder 管用哪家、哪个模型、什么地址环境变量管密钥。改模型改 Builder 改环境变量名Java 代码其它部分完全不动。1.7 框架核心概念速览在开始写代码之前先理解几个核心概念ReActAgent推理循环ReActAgent是 1.x 起就存在的核心类。agent.call(messages)跑一次思考 → 调用工具 → 观察结果 → 继续思考循环返回最终回复。所有Agent都基于ReActAgent——HarnessAgent也是ReActAgent的子类。HarnessAgent工程包装HarnessAgentReActAgent 一组叠加在循环关键时机上的 middleware工作区注入、压缩、记忆、子 agent、沙箱、Plan Mode。Builder 上每开一个能力就挂一个 middleware不写则默认行为。安装、依赖、跑通第一个HarnessAgent的端到端示例见快速开始。Msg消息Msg是 Agent 之间通信的基本单位。每条消息包含role角色USER、ASSISTANT、SYSTEM、TOOLcontent内容块列表文本、图像、工具调用等name发送者名称2.0 仍然保留Msg作为底层传输对象但业务代码里更推荐用具体子类型UserMessage/AssistantMessage/SystemMessage/ToolResultMessage类型更明确。Model模型Model接口封装了与 LLM 的交互。框架内置的支持OpenAIChatModelOpenAI 以及 DeepSeek、GLM、Ollama 等所有 OpenAI 兼容服务DashScopeChatModel通义千问AnthropicChatModelClaudeGeminiChatModelGoogle Gemini1.x 的OllamaChatModel专用协议在 2.0 不再单独提供——直接用OpenAIChatModelbaseUrlhttp://localhost:11434即可。Toolkit工具集Toolkit管理 Agent 可以调用的工具。通过Tool注解把 Java 方法注册为工具2.0 继续完整支持 1.x 的Tool/ToolParam语法。AgentStateAgentStateStore替代 1.x 的MemoryAgentState是 agent 当前瞬时运行状态的完整快照——对话历史、权限规则、Plan Mode 状态、todo 列表等。AgentStateStore把AgentState持久化到外部存储文件、Redis、MySQL……实现同sessionId跨进程、跨机器、跨副本地恢复会话。这是 2.0 取代 1.xMemory接口的统一抽象。SubagentDeclaration子 agent2.0 取代 Pipeline/MsgHub把子 agent 的 spec 写到workspace/subagents/id.md主 agent 就能在推理时通过agent_spawn委派。同步timeout_seconds 0默认 30 秒和后台timeout_seconds 0立即返回task_id两种模式后台任务完成时框架自动把结果作为系统提醒注入下一轮。Middleware2.0 取代 HookMiddleware/MiddlewareBase暴露 5 个钩子位置onAgent/onReasoning/onActing/onModelCall/onSystemPrompt在 ReAct 循环的关键时机插入逻辑。Hook接口在 2.0 仍可用Deprecated(forRemoval true)新代码请用Middleware。