本文展示了如何使用 AgentScope-Java 库创建一个具备工具调用能力的、支持流式响应的 ReAct Agent。

一、开发示例

下面实现了一个名为 Friday 的命令行 AI 助手。它能理解用户的自然语言指令，并在需要时调用 get_time、get_random 或 echo 等工具来完成任务。

其核心亮点在于利用了模型的流式输出能力，将 Agent 的思考过程、工具调用和最终结果以数据流的形式实时地、分块地展示给用户，提供了比传统一次性问答更佳的交互体验。

import com.google.gson.Gson;
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.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import reactor.core.publisher.Flux;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Random;

/**
* 带有 3 个简单工具的 ReActAgent 示例。单个用户请求可以触发多个工具。工具包括：
* 1) get_time(zone): 返回当前时间字符串
* 2) get_random(min,max): 返回 [min, max] 范围内的随机整数
* 3) echo(text): 回显给定的文本
*/
public class ReActAgentWithToolsStreamExample {
 // 日志记录器，用于输出日志信息
 private static final Logger log = LoggerFactory.getLogger(ReActAgentWithToolsExample.class);
 // 定义简单工具类，包含三个工具方法
 public static class SimpleTools {
 // 获取当前时间的工具方法
 @Tool(name = "get_time", description = "Get current time string")
 public String getTime() {
 LocalDateTime now = LocalDateTime.now();
 return now.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
 }
 // 获取随机数的工具方法
 @Tool(name = "get_random", description = "Get a random integer in [min, max]")
 public int getRandom(
 @ToolParam(description = "Min value", required = true) Integer min,
 @ToolParam(description = "Max value", required = true) Integer max) {
 // 设置默认值，如果参数为空则使用默认值
 int lo = min != null ? min : 0;
 int hi = max != null ? max : 100;
 // 确保最小值小于最大值
 if (hi < lo) {
 int t = lo; lo = hi; hi = t;
 }
 // 生成并返回随机数
 return lo + new Random().nextInt(hi - lo + 1);
 }

 // 回显文本的工具方法
 @Tool(name = "echo", description = "Echo back the given text")
 public String echo(@ToolParam(description = "Text to echo", required = true) String text) {
 return text == null ? "" : text;
 }
 }

 public static void main(String[] args) throws Exception {
 // 从环境变量获取 DashScope API 密钥
 String dashApiKey = System.getenv("DASHSCOPE_API_KEY");
 if (dashApiKey == null || dashApiKey.isEmpty()) {
 log.warn("未找到 API 密钥。请设置 DASHSCOPE_API_KEY 环境变量。");
 return;
 }
 // 创建工具包实例
 Toolkit toolkit = new Toolkit();
 // 将自定义工具类注册到工具包中
 toolkit.registerTool(new SimpleTools());
 // 创建内存管理器，用于存储对话历史
 InMemoryMemory memory = new InMemoryMemory();
 // 使用建造者模式构建 ReAct Agent
 ReActAgent agent = ReActAgent.builder()
 .name("Friday") // 设置Agent名称为 Friday
 .sysPrompt("You are a helpful assistant named Friday. You can call tools in parallel when needed.") // 设置系统提示词
 .toolkit(toolkit) // 设置工具包
 .memory(memory) // 设置内存管理器
 .model(DashScopeChatModel.builder() // 配置 DashScope 聊天模型
 .apiKey(dashApiKey) // 设置 API 密钥
 .modelName("qwen-max") // 设置模型名称
 .stream(true) // 启用流式输出
 .enableThinking(false) // 禁用思考模式
 .defaultOptions(new GenerateOptions()) // 设置默认生成选项
 .build())
 .formatter(new DashScopeChatFormatter()) // 设置消息格式化器
 .parallelToolCalls(true) // 启用并行工具调用
 .build();

 // 创建缓冲读取器，从标准输入读取用户输入
 BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
 // 进入交互循环，直到用户输入 "exit" 退出
 while (true) {
 System.out.print("User> "); // 显示用户输入提示符
 String line = reader.readLine(); // 读取用户输入
 if (line == null || "exit".equalsIgnoreCase(line.trim())) {
 break;
 }
 // 创建用户消息对象，将用户的输入行封装起来
 Msg userMsg = Msg.builder().role(MsgRole.USER).textContent(line).build();
 // 调用 agent 的 stream 方法，传入用户消息，获取一个响应式流（Flux）
 // 由于模型配置中 stream=true，所以这里返回的是一个流
 Flux<Msg> stream = agent.stream(userMsg);
 // 订阅流并处理其中的每个消息
 // doOnNext: 每当流中发出一个新消息(msg)时，就执行lambda表达式
 // lambda表达式: 将消息对象转换为JSON字符串，并以"Friday> "为前缀打印到控制台
 // blockLast: 阻塞当前线程，直到流发出最后一个元素并完成。这确保在所有流式响应都打印完毕之前，程序不会继续执行下一次循环
 stream.doOnNext(msg -> System.out.println("Friday> " + new Gson().toJson(msg))).blockLast();
 }
 // 输出退出日志
 log.info("Bye.");
 }
}

二、代码说明

1. SimpleTools 内部类

这个静态内部类定义了一组可供 Agent 调用的工具。

@Tool 注解：将一个方法标记为工具，并提供名称和描述。Agent 会根据这些信息决定何时以及如何使用该工具。

@ToolParam 注解：描述工具方法的参数。

它包含了三个工具方法：

• getTime(): 获取当前格式化的时间字符串。
• getRandom(min, max): 在指定范围内生成一个随机整数。
• echo(text): 原样返回输入的文本。

2. main 方法

环境设置：第一，它会检查并获取名为 DASHSCOPE_API_KEY 的环境变量，这是调用通义千问模型所必需的 API 密钥。

Agent 构建：使用建造者模式（Builder Pattern）来配置一个 ReActAgent。

• name(“Friday”): 为 Agent 命名。
• sysPrompt(…): 设置系统提示词，指导 Agent 的行为和角色。
• toolkit(…): 将前面定义的 SimpleTools 实例注册到 Agent 的工具包中，使其能够调用这些工具。
• memory(…): 配置一个 InMemoryMemory，用于存储对话历史。
• model(…): 配置 Agent 使用的大语言模型。这里使用的是阿里云的通义千问（DashScopeChatModel）。
• stream(true): 这是一个关键配置。它启用了模型的流式输出功能。这意味着模型会以数据流的形式，一块一块地返回响应，而不是一次性生成全部内容。
• parallelToolCalls(true): 允许 Agent 在需要时并行调用多个工具。

3. 流式处理

Msg userMsg = …: 将用户的输入封装成一个 Msg 对象。

Flux<Msg> stream = agent.stream(userMsg);: 调用 Agent 的 stream 方法。由于模型配置了 stream(true)，此方法返回一个 Flux<Msg>。Flux 是一个来自 Project Reactor 库的响应式流发布者，它会随着时间的推移异步地发出零个或多个 Msg 片段。

stream.doOnNext(…).blockLast();: 这行代码订阅并处理这个流。

doOnNext(): 为流中的每一个元素（即每一个消息块 msg）注册一个回调。每当 Agent 返回一个新的消息块时，这个回调就会被触发，将消息块转换成 JSON 格式并打印到控制台。

blockLast(): 阻塞当前线程，直到流处理完成。这确保了在所有响应内容都打印完毕之前，程序不会立即再次提示用户输入。

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