一、前言

AgentScope Java 是阿里巴巴通义实验室推出的面向生产环境的智能体工程网站。不过，其 Quick Start 文档以极简的方法。展示了从环境搭建到多使用者并发服务的完整链路。

二、环境准备与安装

基础要求

依赖项	最低版本
JDK	17+
Maven	3.+

Maven 依赖配置

AgentScope 采用模块化依赖设计主要入口为 agentscope-harness

io.agentscope
agentscope-harness
${agentscope.version}

If you only need bare ReActAgent framework API。just include agentscope-core. The model extension modules are independent and should be added as needed. For example,using DashScope:

io.agentscope
agentscope-extensions-model-dashscope
${agentscope.version}

模块依赖关系

agentscope-harness
└── agentscope-core
└── agentscope-extensions-model-*
├── dashscope
├── openai
├── anthropic
├── gemini
└── ollama

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

使用者痛点： 在实际项目中，往往需要同时处理人格设定、会话持久化和长期记忆压缩，却常因缺少统一入口而导致代码散落多个模块。下面的示例一次性展示这三大主要能力。

能力	说明
工作区驱动的人格	通过文件定义 Agent 人格，实现可编辑、版本化管理。
会话自动持久化	第二轮调用自动恢复上下文，无需手动保存状态。
长期记忆压缩	对话超阈值后自动压缩，将事实抽取到长期记忆文件。

完整代码示例

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 {
HarnessAgent agent = HarnessAgent.builder
.name
.sysPrompt
// 字符串形式由 ModelRegistry 解析 —— 自动读取 DASHSCOPE_API_KEY
.model
.workspace)
.compaction
.triggerMessages // 超过阈值触发压缩
.keepMessages // 保留最近 N 条消息
.build)
.build;
RuntimeContext ctx = RuntimeContext.builder
.sessionId
.userId
.build;// 第一轮：自我介绍 + 当天的事
agent.call,ctx).block;// 第二轮：同 sessionId。自动恢复上一轮状态后回答
agent.call,ctx).block;}
}

关键设计解析

#模型切换极简#：.model 以字符串形式传入，由 ModelRegistry 自动解析并读取对应环境变量。话说回来，切换厂商只需修改字符串：

.model
.model
.model
.model

#压缩策略配置#：

CompactionConfig.builder
.triggerMessages // 消息数达到阈值时触发压缩
.keepMessages // 压缩后保留最近 N 条
.build;

运行后的目录结构

.agentscope/workspace/ ← 工作区
├── AGENTS.md ← Agent 人格定义
└── agents/
└── note-taker/
└── sessions/ ← 永不压缩的原始对话日志
~/.agentscope/state/note-taker/
└── alice/
└── demo-session/
└── agent_state.json ← AgentState 自动写回/加载

记忆压缩流转过程

对话消息
↓ 自动压缩 → workspace/memory/YYYY-MM-DD.md ← 提炼出的事实
↓ 周期性合并 → MEMORY.md ← 长期记忆库
↓ 下一轮推理时注入 system prompt ← 决策依据提高准确性

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

If you need real‑time feedback,replace .call with .streamEvents. The following snippet prints text deltas and tool‑call markers on fly.

import io.agentscope.core.event.AgentEventType;import io.agentscope.core.event.TextBlockDeltaEvent;import io.agentsscope.core.event.ToolCallStartEvent;agent.streamEvents)
.doOnNext(event -> {
if == AgentEventType.TEXT_BLOCK_DELTA) {
System.out.print event).getDelta);} else if == AgentEventType.TOOL_CALL_START) {
System.out.println event).getToolCallName);}
// or events: thinking blocks。tool results,finish...
})
.blockLast;

#事件类型一览#：

事件类型	说明
TEXTBLOCKDELTA	LLM 返回的逐块文字。
T TOOLCALLSTART	Cue that a tool will be invoked.

五、多使用者并发：无状态设计"

This is core production‑grade architectural decision of AgentScope:

The Agent itself is stateless 娱乐ween calls—one instance can serve requests from different users and sessions concurrently.

" "实现方式——RuntimeContext 隔离上下文 // 应用启动时创建单例实例 HarnessAgent agent = HarnessAgent.builder .name .sysPrompt .model .workspace ) .compaction .triggerMessages .keepMessages .build) .build;// HTTP handler 示例——每个请求携带独立 RuntimeContext agent.call( new UserMessage,RuntimeContext.builder .sessionId .userId .build) .block;

并发安全保证

ad> tr> /ad> tbody> tr> tr> /tbody> /table>

六、生产环境注意事项

状态存储选型

场景	行为	同一 的并发请求	自动串行化，避免状态竞争	不同 session 的请求	完全并行。互不干扰

环境	推荐方法
开发 / 单机	JsonFileAgentStateStore
生产集群	RedisAgentStateStore或自定义实现 AgentStateStore 接口

/blockquote>

环境变量配置

模型提供商	环境变量名
DashScope	DASHSCOPEAPIKEY
OpenAI	OPENAIAPIKEY
Anthropic > ANTHROPICAPIKEY < /t d>/t r>/tbody>/table

七、进阶学习方法

。

---