技术文章

概述 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 行）： ...

前言 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 的第二轮对话记得第一轮的内容）、显式启用对话压缩。 ...