2024最新AgentScope Java新手村从零开始完整教程：框架简介与环境搭建步骤详解

第一章 AgentScope Ja va 2.0 入门：从源码编译到第一个能对话的 Agent

你可能会问，AgentScope Ja va 是什么？简单来说，它是阿里巴巴开源的一个 Agent 编程框架，专门用来构建基于大语言模型（LLM）的智能体应用。而 2.0 版本，是一次意义重大的重构。在 1.x 的 ReAct 循环基础上，它抽出了一个独立的 HarnessAgent 层，把工作区、人格、长期记忆、子 Agent 编排、沙箱隔离、技能装配、计划模式这些都打包成了一个“工程就绪”的入口。同时，原来 1.x 那种“模块大杂烩”也被拆解成了清晰的核心与扩展。

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

2.0 的核心能力

先来看看 2.0 里都藏了哪些好东西：

• ReActAgent：核心推理循环（思考 → 调用工具 → 观察结果 → 继续思考），1.x 的核心类完全保留。
• HarnessAgent（推荐入口）：在 ReActAgent 之上的一层薄包装，把长期运行 Agent 必备的工程能力（工作区、Session、记忆、压缩、子 Agent、沙箱、技能、Plan Mode）用一个 Builder 串起来。
• 工具系统：通过 @Tool 注解将任意 Ja va 方法注册为 Agent 可调用的工具；工具元数据生成 JSON Schema 由 LLM 自动调用。
• 多模型支持：内置 OpenAI 协议（DeepSeek、GLM、Ollama 等所有 OpenAI 兼容服务）、DashScope（通义千问）、Anthropic Claude、Google Gemini。
• 会话与状态：AgentState + AgentStateStore 取代了 1.x 的 Memory 体系，跨进程、跨机器、跨副本的状态恢复统一由 AgentStateStore 后端承担（InMemoryAgentStateStore / JsonFileAgentStateStore / RedisAgentStateStore / MysqlAgentStateStore）。
• 子 Agent 编排（2.0 取代 Pipeline/MsgHub）：SubagentDeclaration 声明一个子 Agent，主 Agent 通过 agent_spawn 工具委派；支持同步（timeout_seconds > 0）和后台（timeout_seconds = 0），后台任务完成时自动反向通知。
• Middleware 体系（2.0 取代 Hook）：MiddlewareBase 暴露 5 个钩子位置（onAgent / onReasoning / onActing / onModelCall / onSystemPrompt），可在 ReAct 循环关键时机插入逻辑。
• 工作区驱动的人格：在 workspace/AGENTS.md 写人格、workspace/MEMORY.md 沉淀长期事实，workspace/subagents/.md 声明子 Agent，文件即配置。
• 结构化输出：让 Agent 返回指定 Ja va 类型的数据。
• MCP 集成：声明式 MCP server + 工具粒度允许/拒绝。

技术栈

模块结构

从源码层面看，项目模块划分得非常清晰：

• 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-bom）

简单总结一下：生产应用请使用 agentscope-harness；学习 ReAct 循环的细节可以单独依赖 agentscope-core；状态持久化、多副本恢复等后端能力则来自 agentscope-extensions（如 agentscope-extensions-redis）。

1.2 环境准备

前置条件

• JDK 17+：推荐使用 JDK 21
• Ma ven 3.8+：用于构建和依赖管理
• IDE：IntelliJ IDEA 推荐
• API Key：至少需要一个 LLM 服务的 API Key

本教程使用 DeepSeek

为了方便演示，本教程统一使用 DeepSeek 作为示例模型（OpenAI 兼容协议，国内访问稳定、价格便宜）。如果你用的是其他服务，配置方法也完全一样，只是 api-key、model-name 和 base-url 不同。

获取 DeepSeek API Key：https://platform.deepseek.com/api_keys

框架内置支持的 LLM 服务（任选其一即可）：

1.3 安装框架到本地 Ma ven 仓库

教程使用的版本是 2.0.0-RC2。好消息是，RC2 已经发布到 Ma ven Central 了，你可以在 pom.xml 中直接引入依赖，完全不需要本地编译：

    io.agentscope
    agentscope-harness
    2.0.0-RC2

当然，如果你需要查看源码或者自行修改编译，也可以从 GitHub 拉取源码，然后在本地执行 mvn install -DskipTests 安装。

1.3.1 克隆源码

