AgentScope Java 开发入门：创建一个简单的ReAct Agent 示例

AgentScope 近期发布了 Java 实现。请注意，该项目仍在实验阶段，并处于积极开发中。

为什么选择 AgentScope？

对新手友善，对专家强劲。
对开发者透明：透明是我们首要原则。提示工程、API 调用、智能体构建、工作流编排等，对开发者都是可见且可控的。没有深度封装或隐式魔法。
实时控制：原生支持实时中断和自定义处理。
更具智能体特性：支持智能体工具管理、智能体长期记忆控制和智能体 RAG 等。
模型无关性：一次编程，运行所有模型。
乐高式智能体构建：所有组件都是模块化的、独立的。
面向多智能体：专为多智能体设计，明确的消息传递和工作流编排，不进行深度封装。
高度可定制：工具、提示、智能体、工作流、第三

一、引入AgentScope Core依赖包

这个 Maven 依赖配置引入了 AgentScope 框架的核心库。

 <!-- AgentScope Core - Main dependency -->
 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-core</artifactId>
 <version>0.1.0</version>
 <exclusions>
 <exclusion>
 <artifactId>slf4j-simple</artifactId>
 <groupId>org.slf4j</groupId>
 </exclusion>
 </exclusions>
 </dependency>

AgentScope Core 提供以下核心功能：

Agent 架构: ReAct、Multi-Agent 等智能体模式
模型集成: 支持多种 LLM 模型（OpenAI、DashScope 等）
工具调用: Toolkit 工具包系统
内存管理: 对话历史和上下文管理
消息处理: 结构化消息格式和处理流程

这是构建 AI Agent 应用的核心依赖，为整个项目提供了 AI 智能体开发的基础设施。

二、创建ReAct Agent 入门示例

下面这段代码是一个基于 Java 的 ReAct Agent 示例程序，用于创建一个智能对话助手。

这是一个命令行交互式 AI 助手，使用阿里云的 DashScope API 作为底层语言模型，实现了 ReAct（Reasoning and Acting）架构的智能体。

import io.agentscope.core.ReActAgent;
import io.agentscope.core.formatter.DashScopeChatFormatter;
import io.agentscope.core.memory.InMemoryMemory;
import io.agentscope.core.message.Msg;
import io.agentscope.core.message.MsgRole;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.model.GenerateOptions;
import io.agentscope.core.tool.Toolkit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.BufferedReader;
import java.io.InputStreamReader;

/**
* 一个最小的 ReAct Agent示例，模仿 Python react_agent 示例。
*
* - 如果设置了 DASHSCOPE_API_KEY，默认使用 DashScope；否则如果设置了 OPENAI_API_KEY，则使用 OpenAI。
* - 从终端读取用户输入；输入 "exit" 退出。
*/
public class ReActAgentExample {

 // 日志记录器，用于输出日志信息
 private static final Logger log = LoggerFactory.getLogger(ReActAgentExample.class);

 public static void main(String[] args) throws Exception {
 // 从环境变量中获取 DashScope API 密钥
 String dashApiKey = System.getenv("DASHSCOPE_API_KEY");

 // 检查 API 密钥是否存在，如果不存在则退出程序
 if (dashApiKey == null || dashApiKey.isEmpty()) {
 log.warn("No API key found. Please set DASHSCOPE_API_KEY.");
 return;
 }

 // 初始化工具包，用于提供智能体可以使用的工具
 Toolkit toolkit = new Toolkit();
 // 初始化内存管理器，用于存储对话历史
 InMemoryMemory memory = new InMemoryMemory();

 // 使用建造者模式创建 ReActAgent
 ReActAgent.Builder builder = ReActAgent.builder()
 .name("Friday") // 设置Agent名称为 Friday
 .sysPrompt("You are a helpful assistant named Friday.") // 设置系统提示词
 .toolkit(toolkit) // 设置工具包
 .memory(memory) // 设置内存管理器
 .model(DashScopeChatModel.builder() // 配置 DashScope 聊天模型
 .apiKey(dashApiKey) // 设置 API 密钥
 .modelName("qwen-max") // 设置模型名称
 .stream(true) // 启用流式输出
 .enableThinking(false) // 禁用思考模式，Agent不会显示内部推理过程
 .defaultOptions(new GenerateOptions()) // 设置默认生成选项，用于控制模型生成行为
 .build()) // 构建 DashScope 聊天模型实例
 .formatter(new DashScopeChatFormatter()); // 设置消息格式化器，用于格式化与 DashScope 的交互消息

 // 构建 ReActAgent 实例
 ReActAgent agent = builder.build();

 // 创建缓冲读取器，用于从标准输入读取用户输入
 BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
 // 开始主循环，持续处理用户输入
 while (true) {
 System.out.print("User> "); // 显示用户输入提示符
 String line = reader.readLine(); // 读取用户输入的一行文本
 // 检查是否需要退出：输入为空（Ctrl+D）或输入 "exit"
 if (line == null || "exit".equalsIgnoreCase(line.trim())) {
 break; // 退出循环
 }
 // 构建用户消息对象，设置角色为用户，内容为输入的文本
 Msg userMsg = Msg.builder().role(MsgRole.USER).textContent(line).build();
 // 让Agent处理用户消息并获取回复，使用 block() 同步等待结果
 Msg msg = agent.reply(userMsg).block();
 // 输出Agent的回复内容
 System.out.println("Friday> " + msg.getContentAsText());
 }

 // 程序结束时输出告别信息
 log.info("Bye.");
 }
}

代码说明：

1. 环境检查与配置

从环境变量 DASHSCOPE_API_KEY 获取 API 密钥；如果密钥不存在，程序会警告并退出。

2. Agent 架构组件

Toolkit: 工具包，为Agent提供可调用的工具功能
InMemoryMemory: 内存管理器，存储对话历史上下文
DashScopeChatModel: 使用阿里云千问模型作为语言理解和生成引擎
DashScopeChatFormatter: 消息格式化器，处理与 API 的消息交互格式

3. Agent 配置

Agent名称：Friday
系统提示词：定义Agent的行为特征
模型配置：使用 qwen-max 模型，启用流式输出，禁用思考模式显示

4. 交互循环

程序进入无限循环，持续处理用户输入：

第一，显示 User> 提示符等待输入，然后读取用户输入的文本，并检查退出条件（输入 “exit” 或 Ctrl+D）。

接着，将用户输入包装成消息对象，调用Agent 的 reply() 方法获取响应，并显示Agent 回复，格式为 Friday> [回复内容]。

5. 程序终止

当用户选择退出时，程序输出告别信息并结束。

技术特点：

使用建造者Builder 模式构建复杂对象
采用响应式编程（Reactive）的 block() 方法同步等待异步结果
集成了完整的 AI Agent 架构：推理、行动、记忆和工具调用能力
支持流式输出，提供更好的用户体验
这个示例展示了如何使用 AgentScope 框架快速构建一个功能完整的 AI 对话助手。

三、测试验证

启动示例程序，进行测试验证。

User> 请介绍你自己
Friday> 你好！我是Friday，一个由阿里云开发的AI助手。我被设计用来协助用户生成各种类型的文本，如文章、故事、诗歌、故事等，并且能够根据用户的指示调整写作风格和内容。无论是创意写作还是实用文档，我都能提供支持。此外，我还能够回答关于广泛话题的问题，提供信息查询服务。我的目标是成为一个多才多艺的助手，无论你需要什么样的协助，只要告知我，我都会尽力而为。很高兴遇见你，希望我们能有愉快的合作！
User> exit
15:16:20.263 [main] Bye.

#秋日生活打卡季##AgentScope#