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

AI Agent on WY 的技术博客

AgentScope Java Harness 架构与实战指南

前言

一、Harness 是什么

快速开始