## 1. 写在前面

为了后续的学习，我们先来看两个概念，`ReActAgent`和`HarnessAgent`。

`Agent`（接口位于 `io.agentscope.core.agent.Agent`，默认实现是 `ReActAgent`）是 AgentScope 的核心抽象——一个推理-行动循环引擎，将模型、工具、权限系统、人机交互、上下文管理、中间件、状态管理和事件系统整合到一个统一接口中。

`HarnessAgent` 是 `ReActAgent` 的一层薄包装，把长期运行 agent 必备的工程能力打包进单一 builder：工作区驱动的人格、长期记忆、子 agent 编排、沙箱隔离、技能装配、计划模式、Channel 路由。裸的 `ReActAgent` 只解决”一次请求 → 推理 → 工具 → 回复”。Harness 要回答的是另一组问题：下一轮怎么接着上一轮、上下文如何保持有界、多用户如何隔离、危险操作如何先 review 再执行、可复用能力如何沉淀。

有点类似于`Deep Agents`和`LangChain`的关系，`HarnessAgent`是针对`ReActAgent`的进一步包装。

![image-20260926113051969](https://developer.qcloudimg.com/http-save/yehe-8160077/f1ee18f3e4b4dbe3fcdd0a453dfdc3c2.png)

整体的学习路线，我们将快速的过一遍`ReActAgent`的知识点，然后核心放到`HarnessAgent`。

## 2. ReActAgent配置介绍

上一篇搭建了一个简单的demo。那么这一篇我们一起看看ReActAgent具体有哪些参数和配置。

### 参数说明

| 参数                | 类型                             | 默认值              | 描述                                                         |
| :------------------ | :------------------------------- | :------------------ | :----------------------------------------------------------- |
| `name`              | `String`                         | 必填                | 智能体标识符，用于消息和日志                                 |
| `sysPrompt`         | `String`                         | 必填                | 智能体的基础系统提示词                                       |
| `model`             | `Model`                          | 必填                | 用于推理的大语言模型（继承自 `ChatModelBase`）               |
| `toolkit`           | `Toolkit`                        | `new Toolkit()`     | 管理工具、MCP 客户端、技能和工具组                           |
| `middlewares`       | `List<? extends MiddlewareBase>` | `List.of()`         | 应用于 agent / reasoning / acting / model call / system prompt 钩子 |
| `stateStore`        | `AgentStateStore`                | `null`（不持久化）  | 配置后 agent 在每次 `call` 后自动加载/保存 `AgentState`，按该次调用 `RuntimeContext` 的 `(userId, sessionId)` 寻址 |
| `defaultSessionId`  | `String`                         | agent `name`        | 当某次调用的 `RuntimeContext` 没带 `sessionId` 时的兜底值    |
| `permissionContext` | `PermissionContextState`         | 默认 `DEFAULT` 模式 | 工具执行的细粒度规则                                         |
| `modelConfig`       | `ModelConfig`                    | 默认值              | 模型重试次数和备用模型                                       |
| `reactConfig`       | `ReactConfig`                    | 默认值              | 最大迭代次数和拒绝处理方式                                   |
| `maxIters`          | `int`                            | `10`                | ReAct 主循环最大迭代次数（也可放在 `reactConfig` 中）        |

有一些基础的参数我们就不展开赘述了。这里先大体一览，后面我们会逐渐介绍。

本篇所有的代码，下面会用到，不再一一贴了：


```java
package com.maple.agent.demo;

import com.maple.agent.MapleAgentApplication;
import com.maple.agent.config.OpenAiModelConfig;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.event.*;
import io.agentscope.core.message.*;
import io.agentscope.extensions.model.openai.OpenAIChatModel;
import org.springframework.boot.SpringApplication;
import org.springframework.context.ConfigurableApplicationContext;

public class ReActAgent_02 {

    public static void main(String[] args) {

        // 为了方便提及代码，不暴露隐私信息，密钥放到application-pro.yml中
        ConfigurableApplicationContext ctx = SpringApplication.run(MapleAgentApplication.class, args);
        OpenAiModelConfig props = ctx.getBean(OpenAiModelConfig.class);

        OpenAIChatModel model = OpenAIChatModel.builder()
                .baseUrl(props.getBaseUrl())
                .apiKey(props.getApiKey())
                .modelName(props.getModelName())
                .stream(true)
                .build();

        ReActAgent agent = ReActAgent.builder()
                .name("笑小枫的学习助手")
                .model(model)
                .sysPrompt("你是笑小枫的学习助手，可以帮助用户快速学习使用AgentScope开发智能体。")
                .build();

//        call(agent);
        streamEvents(agent);

    }

    // 多模态消息，直接返回结果
    private static void call(ReActAgent agent) {
        UserMessage userMessage = new UserMessage(
                "user",
                TextBlock.builder().text("这张图片是什么？").build(),
                DataBlock.builder().source(
                        URLSource.builder().url("https://image.xiaoxiaofeng.site/blog/image/image-20260719154443011.png?xiaoxiaofeng").build())
                        .build()
        );
        Msg reply = agent.call(userMessage).block();
        System.out.println(reply.getTextContent());
    }

    // 流式返回结果
    private static void streamEvents(ReActAgent agent) {
        agent.streamEvents(new UserMessage("user", "帮我制定学习计划"))
                .doOnNext(event -> {
                    if (event instanceof AgentStartEvent start) {
                        System.out.println("[start replyId=" + start.getReplyId() + "]");
                    } else if (event instanceof TextBlockDeltaEvent delta) {
                        System.out.print(delta.getDelta());
                    } else if (event instanceof AgentEndEvent end) {
                        System.out.println("\n[完成]");
                    }
                })
                .blockLast();
    }

    // 演示执行事件，流式返回结果
    private static void streamEvents2(ReActAgent agent) {
        StringBuilder accumulated = new StringBuilder();

        agent.streamEvents(new UserMessage("user", "你是谁？"))
                .doOnNext(event -> {
                    if (event instanceof AgentStartEvent start) {
                        System.out.println("[start replyId=" + start.getReplyId() + "]");
                    } else if (event instanceof ThinkingBlockStartEvent thinkingBlockStartEvent) {
                        System.out.println("[思考开始 replyId=" + thinkingBlockStartEvent.getReplyId() + "]");
                    } else if (event instanceof ThinkingBlockDeltaEvent thinkingBlockDeltaEvent) {
                        System.out.println("[思考内容 =" + thinkingBlockDeltaEvent.getDelta() + "]");
                    } else if (event instanceof ThinkingBlockEndEvent thinkingBlockEndEvent) {
                        System.out.println("[思考完成 replyId=" + thinkingBlockEndEvent.getReplyId() + "]");
                    } else if (event instanceof TextBlockDeltaEvent delta) {
                        accumulated.append(delta.getDelta());
                    } else if (event instanceof ToolCallStartEvent tc) {
                        System.out.println("[tool] " + tc.getToolCallName());
                    } else if (event instanceof ToolResultEndEvent end) {
                        System.out.println("[tool result state=" + end.getState() + "]");
                    } else if (event instanceof AgentEndEvent end) {
                        System.out.println("\n[end] full text:\n" + accumulated);
                    }
                })
                .blockLast();
    }
}
```

##  3. 消息类型

`Msg`（位于 `io.agentscope.core.message`）代表对话中的一个轮次——用户输入、智能体回复或系统指令，内容以有序的类型化块（`ContentBlock`）列表表示。

`Msg` 类的核心字段（getter）如下：

| 方法                  | 类型                  | 说明                                                         |
| :-------------------- | :-------------------- | :----------------------------------------------------------- |
| `getId()`             | `String`              | 唯一消息标识符                                               |
| `getName()`           | `String`              | 发送方名称（可空）                                           |
| `getRole()`           | `MsgRole`             | `USER` / `ASSISTANT` / `SYSTEM` / `TOOL`                     |
| `getContent()`        | `List<ContentBlock>`  | 有序内容块列表（不可变）                                     |
| `getMetadata()`       | `Map<String, Object>` | 任意键值元数据                                               |
| `getTimestamp()`      | `String`              | 创建时间（`yyyy-MM-dd HH:mm:ss.SSS`）                        |
| `getUsage()`          | `ChatUsage`           | Token 用量（仅 assistant 消息）                              |
| `getGenerateReason()` | `GenerateReason`      | 退出原因：`MODEL_STOP` / `TOOL_SUSPENDED` / `REASONING_STOP_REQUESTED` / `ACTING_STOP_REQUESTED` / `ALL_TOOLS_DENIED` / `INTERRUPTED` / `MAX_ITERATIONS` |

通过断点图，可以比较直观的看到上面的内容。

![image-20260926122621283](https://developer.qcloudimg.com/http-save/yehe-8160077/8fc5c27143e7a49d90f138fc74779e63.png)

### 内容块

消息内容由类型化的块组成，每种块代表一类独立信息。块类位于 `io.agentscope.core.message`：

![image-20260926123109700](https://developer.qcloudimg.com/http-save/yehe-8160077/938e3ed85e9645ad0d55bbd6c9a8817b.png)

| 块类型            | 说明                                                         | 允许出现在              |
| :---------------- | :----------------------------------------------------------- | :---------------------- |
| `TextBlock`       | 纯文本内容                                                   | USER、ASSISTANT、SYSTEM |
| `DataBlock`       | 二进制数据（图片、音频、视频），通过 base64 或 URL；统一替代旧的 ImageBlock/AudioBlock/VideoBlock | USER、ASSISTANT         |
| `ThinkingBlock`   | 模型推理过程（思维链）                                       | ASSISTANT               |
| `ToolUseBlock`    | 工具调用，包含 `id` / `name` / `input` / `state`（`ToolCallState`） | ASSISTANT               |
| `ToolResultBlock` | 工具执行结果，包含 `state`（`ToolResultState`）              | ASSISTANT               |
| `HintBlock`       | 以用户上下文形式注入循环的指令                               | ASSISTANT               |

我们用到的比较多的也就是前面两个，看一下怎么使用：

```java
    private static void call(ReActAgent agent) {
        UserMessage userMessage = new UserMessage(
                "user",
                TextBlock.builder().text("这张图片是什么？").build(),
                DataBlock.builder().source(
                        URLSource.builder().url("https://image.xiaoxiaofeng.site/blog/image/image-20260719154443011.png?xiaoxiaofeng").build())
                        .build()
        );
        Msg reply = agent.call(userMessage).block();
        System.out.println(reply.getTextContent());
    }
```

返回的结果如下：

![image-20260926123847437](https://developer.qcloudimg.com/http-save/yehe-8160077/2ce01fd677cd8ca66314a91ab9ae38c3.png)

关于ThinkingBlock和Tool相关(后面讲到工具再说)的消息，只有在streamEvents方式中能更好的体现。
![image.png](https://developer.qcloudimg.com/http-save/yehe-8160077/bde43ef3e6eb7eb2c4b36326e508021f.png)

##  4. 输出方式

我们上一篇演示的demo，直接返回了结果，如果我们想要打字机的那种展示怎么做呢，这里我们详细的讲一讲

* call

`call` 在内部消费所有事件，当智能体完成或因外部交互暂停时返回最终 `Msg`。

![image-20260926115307298](https://developer.qcloudimg.com/http-save/yehe-8160077/1b42df71980441ed223f104a2070b491.png)

* streamEvents

  构建流式输出。`streamEvents` 逐一产出 `AgentEvent` 对象，让你实时将文本输出、工具调用进度和生命周期事件流式传输给用户。

![PixPin_2026-09-26_12-15-33](https://developer.qcloudimg.com/http-save/yehe-8160077/790b98e1050048146f6fce5e5e5452e4.gif)

## 5. 执行事件

在上面我们看到了各种执行过程中的事件，事件是消息的流式对应物。每种类型的事件，都遵循 **start → delta → end** 模式。

其中delta可能产生多次，属于**增量内容片段**。
![image.png](https://developer.qcloudimg.com/http-save/yehe-8160077/6f6890601a157a73a3bd9110f8ab7a50.png)
关于事件的执行顺序和生命周期，这里就不展开了，可以前往AgentScope官网查看。

[https://java.agentscope.io/v2/zh/docs/building-blocks/message-and-event](https://java.agentscope.io/v2/zh/docs/building-blocks/message-and-event)

## 6. 本章小结

本篇围绕 `ReActAgent` 展开，主要讲了三件事：

**1. 概念区分**：`ReActAgent` 是 AgentScope 的核心抽象，负责“一次请求 → 推理 → 工具 → 回复”的循环；`HarnessAgent` 是它的薄包装，额外打包了工作区、长期记忆、子 agent、沙箱等工程能力。

**2. 消息体系**：`Msg` 代表对话中的一个轮次，由有序的 `ContentBlock` 组成。常用的有 `TextBlock`（文本）和 `DataBlock`（图片/音频/视频等多模态数据），此外还有 `ThinkingBlock`（思维链）、`ToolUseBlock` / `ToolResultBlock`（工具调用与结果）、`HintBlock`（注入指令）。

**3. 输出方式和执行事件**：`call` 会内部消费所有事件，等智能体完成或暂停后返回最终 `Msg`，适合一次性拿结果；`streamEvents` 则逐一产出 `AgentEvent`，遵循 **start → delta → end** 模式，适合打字机式的实时展示。

本篇就到这里了，下一篇会深入介绍下 `ReActAgent` 的`Middleware`的扩展能力。

本系列源码[https://gitee.com/hack-feng/maple-agent-demo](https://gitee.com/hack-feng/maple-agent-demo)

![AgentScope第2篇-ReActAgent与消息流一览图_笑小枫_2160x3840](https://developer.qcloudimg.com/http-save/yehe-8160077/e09d0de8755c8b634954422b99d9704a.png)

为了后续的学习，我们先来看两个概念，ReActAgent和HarnessAgent。

AgentScope 学习系列 - 02：ReActAgent 配置、消息与事件

本文介绍AgentScope核心组件ReActAgent与HarnessAgent。ReActAgent作为推理-行动循环引擎，整合模型、工具与上下文管理；HarnessAgent则在其基础上封装长期记忆、多用户隔离、沙箱安全等工程能力，支持复杂场景下的持续智能体运行。通过参数配置与事件流处理，实现高效、可复用的智能体开发。

人工智能

ReActAgent是AgentScope的核心推理-行动循环引擎，整合模型、工具与事件系统；HarnessAgent是其薄包装，额外提供长期记忆、子agent编排、沙箱隔离等工程能力。Msg由有序ContentBlock组成，支持文本、多模态及工具调用。输出支持call（一次性结果）与streamEvents（流式事件，遵循start→delta→end模式）。

人机交互

代码解释

AgentScope

中间件

智能体

LangChain

路由

Agent

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

ReActAgent是AgentScope的核心推理-行动循环引擎，整合模型、工具与事件系统；HarnessAgent是其薄包装，额外提供长期记忆、子agent编排、沙箱隔离等工程能力。Msg由有序ContentBlock组成，支持文本、多模态及工具调用。输出支持call（一次性结果）与streamEvents（流式事...

AgentScope 学习系列 - 02：ReActAgent 配置、消息与事件-腾讯云开发者社区-腾讯云

AgentScope 学习系列 - 02：ReActAgent 配置、消息与事件

AgentScope 学习系列 - 02：ReActAgent 配置、消息与事件

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