Java on WY 的技术博客

ReActAgent 源码分析

Fri, 22 May 2026 00:00:00 +0000

概述

ReActAgent 是 AgentScope Java 的核心推理引擎，位于 agentscope-core 模块。它实现了 ReAct (Reasoning and Acting) 设计模式——在推理（想下一步做什么）和执行（调工具）之间交替循环。

源码位置：agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java（1925 行）

核心依赖

public class ReActAgent extends StructuredOutputCapableAgent {
 private final Memory memory; // 对话历史（InMemoryMemory）
 private final String sysPrompt; // 系统提示词
 private final Model model; // LLM 模型
 private final int maxIters; // 最大迭代次数（默认 10）
 private final Toolkit toolkit; // 可用工具集
 private final PlanNotebook planNotebook; // 计划本
 private final StatePersistence statePersistence; // 状态持久化策略
}

核心循环：reason → act → reason → act → …

整个 ReAct 循环的入口：

private Mono<Msg> executeIteration(int iter) {
 return reasoning(iter, false); // 先推理
}

reasoning 阶段（第 560-650 行）

① 检查 maxIters → 超限则走 summarizing()
② notifyPreReasoningEvent() ← Hook 注入点：CompactionHook、SubagentsHook、WorkspaceContextHook
③ model.stream(messages + tool schemas) ← 调 LLM
④ 逐 chunk 处理 + notifyReasoningChunk() ← 流式输出
⑤ notifyPostReasoning() ← Hook 注入点
⑥ 判断：
- stopRequested → 返回（HITL 打断）
- gotoReasoning → 继续推理（结构化输出重试）
- isFinished(msg) → 没有 tool call → 返回结果
- 有 tool call → going to acting(iter)

关键判断 isFinished（第 969 行）：

把你的Java后端经验重新编译一次：当Netty/Epoll/JVM映射到AI Infra

Fri, 22 May 2026 00:00:00 +0000

用10年Java后端工程师听得懂的语言，把AI Infra/HPC的底层原理讲透——这不是路线图，这是一次系统级的代码级映射。

系列01：内存管理——当你在管理 ByteBuf 时，你已经在管理 KV Cache 了

Fri, 22 May 2026 00:00:00 +0000

从 Netty ByteBuf 池化、JVM 堆管理到 vLLM PagedAttention 与 GPU 显存管理，同一个问题在三个世界的不同解法。附带 4 个可运行的代码实验。

AgentScope Java Harness 架构与实战指南

Wed, 20 May 2026 00:00:00 +0000

前言

AgentScope Java 的 Harness 模块是一个面向生产环境的多智能体运行时框架。本文基于官方文档，从其设计理念到具体代码实践，完整梳理 Harness 的核心架构与使用方式。

一、Harness 是什么

agentscope-harness 在 agentscope-core 的 ReActAgent 之上，通过 Hook 和 Toolkit 两个扩展点，装配出一套面向长期稳定运行的工程化基础设施。它的入口只有一个类：HarnessAgent。

裸的 ReActAgent 只有"请求 — 推理 — 工具 — 回复"一轮循环。而 Harness 要回答的是一组更贴近生产的问题：

下一轮怎么办？
下一天怎么办？
上下文爆了怎么办？
状态丢了怎么办？
任务太重怎么办？

它不替换推理循环，而是在循环的关键时机插入 hook、为模型补上一组基础工具，把这些问题的默认工程答案打包好。

快速开始

<dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-harness</artifactId>
 <version>${agentscope.version}</version>
</dependency>

public class QuickstartExample {
 public static void main(String[] args) throws Exception {
 // 1. 准备工作区
 Path workspace = Paths.get(".agentscope/workspace");
 initWorkspaceIfAbsent(workspace);

 // 2. 构建模型
 Model model = DashScopeChatModel.builder()
 .apiKey(System.getenv("DASHSCOPE_API_KEY"))
 .modelName("qwen-max")
 .stream(true)
 .build();

 // 3. 构建 HarnessAgent
 HarnessAgent agent = HarnessAgent.builder()
 .name("quickstart-agent")
 .sysPrompt("你是一个帮助用户做笔记的助手。")
 .model(model)
 .workspace(workspace)
 .compaction(CompactionConfig.builder()
 .triggerMessages(30)
 .keepMessages(10)
 .flushBeforeCompact(true)
 .build())
 .build();

 // 4. 两轮对话，同一 sessionId
 RuntimeContext ctx = RuntimeContext.builder()
 .sessionId("demo-session")
 .userId("alice")
 .build();

 Msg turn1 = agent.call(
 Msg.builder().role(MsgRole.USER)
 .textContent("我叫天宇，今天准备做一个关于 ReAct 的技术分享。")
 .build(),
 ctx).block();

 Msg turn2 = agent.call(
 Msg.builder().role(MsgRole.USER)
 .textContent("我叫什么？我今天要干什么？")
 .build(),
 ctx).block();
 }

 private static void initWorkspaceIfAbsent(Path workspace) throws Exception {
 Files.createDirectories(workspace);
 Path agentsMd = workspace.resolve("AGENTS.md");
 if (Files.exists(agentsMd)) return;
 Files.writeString(agentsMd, """
 # 笔记助手
 你是一个帮助用户整理笔记和知识的助手。
 ## 行为约定
 - 主动记录用户提到的关键事实（姓名、计划、偏好等）
 - 回答用简洁中文，必要时给出要点列表
 - 对不确定的内容要主动说明，不要臆造
 """);
 }
}

上述代码展示了 Harness 的三个核心价值：工作区驱动的人格、会话持久化（同一 sessionId 的第二轮对话记得第一轮的内容）、显式启用对话压缩。