AgentScope 2.0：2. 快速上手从零构建生产级智能体

mqiqe

738人浏览 · 2026-08-08 17:45:00

mqiqe · 2026-08-08 17:45:00 发布

目录：
1. 面向生产环境的智能体工程平台
2. 快速上手从零构建生产级智能体
3. Agent —— 智能体的核心抽象与工程化实践
4. Message & Event —— 消息模型与事件流深度解
5. Middleware —— 无侵入式智能体扩展机制深度解析
6. Model —— 统一模型接入层与容错机制深度解析
7. Permission System —— 权限控制系统深度解析
8. Tool —— 工具系统架构与生产级实践深度解析
9. Context —— 运行时上下文与状态管理深度解析

一、前言

AgentScope Java 2.0 是阿里巴巴通义实验室推出的面向生产环境的智能体工程平台。其 Quick Start 文档以极简的路径，展示了从环境搭建到多用户并发服务的完整链路。本文将基于官方文档内容，系统梳理 AgentScope 2.0 的快速上手流程，并深入解析其核心设计思想。

二、环境准备与安装

2.1 基础要求

依赖项	最低版本
JDK	17+
Maven	3.9+（推荐）

2.2 Maven 依赖配置

AgentScope 2.0 采用模块化依赖设计，核心入口为 agentscope-harness：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>${agentscope.version}</version>
</dependency>

设计要点：HarnessAgent 是推荐的入口类，它将工作区、长期记忆、会话持久化、子 Agent、沙箱等工程能力打包在一个 Builder 中。依赖 agentscope-harness 会自动引入核心 agentscope-core。

如果只需要裸 ReActAgent 的框架 API（不需要工作区/持久化/子 Agent/沙箱），仅引入 agentscope-core 即可。
模型扩展模块是独立的，需按需引入。例如使用 DashScope：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-dashscope</artifactId>
    <version>${agentscope.version}</version>
</dependency>

2.3 模块依赖关系

agentscope-harness
  └── agentscope-core（自动传递）
        └── agentscope-extensions-model-*（按需引入）
              ├── dashscope
              ├── openai
              ├── anthropic
              ├── gemini
              └── ollama

三、第一个智能体：三合一能力演示

官方 Quick Start 通过一个精炼示例，同时展示了三大核心能力：

能力	说明
工作区驱动的人格	通过 AGENTS.md 定义 Agent 人格
会话自动持久化	相同 sessionId 的第二轮自动恢复上下文
对话压缩	超阈值后自动压缩，长期事实落入 MEMORY.md

3.1 完整代码示例

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import io.agentscope.harness.agent.memory.compaction.CompactionConfig;
import java.nio.file.Paths;

public class FirstAgent {
    public static void main(String[] args) {
        HarnessAgent agent = HarnessAgent.builder()
                .name("note-taker")
                .sysPrompt("你是一个帮助用户做笔记的助手。")
                // 字符串形式由 ModelRegistry 解析 —— 自动读取 DASHSCOPE_API_KEY
                .model("dashscope:qwen-plus")
                .workspace(Paths.get(".agentscope/workspace"))
                .compaction(CompactionConfig.builder()
                        .triggerMessages(30)
                        .keepMessages(10)
                        .build())
                .build();

        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId("demo-session")
                .userId("alice")
                .build();

        // 第一轮：自我介绍 + 当天的事
        agent.call(new UserMessage("我叫天宇，今天准备一个关于 ReAct 的技术分享。"), ctx).block();
        // 第二轮：同 sessionId，自动恢复上一轮状态后回答
        agent.call(new UserMessage("我叫什么？我今天要干什么？"), ctx).block();
    }
}

3.2 关键设计解析

模型切换极简：.model(“dashscope:qwen-plus”) 以字符串形式传入，由 ModelRegistry 解析并自动读取对应环境变量。切换厂商只需修改字符串：

.model("openai:gpt-5.5")
.model("anthropic:claude-sonnet-4-5")
.model("gemini:gemini-2.0-flash")
.model("ollama:llama3")

压缩策略配置：

CompactionConfig.builder()
    .triggerMessages(30)   // 消息数达到 30 条时触发压缩
    .keepMessages(10)      // 压缩后保留最近 10 条
    .build()

3.3 运行后的目录结构

运行后自动生成两棵目录树：

