快速开始¶

安装¶

AgentScope Java 需要 JDK 17 及以上版本，构建工具推荐 Maven 3.9+。

Maven 依赖¶

HarnessAgent 是推荐的入口，把工作区、长期记忆、会话持久化、子 agent、沙箱等工程能力打包在一个 builder 里；依赖 agentscope-harness 会自动把核心 agentscope-core 一并拉进来：

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

Note

当前最新版本为 2.0.0-RC1，把 ${agentscope.version} 替换为该值即可。完整发布说明见 GitHub Release Notes。

只想跑裸 ReActAgent（不需要工作区 / 持久化 / 子 agent / 沙箱），单独依赖 agentscope-core 即可。两种用法的区别详见 Harness 架构。

DashScope / OpenAI / Anthropic / Gemini / Ollama 的 formatter 与 chat model 都在 agentscope-core 里；MCP 集成需要官方 MCP SDK，参考 agentscope-examples/documentation/pom.xml。

源码构建¶

git clone -b main https://github.com/agentscope-ai/agentscope-java
cd agentscope-java
./mvnw -DskipTests install

第一个智能体¶

下面的例子用 HarnessAgent 跑通三件事：工作区驱动的人格（AGENTS.md）、会话自动持久化（相同 sessionId 的第二轮记得第一轮）、对话压缩（超阈值后自动压缩 + 长期事实落到 MEMORY.md）。模型 id 直接以字符串形式传给 .model(...)，由 ModelRegistry 解析并自动读取对应环境变量。

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；
                // 切换其他厂商时改用 "openai:gpt-5.5"、"anthropic:claude-sonnet-4-5"、
                // "gemini:gemini-2.0-flash" 或 "ollama:llama3"。
                .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();
    }
}

跑完之后你会看到工作区目录已经长出来了：

.agentscope/workspace/
├── AGENTS.md                    ← 写一份就是 agent 的人格（不写也能跑）
└── agents/note-taker/
    ├── context/demo-session/    ← AgentState 自动写回 / 加载
    └── sessions/                ← 永不压缩的原始对话日志

进程重启、sessionId 不变，第二段对话依然记得第一段——因为 AgentState 已经落在了 agents/note-taker/context/demo-session/ 下。多聊几轮触发压缩后，提炼出来的事实会先落到 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).getToolName());
            }
            // 其他事件：思考块、工具结果、回复结束等
        })
        .blockLast();

Tip

运行前在环境变量里设置 DASHSCOPE_API_KEY。切换厂商只需改 .model(...) 的字符串并设置对应的 API key（OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY）。需要更精细地控制超时 / 自定义 endpoint 等参数时，仍可显式 DashScopeChatModel.builder()...build() 构造实例后传给 .model(Model)。

接下来¶

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