02.AgentScope Java 2.0 核心推理引擎 ReActAgent
同样是调大模型,ReActAgent 能自己决定"缺什么查什么",你的 LLM 还在背答案
2.AgentScope Java 2.0 ReActAgent 核心拆解:推理循环、工具调用与实战
上一篇文章我们搭建了 AgentScope Java 2.0 的环境,并跑通了第一个 HarnessAgent 对话。细心的同学可能注意到,我们在 demo 中用了 HarnessAgent.builder(),但我当时说了一句"HarnessAgent 是在 ReActAgent 之上的薄包装"。
那么问题来了——这个 ReActAgent 到底是啥?它和普通的 LLM API 调用有啥区别?那个所谓的"思考→调用工具→观察结果→继续思考"的循环到底是怎么转起来的?
今天我们就来拆解 AgentScope Java 2.0 的核心引擎——ReActAgent。理解了这个循环,你就掌握了智能体的心脏。
一、先搞懂:ReAct 模式是啥?
一般来讲,当我们在 Java 中调用大模型 API 时,最常见的使用姿势是这样的:
// 普通的 LLM API 调用 —— 一问一答,完事
String response = chatModel.call("今天天气怎么样?");
// 拿到回答就结束了,模型不会反问、不会自己查资料、不会反复思考
这种"一问一答"的模式虽然简单,但是有个硬伤——模型只能靠自己的训练知识回答问题。如果我问"今天北京的温度比昨天高多少?",模型得先查到今天和昨天的温度,再做减法。但在普通的 API 调用中,模型无法主动去"查"任何外部数据。
ReAct(Reasoning + Acting) 模式就是来解决这个问题的。它的核心理念很简单:
让 LLM 在"推理"和"行动"之间循环切换——推理决定下一步做什么,行动去调用外部工具获取信息,然后根据结果继续推理,直到得出最终答案。
这个循环用流程图表示如下:
┌───────────────┐
│ 收到用户输入 │
└───────┬───────┘
▼
┌───────────────┐
│ 思考(Reason) │◄────────────┐
│ "我需要查..." │ │
└───────┬───────┘ │
▼ │
┌───────────────┐ │
│ 行动(Act) │ │
│ 调用工具获取信息 │ │
└───────┬───────┘ │
▼ │
┌───────────────┐ │
│ 观察(Observe) │───────────────┘
│ 拿到工具结果 │ 继续推理
└───────┬───────┘
▼
┌───────────────┐
│ 得出最终答案 │
└───────────────┘
简单来讲:ReAct 让 LLM 不仅仅是一个"问答机器",而是一个具备"动手能力"的智能体——它能自己决定什么时候需要查资料、查什么、怎么用查到的结果。这就是 Agent 和普通 LLM 调用的本质区别。
1. 一个直观的理解
想象一下你让一个实习生去完成任务:
- 普通 LLM 调用 = 你问实习生一个问题,他只能凭自己的记忆回答,不知道的就说不知道
- ReAct Agent = 实习生不仅回答问题,还会自己主动去翻文档、查数据库、跑脚本,然后把查到的信息综合起来给你一个完整的答案
AgentScope Java 2.0 中的 ReActAgent 就是这个"实习生的大脑"——它负责控制整个思考-行动循环的节奏。
二、ReActAgent 的核心执行流程
AgentScope Java 2.0 的 ReActAgent 在每次 call 调用时运行一套完整的推理-行动循环。官方文档给出了非常清晰的主循环流程图,我将其转化为更容易理解的执行步骤:
输入消息
│
▼
┌─────────────────────────────────────────────────┐
│ Step 1: 将消息添加到上下文(Context) │
│ - 把用户输入追加到对话历史 │
└─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Step 2: 检查下一步动作(Next Action) │
│ - 是继续推理?还是退出/暂停? │
└─────────────────────────────────────────────────┘
│
├── 退出 → 返回最终消息或等待外部交互
│
▼ (继续推理)
┌─────────────────────────────────────────────────┐
│ Step 3: 上下文压缩(如需要) │
│ - 对话太长时自动压缩历史,保持上下文在窗口内 │
└─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Step 4: 调用 LLM 推理 │
│ - 把当前上下文 + 工具描述发给模型 │
│ - 模型决定:直接回复 / 调用某个工具 │
└─────────────────────────────────────────────────┘
│
├── 无工具调用 → 返回最终消息(结束)
│
▼ (模型决定调用工具)
┌─────────────────────────────────────────────────┐
│ Step 5: 行动阶段(Acting) │
│ - 批量执行工具调用(串行或并发) │
│ - 权限检查:允许 / 需要审批 / 拒绝 │
│ - 执行工具 → 拿到结果 │
└─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Step 6: 将工具结果加回上下文 │
│ - 模型"看到"工具执行结果 │
│ - 回到 Step 2,继续推理循环 │
└─────────────────────────────────────────────────┘
注意上面的 Step 5 中的权限检查——这是 AgentScope Java 2.0 的一个亮点。工具调用不再是"裸奔"的,框架内置了允许 / 需要用户审批 / 拒绝三态决策机制。对于敏感操作(比如删除文件、写数据库),可以配置成需要人工确认,Agent 会暂停并等待用户批准后再执行。
重点:ReActAgent 的核心循环本质上是一个 while 循环,每次迭代模型可以选择"直接回答"或"调用工具"。默认最大迭代次数是 10 次——如果 10 次还没搞定,Agent 会强制结束,防止无限循环。
三、手写第一个 ReActAgent:让 Agent 学会查气温算温差
理论说再多不如来段代码。我们来实现一个带天气查询工具的 ReActAgent——让 Agent 能够自己决定调用"查气温"工具来获取某一天的温度数据,然后综合多个结果回答温差问题。
为什么要用这个例子?因为大模型虽然数学能力强,但它不可能知道昨天的实时气温。这就迫使 Agent 必须调用外部工具获取数据——这才是 ReAct 模式真正发挥作用的地方。
1. 准备 Maven 依赖
在上一篇的 pom.xml 基础上,我们只需要 agentscope-harness 就够了(它会自动拉 agentscope-core):
<properties>
<agentscope.version>2.0.0</agentscope.version>
</properties>
<dependencies>
<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-harness</artifactId>
<version>${agentscope.version}</version>
</dependency>
<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-extensions-model-openai</artifactId>
<version>${agentscope.version}</version>
</dependency>
</dependencies>
2. 定义天气查询工具
AgentScope Java 2.0 中,注册工具的使用姿势非常简单——只需要在普通 Java 类的方法上标注 @Tool 和 @ToolParam 注解即可:
package com.example.tools;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
/**
* 天气查询工具 —— Agent 通过此工具获取指定日期的气温
*/
public class WeatherTool {
@Tool(name = "getDailyTemperature",
value = "查询某一天的最高气温和最低气温,入参为日期字符串,格式为 yyyy-MM-dd")
public String getDailyTemperature(
@ToolParam(name = "date",
description = "查询的日期,格式 yyyy-MM-dd,例如 2026-07-21") String date) {
// 真实项目中这里会调用天气预报 API(如和风天气、OpenWeatherMap 等)
// 此处为演示,根据日期返回模拟数据
System.out.println("getDailyTemperature: " + date);
return switch (date) {
case "2026-07-20" -> "2026-07-20 最高温 35°C,最低温 27°C,晴转多云";
case "2026-07-21" -> "2026-07-21 最高温 32°C,最低温 25°C,阵雨";
case "2026-07-22" -> "2026-07-22 最高温 30°C,最低温 23°C,中雨";
default -> date + " 暂无预报数据";
};
}
}
注意:
@Tool注解的 name 和 value 都是必填的,name 是工具的唯一标识,value 是工具的描述。LLM 会根据 name 和 value 来决定什么时候调用这个工具。这是踩过坑的小伙伴都知道的——"描述含糊不清,模型就不知道该用哪个工具"。
3. 创建 ReActAgent
接下来是最核心的部分——创建 ReActAgent 并注册工具:
package com.example;
import com.example.tools.WeatherTool;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.tool.Toolkit;
public class Main {
public static void main(String[] args) {
// 1. 创建 Toolkit 并注册工具
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new WeatherTool());
// 2. 构建 ReActAgent
ReActAgent agent = ReActAgent.builder()
.name("weather-agent")
.sysPrompt("你是一个天气查询助手。你可以查询某天的气温数据。" +
"当用户问温差、温度变化等问题时,请先查询各天的温度,再综合分析。")
.model(OpenAIChatModel.builder()
.apiKey(EnvUtil.getZhipuApiKey())
.baseUrl("https://open.bigmodel.cn/api/paas")
.endpointPath("/v4/chat/completions")
.modelName("GLM-4-Flash")
.stream(true)
.formatter(new OpenAIChatFormatter())
.build())
.toolkit(toolkit)
.maxIters(15) // 最大推理迭代次数
.build();
// 3. 流式监听 ReAct 全过程:思考 → 调用工具 → 观察结果 → 继续思考
System.out.println("╔════════════════════════════════════════╗");
System.out.println("║ 🔍 ReAct 思考推理过程 ║");
System.out.println("╚════════════════════════════════════════╝\n");
agent.streamEvents(
new UserMessage("今天(2026-07-22)比昨天(2026-07-21)降温了多少度?")
).doOnNext(event -> {
if (event.getType() == AgentEventType.TEXT_BLOCK_DELTA) {
// 模型返回的流式文本片段 —— 逐个字符输出(即"思考"和"最终回答"的内容)
System.out.print(((TextBlockDeltaEvent) event).getDelta());
} else if (event.getType() == AgentEventType.TOOL_CALL_START) {
// Agent 即将调用工具
System.out.println("\n\n🔧 [调用工具] " +
((ToolCallStartEvent) event).getToolCallName());
}
}).doOnComplete(() -> {
System.out.println("\n\n✅ ReAct 推理完成!");
}).blockLast();
}
}
4. 运行效果
运行上面的代码,控制台输出如下(注意:这是通过流式事件捕获的过程日志,下面我会讲 streamEvents):
╔════════════════════════════════════════╗
║ 🔍 ReAct 思考推理过程 ║
╚════════════════════════════════════════╝
我们需要比较今天和昨天的气温变化,因此需要查询这两天的气温数据。
🔧 [调用工具] getDailyTemperature
getDailyTemperature: 2026-07-22
🔧 [调用工具] getDailyTemperature
getDailyTemperature: 2026-07-21
今天(2026-07-22)的最高温度为30°C,最低温度为23°C;昨天(2026-07-21)的最高温度为32°C,最低温度为25°C。因此,今天比昨天降温了2°C。
✅ ReAct 推理完成!
注意看这个过程中 Agent 的推理链:先意识到需要查数据 → 调用工具查第一天 → 再查第二天 → 对比温差 → 综合回答。每一步都是模型自主决策的结果,这才是 ReAct 模式真正的价值——模型清楚自己不知道什么,主动去获取信息,再把信息加工成答案。
5. 如果不用 Agent,传统方式要怎么写?
作为对比,如果不使用 ReActAgent,要实现同样的"查天气算温差"效果,我们需要自己写一套逻辑:
// 传统方式:需要我们自己管理"理解→查数据→计算"的全流程
String userInput = "今天比昨天降温了多少度?";
// 1. 用 LLM 从用户问题中提取日期和意图
String intent = callLlm("从以下问题中提取需要查询的日期:" + userInput);
// 输出: "需要查询 2026-07-21 和 2026-07-22 的温度"
// 2. 自己写代码逐个调用天气 API
String temp1 = weatherApi.query("2026-07-21"); // 32°C / 25°C
String temp2 = weatherApi.query("2026-07-22"); // 30°C / 23°C
// 3. 再调 LLM 做温差分析
String finalAnswer = callLlm(
"2026-07-21气温:" + temp1 + ",2026-07-22气温:" + temp2 +
",请计算温差并回答用户:" + userInput
);
看到了吧?没有 ReActAgent,你需要自己管理"理解意图→分步执行→结果汇总"的全流程。而 AgentScope 把这一切都自动化了——模型自己决定什么时候需要查数据、查哪个日期、拿到结果后怎么对比。
四、深入理解核心参数
ReActAgent 提供了丰富的配置参数,下面几个是日常开发中最常用的:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | String | 必填 | Agent 标识符,用于消息和日志 |
sysPrompt | String | 必填 | 系统提示词,定义 Agent 人设 |
model | String / Model | 必填 | LLM 模型(String 由 ModelRegistry 解析) |
toolkit | Toolkit | new Toolkit() | 工具注册中心 |
maxIters | int | 10 | 最大推理迭代次数 |
stateStore | AgentStateStore | null | 状态持久化(不配则不持久化) |
middlewares | List | List.of() | 中间件列表 |
1. maxIters —— 防止 Agent 陷入死循环
这个参数可以说是最重要的安全阀。假设 Agent 在某个环节反复出错——比如调用天气工具时网络超时,它可能一直重试,陷入无限循环。
ReActAgent agent = ReActAgent.builder()
.name("safe-agent")
.sysPrompt("你是一个助手。")
.model(...)
.toolkit(toolkit)
.maxIters(5) // 最多迭代5次,超限强制结束
.build();
默认 10 次对于大部分场景是够用的。如果你的任务特别复杂(比如多步数据分析),可以适当调大;反之,对于简单的问答场景,设为 3-5 次可以更快失败。
2. stateStore —— 让 Agent 拥有"记忆力"
默认情况下,ReActAgent 每次 call 都是"一次性"的——call 结束上下文就丢了。如果需要跨会话保持状态(比如让 Agent 记住用户上一轮说了什么),就需要配置 AgentStateStore:
import io.agentscope.core.state.JsonFileAgentStateStore;
import java.nio.file.Paths;
ReActAgent agent = ReActAgent.builder()
.name("memory-agent")
.sysPrompt("你是一个有记忆的助手。")
.model(...)
.toolkit(toolkit)
.stateStore(new JsonFileAgentStateStore(
Paths.get(System.getProperty("user.home"), ".agentscope/sessions")))
.build();
// 第一轮:Agent 记住对话
agent.call(new UserMessage("我叫一灰灰。"),
RuntimeContext.builder()
.userId("user001")
.sessionId("session001")
.build()).block();
// 第二轮:同 userId + sessionId,Agent 还记得刚才的话
agent.call(new UserMessage("我叫什么名字?"),
RuntimeContext.builder()
.userId("user001")
.sessionId("session001")
.build()).block();
// → Agent 会回答:你叫一灰灰
注意:这里用的是
ReActAgent而不是HarnessAgent,所以状态存储需要手动配置stateStore。如果用HarnessAgent,上一篇文章讲过,工作区会自动管理会话持久化。
3. Toolkit —— 工具注册中心
Toolkit 是 Agent 的"工具箱",支持多种方式注册工具:
Toolkit toolkit = new Toolkit();
// 方式一:通过 @Tool 注解注册(推荐)
toolkit.registerTool(new WeatherTool());
// 方式二:注册 MCP 客户端(对接外部服务)
McpClientWrapper mcpClient = McpClientBuilder.streamableHttp()
.name("weather-service")
.url("http://localhost:8080/mcp")
.build();
toolkit.registerMcpClient(mcpClient).block();
// 方式三:启用内置元工具
// .enableMetaTool(true) — 让 Agent 能动态发现和切换工具组
// .enableTaskList() — 让 Agent 能拆解复杂任务为步骤
五、流式事件与执行观测
在实际开发中,我们往往不只想拿到最终结果,还想实时看到 Agent 的"思考过程"——它在想什么、调用了什么工具、拿到了什么结果。
AgentScope Java 2.0 提供了 streamEvents() 方法,可以把 Agent 执行的每一步以类型化事件的形式流式推送出来:
import io.agentscope.core.event.AgentEventType;
import io.agentscope.core.event.TextBlockDeltaEvent;
import io.agentscope.core.event.ToolCallStartEvent;
import io.agentscope.core.event.ToolCallEndEvent;
// 用于暂存正在组装的工具参数
Map<String, StringBuilder> toolArgsBuffer = new ConcurrentHashMap<>();
agent.streamEvents(new UserMessage("今天和昨天比降温了多少度?"))
.doOnNext(event -> {
switch (event.getType()) {
case TOOL_CALL_START -> {
var e = (ToolCallStartEvent) event;
// 1. 此时只能获取到工具名称和唯一标识
System.out.println("\n[准备调用工具] " + e.getToolCallId() + " : " + e.getToolCallName());
// 初始化参数缓冲区
toolArgsBuffer.put(e.getToolCallId() + ":req", new StringBuilder());
toolArgsBuffer.put(e.getToolCallId() + ":rsp", new StringBuilder());
}
case TOOL_CALL_DELTA -> {
var e = (ToolCallDeltaEvent) event;
// 2. 通过 toolCallId 关联,流式拼接工具参数
StringBuilder buffer = toolArgsBuffer.get(e.getToolCallId() + ":req");
System.out.println("\n[工具参数] " + e.getToolCallId() + " : " + e.getDelta());
if (buffer != null) {
buffer.append(e.getDelta());
}
}
case TOOL_RESULT_START -> {
// 3. 工具开始执行
var e = (ToolResultStartEvent) event;
System.out.println("\n[工具执行开始] " + e.getToolCallId() + " : " + e.getToolCallName());
}
case TOOL_RESULT_TEXT_DELTA -> {
// 4. 流式获取工具返回结果
var e = (ToolResultTextDeltaEvent) event;
StringBuilder buffer = toolArgsBuffer.get(e.getToolCallId() + ":rsp");
System.out.println("[工具返回]: " + e.getDelta());
if (buffer != null) {
buffer.append(e.getDelta());
}
}
case TOOL_RESULT_END -> {
var e = (ToolResultEndEvent) event;
// 5. 参数拼接完成,获取完整参数并清理缓冲区
String finalArgs = toolArgsBuffer.remove(e.getToolCallId() + ":req").toString();
System.out.println("完整参数: " + finalArgs);
// 工具调用完成,获取完整结果并清理缓冲区
String finalResult = toolArgsBuffer.remove(e.getToolCallId() + ":rsp").toString();
System.out.println("完整结果: " + finalResult);
}
}
})
.blockLast();
运行效果如下(实时逐行输出):
╔════════════════════════════════════════╗
║ 🔍 ReAct 思考推理过程 ║
╚════════════════════════════════════════╝
[准备调用工具] call_202607230917525694757126974093_0 : getDailyTemperature
[工具参数] call_202607230917525694757126974093_0 : {"date": "2026-07-23"}
[工具执行开始] call_202607230917525694757126974093_0 : getDailyTemperature
[WeatherTool] 查询日期: 2026-07-23
[工具返回]: "2026-07-23 最高温 14°C,最低温 2°C,雷阵雨"
完整参数: {"date": "2026-07-23"}
完整结果: "2026-07-23 最高温 14°C,最低温 2°C,雷阵雨"
[准备调用工具] call_202607230917552c843e2b1a3941e3_0 : getDailyTemperature
[工具参数] call_202607230917552c843e2b1a3941e3_0 : {"date": "2026-07-22"}
[工具执行开始] call_202607230917552c843e2b1a3941e3_0 : getDailyTemperature
[WeatherTool] 查询日期: 2026-07-22
[工具返回]: "2026-07-22 最高温 18°C,最低温 6°C,大雨"
完整参数: {"date": "2026-07-22"}
完整结果: "2026-07-22 最高温 18°C,最低温 6°C,大雨"
注意观察——Agent 是先查了 23 号,再查 22 号,然后自己做了对比。这种"需要什么查什么"的能力,才是 ReAct 模式真正的魅力所在。
在AgentScope中,提供了大量的事件,基本上覆盖了全流程调用的各个时机节点,通过这些事件的监听,你可以做丰富的检测、扩展,官方说明文档可以参照:- 消息与事件 - AgentScope Java
完整的生命周期可以参见下图