git clone https://github.com/agentscope-ai/agentscope-ja va.git
cd agentscope-ja va
git checkout v2.0.0-RC2 # 切到目标 tag，没有 tag 就用 main 分支

源码里有这些关键目录，方便后续查阅：

• agentscope-core/ — 核心框架（ReActAgent、Middleware、AgentState、AgentStateStore）
• agentscope-harness/ — HarnessAgent、工作区、压缩、子 Agent、沙箱、技能、Plan Mode
• agentscope-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 了。

1.3.3 验证安装是否成功

执行以下命令检查：

ls ~/.m2/repository/io/agentscope/agentscope-harness/2.0.0-RC2/

应该能看到 agentscope-harness-2.0.0-RC2.jar 和 .pom 文件。再检查 BOM：

ls ~/.m2/repository/io/agentscope/agentscope-bom/2.0.0-RC2/

如果两个目录都存在，那么后面创建的应用项目就能正确解析依赖了。

1.3.4 常见问题

这里整理了新手可能遇到的几个典型问题：

Q: 报 "Non-resolvable import POM"
A: 多半是没装根 POM。在 agentscope-ja va/ 根目录执行 mvn install -DskipTests，不要进子模块单独装。

Q: 报 "Could not find artifact io.agentscope:..." 但 jar 文件明明在本地
A: 缓存问题。执行 mvn -U clean 或在 IDE 里 Reload All Ma ven Projects。

Q: 后续 git pull 后代码更新了，本地应用报找不到类
A: 重新跑 mvn install -DskipTests，新版本的工件才能覆盖到本地。

Q: 报 Failed to execute goal com.diffplug.spotless:spotless-ma ven-plugin:...:check，说几百个文件格式违规
A: 这是 Spotless 格式化检查失败，不是代码错误。Windows 上最常见的原因是 CRLF 换行符问题——git 检出时把 Unix 换行符（LF）自动转成了 Windows 换行符（CRLF），Spotless 期望 LF 所以报错。

修复方法：

# 第一步：让 Spotless 自动修复所有违规文件
mvn spotless:apply

# 第二步：重新编译
mvn install -DskipTests

mvn spotless:apply 会扫描整个项目，把所有文件的缩进、换行、import 顺序等按项目规范就地修复。
如果用了 Windows git 且担心以后再犯，可以关掉 git 的自动换行转换：

git config --global core.autocrlf false

或者在项目根目录的 .gitattributes 文件里加一行 * text=auto eol=lf 强制统一为 LF。

1.4 创建项目

使用 Ma ven 创建

先创建一个标准的 Ma ven 项目：

mkdir my-agent-app
cd my-agent-app

pom.xml

2.0 推荐直接依赖 agentscope-harness——它会传递引入 agentscope-core 和 Harness 自身的所有能力：

    4.0.0
    com.example
    my-agent-app
    1.0-SNAPSHOT
    jar

    
        17
        2.0.0-RC2
    

    
        
            
                io.agentscope
                agentscope-bom
                ${agentscope.version}
                pom
                import
            
        
    

    
        
        
            io.agentscope
            agentscope-harness
        
        
        
            io.agentscope
            agentscope-extensions-redis
        
    

项目结构

一个典型的项目结构如下：

my-agent-app/
├── src/main/ja va/com/example/
│   ├── Application.ja va          ← 启动入口，构造 HarnessAgent
│   └── controller/ChatController.ja va ← 把 HarnessAgent 暴露为 HTTP 接口
├── src/main/resources/
│   └── application.yml           ← 模型配置 + 工作区路径
├── workspace/                    ← HarnessAgent 的人格、记忆、技能文件（运行时生成）
│   ├── AGENTS.md
│   └── MEMORY.md
└── pom.xml

1.5 配置 LLM 模型

HarnessAgent 的 LLM 通过 Builder 模式配置，核心就三件事：

1.5.1 配置 application.yml

application.yml 写在 src/main/resources/ 下：

agentscope:
  deepseek:
    api-key: ${DEEPSEEK_API_KEY:}
    model-name: deepseek-chat
    base-url: https://api.deepseek.com
  workspace:
    path: ./workspace

设置环境变量：

# Windows PowerShell
$env:DEEPSEEK_API_KEY="sk-xxxxxxxx"

# Linux/macOS
export DEEPSEEK_API_KEY="sk-xxxxxxxx"

