02.AgentScope Java 2.0 核心推理引擎 ReActAgent

一灰灰blogAgentScope Java新手村核心概念与快速起步ReActAgent 推理引擎AgentScopeJavaReActAgentAI Agent约 4771 字大约 16 分钟

同样是调大模型,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 提供了丰富的配置参数,下面几个是日常开发中最常用的:

参数类型默认值说明
nameString必填Agent 标识符,用于消息和日志
sysPromptString必填系统提示词,定义 Agent 人设
modelString / Model必填LLM 模型(String 由 ModelRegistry 解析)
toolkitToolkitnew Toolkit()工具注册中心
maxItersint10最大推理迭代次数
stateStoreAgentStateStorenull状态持久化(不配则不持久化)
middlewaresListList.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 Javaopen in new window

完整的生命周期可以参见下图

这 28 种类型化事件覆盖了 Agent 执行的整个生命周期——文本输出、工具调用、用户确认、中断、错误等等。用 streamEvents 可以非常方便地对接 Web UI(比如 Spring Boot + WebSocket),实现类似 ChatGPT 的流式打字效果。

六、小结

到这里,我们已经完整地走通了 AgentScope Java 2.0 的核心推理引擎。回顾一下今天的重点:

  1. ReAct 模式是什么 — 让 LLM 在"推理"和"行动"之间循环切换,从被动问答变成主动智能体
  2. ReActAgent 的执行流程 — 消息入队 → 检查下一步 → LLM 推理 → 工具调用 → 结果回注 → 继续推理
  3. 实战:天气温差 Agent — 用 @Tool 注解注册天气查询工具,Agent 自主决策分步查询并对比温差。大模型算数不需要工具,但查实时数据必须靠工具——这才是 ReAct 模式的精髓
  4. 核心参数配置 — maxIters 防止死循环、stateStore 赋予记忆力、Toolkit 管理工具箱
  5. 流式事件观测 — streamEvents() 实时追踪 Agent 的每一步思考与行动

对比一下:

能力普通 LLM APIReActAgent
调用外部工具❌ 需自己写逻辑✅ 自动决策调用
多步推理❌ 一次性回答✅ 循环迭代思考
状态管理❌ 无状态✅ 可持久化会话
权限控制❌ 无✅ 三态决策
实时观测❌✅ 28 种类型化事件

从上面的对比可以看出,ReActAgent 并不是一个"花架子",它把智能体最核心的"思考-行动"循环做成了框架的内建能力。开发者只需要注册工具、配好模型,Agent 就能自主完成复杂的多步任务。

七、其他

0. 项目

1. 下篇预告

本文是【AgentScope Java 新手村系列】的第二篇。学完 ReActAgent 之后,接下来的内容更精彩:

  • 第1篇:AgentScope Java 2.0 简介与环境搭建open in new window:从 GitHub 拉取源码编译安装,使用纯 Java 启动工程,接入 DeepSeek/OpenAI 兼容模型。
  • 第3篇:工具系统(Tools)实战 — 用 @Tool 注解将任意 Java 方法注册为 Agent 工具,实现文件读写、HTTP 调用、数据库查询等各种骚操作
  • 第4篇:HarnessAgent 深度解析 — 什么时候用 ReActAgent,什么时候用 HarnessAgent?工作区、记忆、技能、子 Agent 怎么协同?

不知道各位小伙伴有没有发现,今天的天气示例中 Agent 查询气温的"思路链"其实可以被保存下来。如果把"查天气→算温差"这种常见问题模式沉淀成 Skill 文件,下次遇到类似问题 Agent 就可以直接复用之前的经验——这就是 2.0 的"自进化"能力。那么这个 Skills 系统到底怎么玩?以上这些问题,我们留到下一篇再详细介绍。

尽信书则不如,以上内容,纯属一家之言,因个人能力有限,难免有疏漏和错误之处,如发现 bug 或者有更好的建议,欢迎批评指正,不吝感激。

微信公众号: 一灰灰Blog —— 关注获取最新技术文章推送

Loading...