这 28 种类型化事件覆盖了 Agent 执行的整个生命周期——文本输出、工具调用、用户确认、中断、错误等等。用 streamEvents 可以非常方便地对接 Web UI(比如 Spring Boot + WebSocket),实现类似 ChatGPT 的流式打字效果。
六、小结
到这里,我们已经完整地走通了 AgentScope Java 2.0 的核心推理引擎。回顾一下今天的重点:
- ReAct 模式是什么 — 让 LLM 在"推理"和"行动"之间循环切换,从被动问答变成主动智能体
- ReActAgent 的执行流程 — 消息入队 → 检查下一步 → LLM 推理 → 工具调用 → 结果回注 → 继续推理
- 实战:天气温差 Agent — 用
@Tool注解注册天气查询工具,Agent 自主决策分步查询并对比温差。大模型算数不需要工具,但查实时数据必须靠工具——这才是 ReAct 模式的精髓 - 核心参数配置 —
maxIters防止死循环、stateStore赋予记忆力、Toolkit管理工具箱 - 流式事件观测 —
streamEvents()实时追踪 Agent 的每一步思考与行动
对比一下:
| 能力 | 普通 LLM API | ReActAgent |
|---|---|---|
| 调用外部工具 | ❌ 需自己写逻辑 | ✅ 自动决策调用 |
| 多步推理 | ❌ 一次性回答 | ✅ 循环迭代思考 |
| 状态管理 | ❌ 无状态 | ✅ 可持久化会话 |
| 权限控制 | ❌ 无 | ✅ 三态决策 |
| 实时观测 | ❌ | ✅ 28 种类型化事件 |
从上面的对比可以看出,ReActAgent 并不是一个"花架子",它把智能体最核心的"思考-行动"循环做成了框架的内建能力。开发者只需要注册工具、配好模型,Agent 就能自主完成复杂的多步任务。
七、其他
0. 项目
- 项目地址:https://github.com/liuyueyi/spring-ai-demo/agent-scope
- ReActAgent 官方文档:https://java.agentscope.io/v2/zh/docs/building-blocks/agent.html
- 工具系统文档:https://java.agentscope.io/v2/zh/docs/building-blocks/tool.html
- 消息与事件系统:https://java.agentscope.io/v2/zh/docs/building-blocks/message-and-event.html
1. 下篇预告
本文是【AgentScope Java 新手村系列】的第二篇。学完 ReActAgent 之后,接下来的内容更精彩:
- 第1篇:AgentScope Java 2.0 简介与环境搭建:从 GitHub 拉取源码编译安装,使用纯 Java 启动工程,接入 DeepSeek/OpenAI 兼容模型。
- 第3篇:工具系统(Tools)实战 — 用
@Tool注解将任意 Java 方法注册为 Agent 工具,实现文件读写、HTTP 调用、数据库查询等各种骚操作 - 第4篇:HarnessAgent 深度解析 — 什么时候用 ReActAgent,什么时候用 HarnessAgent?工作区、记忆、技能、子 Agent 怎么协同?
不知道各位小伙伴有没有发现,今天的天气示例中 Agent 查询气温的"思路链"其实可以被保存下来。如果把"查天气→算温差"这种常见问题模式沉淀成 Skill 文件,下次遇到类似问题 Agent 就可以直接复用之前的经验——这就是 2.0 的"自进化"能力。那么这个 Skills 系统到底怎么玩?以上这些问题,我们留到下一篇再详细介绍。
尽信书则不如,以上内容,纯属一家之言,因个人能力有限,难免有疏漏和错误之处,如发现 bug 或者有更好的建议,欢迎批评指正,不吝感激。
微信公众号: 一灰灰Blog —— 关注获取最新技术文章推送