Ja va 代码里完全不用关心 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 验证环境

完整示例：基于 HarnessAgent

创建一个 src/main/ja va/com/example/Application.ja va：

package 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(ja va.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_KEY="sk-xxxxxxxx"
mvn exec:ja va -Dexec.mainClass="com.example.Application"

# Linux/macOS
export DEEPSEEK_API_KEY="sk-xxxxxxxx"
mvn exec:ja va -Dexec.mainClass="com.example.Application"

如果能看到 Agent 的回复，说明环境搭建成功了。

用其他模型？改 YAML + 改环境变量

OpenAIChatModel 支持所有 OpenAI 兼容服务。DeepSeek 也是改 YAML 配置出来的——api-key 字段里的 ${DEEPSEEK_API_KEY:} 是 Spring 的占位符，启动时从环境变量读。换模型要做两件事：

• 改 application.yml（或 Model 的 Builder 参数）里的 api-key 占位符 / model-name / base-url
• 改环境变量名（不同的服务商用不同的 key）

用官方 OpenAI：

OpenAIChatModel model = OpenAIChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("gpt-4o-mini")
    .baseUrl("https://api.openai.com")
    .stream(true)
    .build();

export OPENAI_API_KEY="sk-xxxxxxxx"

用本地 Ollama：

OpenAIChatModel 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_KEY="xxxxxxxxxxxxxxxx"

1.7 框架核心概念速览

在开始写代码之前，先快速过一遍几个核心概念，心里有个底。

ReActAgent（推理循环）

ReActAgent 是 1.x 起就存在的核心类。agent.call(messages) 跑一次"思考 → 调用工具 → 观察结果 → 继续思考"循环，返回最终回复。所有"Agent"都基于 ReActAgent——HarnessAgent 也是 ReActAgent 的子类。

HarnessAgent（工程包装）

HarnessAgent = ReActAgent + 一组叠加在循环关键时机上的 middleware（工作区注入、压缩、记忆、子 Agent、沙箱、Plan Mode）。Builder 上每开一个能力，就挂一个 middleware；不写则使用默认行为。

Msg（消息）

Msg 是 Agent 之间通信的基本单位。每条消息包含：

• role：角色（USER、ASSISTANT、SYSTEM、TOOL）
• content：内容块列表（文本、图像、工具调用等）
• name：发送者名称

2.0 仍然保留 Msg 作为底层传输对象，但业务代码里更推荐使用具体子类型 UserMessage / AssistantMessage / SystemMessage / ToolResultMessage，类型更明确。

Model（模型）

Model 接口封装了与 LLM 的交互。框架内置的支持：

• OpenAIChatModel（OpenAI 以及 DeepSeek、GLM、Ollama 等所有 OpenAI 兼容服务）
• DashScopeChatModel（通义千问）
• AnthropicChatModel（Claude）
• GeminiChatModel（Google Gemini）

Toolkit（工具集）

Toolkit 管理 Agent 可以调用的工具。通过 @Tool 注解把 Ja va 方法注册为工具；2.0 继续完整支持 1.x 的 @Tool / @ToolParam 语法。

AgentState + AgentStateStore（替代 1.x 的 Memory）

AgentState 是 Agent 当前"瞬时"运行状态的完整快照——对话历史、权限规则、Plan Mode 状态、todo 列表等。AgentStateStore 把 AgentState 持久化到外部存储（文件、Redis、MySQL……），实现"同 sessionId 跨进程、跨机器、跨副本"地恢复会话。这是 2.0 取代 1.x Memory 接口的统一抽象。

SubagentDeclaration（子 Agent，2.0 取代 Pipeline/MsgHub）

把子 Agent 的 spec 写到 workspace/subagents/.md，主 Agent 就能在推理时通过 agent_spawn 委派。同步（timeout_seconds > 0，默认 30 秒）和后台（timeout_seconds = 0，立即返回 task_id）两种模式；后台任务完成时框架自动把结果作为系统提醒注入下一轮。

Middleware（2.0 取代 Hook）

Middleware / MiddlewareBase 暴露 5 个钩子位置（onAgent / onReasoning / onActing / onModelCall / onSystemPrompt），在 ReAct 循环的关键时机插入逻辑。需要注意的是，Hook 接口在 2.0 仍可用（已标记 @Deprecated(forRemoval = true)），新代码请使用 Middleware。