.agentscope/workspace/                          ← 工作区（Agent 内容）
├── AGENTS.md                                   ← Agent 人格定义
└── agents/note-taker/
    └── sessions/                               ← 永不压缩的原始对话日志

~/.agentscope/state/note-taker/                 ← 状态存储（工作区之外）
└── alice/demo-session/                         ← AgentState 自动写回/加载
    └── agent_state.json

架构要点：AgentState 默认存储在工作区之外的 ~/.agentscope/state// 下。这是因为状态是恢复工作区本身的前提条件（例如沙箱清空后需要先有状态才能重建工作区），不能和工作区数据耦合。

3.4 记忆压缩流转

多轮对话触发压缩后的数据流转：

对话消息（超阈值）
    ↓ 自动压缩
workspace/memory/YYYY-MM-DD.md    ← 提炼出的事实
    ↓ 周期性合并
MEMORY.md                          ← 长期记忆
    ↓ 下一轮推理时
自动注入 system prompt              ← 影响后续行为

四、流式输出：实时查看推理与工具调用

将 call(…) 替换为 streamEvents(…) 即可获取实时事件流，适用于 Web/TUI 渲染场景：

import io.agentscope.core.event.AgentEventType;
import io.agentscope.core.event.TextBlockDeltaEvent;
import io.agentscope.core.event.ToolCallStartEvent;

agent.streamEvents(new UserMessage("帮我把今天的关键点列三条。"))
        .doOnNext(event -> {
            if (event.getType() == AgentEventType.TEXT_BLOCK_DELTA) {
                // 模型返回的流式文本片段
                System.out.print(((TextBlockDeltaEvent) event).getDelta());
            } else if (event.getType() == AgentEventType.TOOL_CALL_START) {
                // 智能体即将调用工具
                System.out.println("\n[tool] " + ((ToolCallStartEvent) event).getToolCallName());
            }
            // 其他事件：思考块、工具结果、回复结束等
        })
        .blockLast();

事件类型一览

事件类型	说明
TEXT_BLOCK_DELTA	模型流式文本片段
TOOL_CALL_START	工具调用开始
思考块事件	模型推理过程
工具结果事件	工具执行返回
回复结束事件	本轮推理完成

五、多用户并发：无状态设计

这是 AgentScope 2.0 面向生产环境的核心架构决策：

Agent 在调用之间是无状态的——同一个实例可以处理不同用户、不同会话的请求。

5.1 实现方式

通过 RuntimeContext 传入 userId / sessionId，每次调用自动加载并隔离各自的对话上下文：

// 应用启动时创建一个 Agent 实例（单例即可）
HarnessAgent agent = HarnessAgent.builder()
        .name("note-taker")
        .sysPrompt("你是一个帮助用户做笔记的助手。")
        .model("dashscope:qwen-plus")
        .workspace(Paths.get(".agentscope/workspace"))
        .compaction(CompactionConfig.builder()
                .triggerMessages(30)
                .keepMessages(10)
                .build())
        .build();

// 在 HTTP handler 中——不同请求传入不同 RuntimeContext
agent.call(new UserMessage(userInput), RuntimeContext.builder()
        .sessionId(sessionId)
        .userId(userId)
        .build()).block();

5.2 并发安全保证

场景	行为
同一 (userId, sessionId) 的并发请求	自动串行化，不会并发写同一份状态
不同 session 的请求	完全并行，互不干扰

六、生产环境注意事项

6.1 状态存储选型

环境	推荐方案
开发/单机	JsonFileAgentStateStore（默认）
生产集群	RedisAgentStateStore（由 agentscope-extensions-redis 提供）
自定义	实现 AgentStateStore 接口

⚠️ 重要警告：默认的 JsonFileAgentStateStore 是基于本地文件的实现，仅适用于开发和单机部署。生产集群环境必须使用分布式实现。

6.2 环境变量配置

模型提供商	环境变量
DashScope	DASHSCOPE_API_KEY
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Gemini	GEMINI_API_KEY

七、进阶学习路径

Quick Start 完成后，官方推荐的深入方向：

主题	内容
智能体（Agent）	ReActAgent 完整接口、参数、call/streamEvents/observe、人机交互、AgentStateStore 配置
Harness 架构	HarnessAgent 各项能力如何协作、状态如何流转
工作区	AGENTS.md/MEMORY.md/skills//subagents//tools.json 的目录布局与加载机制
文件系统	本机 + shell / 共享存储 / 沙箱三种部署模式