01 引言

如果说Spring AI是给Java和AI的融合提供了方便，那么Langchain4j则是集成了更加丰富的功能。而阿里的 AgentScope Java 2.0则是基于Harness 架构，将AI Agent整套流程使用Java落地了，并提供了场地稳定运行的工程底座。

我们一起来看看这个到底是什么东西？

02 简介

AgentScope Java 2.0 是面向企业级、分布式、生产环境的智能体框架，提供与模型能力相匹配的核心 Harness 抽象，可支持长期、稳定、安全可控的智能体任务执行。

• 事件系统：统一的事件流，28 种类型化事件，服务于前端实时渲染与 human-in-the-loop。
• 权限系统：工具调用决策机制：允许 / 用户审批 / 拒绝。
• Middleware：基于 AOP 模式的 hook 事件拦截机制，灵活扩展推理-行动循环。
• Workspace 与沙箱：在隔离环境中执行工具 —— 本地、Docker、Kubernetes 或 AgentRun 云沙箱
• 多智能体编排： 多种子智能体定义模式，agent_spawn / agent_send + 事件流实时转发。
• 分布式部署：真正的分布式 session 与 memory 管理（Redis / MySQL / PostgreSQL / OSS / COS），跨副本 session 恢复。

官网地址：https://java.agentscope.io/

GitHub地址：https://github.com/agentscope-ai/agentscope-java

03 小试牛刀

我们通过创建具有记忆功能的智能体，所需要的核心类：

io.agentscope.harness.agent.HarnessAgent

3.1 引入依赖

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

2.0 中模型提供商已拆分为独立扩展模块，需额外引入所需的模型依赖。本节的案例使用Ollama，所以需要引入Ollama的相关扩展包。

目前支持的模型：

想通过SpringBoot配置可以直接使用：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-spring-boot-starter</artifactId>
    <version>${agentscope.version}</version>
</dependency>

3.2 创建智能体

/** 工作区路径，存放 AGENTS.md / MEMORY.md / memory/ 等 */
private String workspacePath = "./workspace/harness-demo";

/** Ollama 服务地址 */
private String baseUrl = "http://localhost:11434";

/** Ollama 模型名称 */
private String modelName = "llama3";

private OllamaChatModel createModel() {
    return OllamaChatModel.builder()
            .baseUrl(baseUrl)
            .modelName(modelName)
            .formatter(new OllamaChatFormatter())
            .build();
}


@Bean
public HarnessAgent memoryAssistantAgent() {
    // 确保 workspace 目录存在（HarnessAgent 要求 AGENTS.md 所在目录可访问）
    java.nio.file.Path wsPath = Paths.get(workspacePath).toAbsolutePath().normalize();
    try {
        java.nio.file.Files.createDirectories(wsPath);
        log.info("  workspace 目录已就绪: {}", wsPath);
    } catch (Exception e) {
        log.warn("  无法创建 workspace 目录: {}，原因: {}", wsPath, e.getMessage());
    }

    HarnessAgent agent = HarnessAgent.builder()
            .name("MemoryAssistant")
            .sysPrompt("""
                    你是一个具有记忆能力的智能助手，名叫"记忆助手"。

                    核心能力：
                    1. 记住用户在对话中分享的个人信息（姓名、偏好、计划等）
                    2. 在后续对话中主动引用之前记住的信息
                    3. 当用户问"你还记得什么"时，列出记住的所有内容
                    4. 使用工具完成计算、时间查询等任务

                    行为准则：
                    - 每次对话开始时，如果之前有记忆，先回顾用户之前说过的重要内容
                    - 记住新信息时，明确说"我已经记住了"
                    - 保持友好、简洁的对话风格
                    - 回答使用中文""")
            .model(createModel())
            .workspace(wsPath)
            // ===== 对话压缩：消息达30条自动压缩，保留最近10条 =====
            .compaction(CompactionConfig.builder()
                    .triggerMessages(30)
                    .keepMessages(10)
                    .build())
            .build();

    log.info("  HarnessAgent 创建成功, name={}, class={}", agent.getName(), agent.getClass().getName());
    return agent;
}

创建智能体的主要参数：

• name：智能体的名字
• sysPrompt：系统提示词
• model：使用的模型
• workspace：智能体的工作空间

3.3 智能体控制层

private final HarnessAgent memoryAssistantAgent;

/** 构建 RuntimeContext，sessionId 为空时自动生成 */
private static RuntimeContext buildContext(String sessionId) {
    String sid = (sessionId != null && !sessionId.isEmpty())
            ? sessionId
            : UUID.randomUUID().toString().substring(0, 8);
    return RuntimeContext.builder()
            .sessionId(sid)
            .userId("demo-user")
            .build();
}


@PostMapping("/chat")
public void chat(@RequestBody ChatRequest request) {
    String sessionId = request.getSessionId();
    RuntimeContext ctx = buildContext(sessionId);
    String effectiveSessionId = ctx.getSessionId();

    log.info("[Harness-chat] sessionId={}, message={}", effectiveSessionId, request.getMessage());

    memoryAssistantAgent.call(new UserMessage(request.getMessage()), ctx).block();
}

3.4 测试

启动之后。我们会发现HarnessAgent自动创建成功。

第一轮对话参数:

{
    "sessionId": "A001",
    "message": "司空长风是雪月城的二城主"
}

响应结果：

第二轮对话参数：

{
    "sessionId": "A001",
    "message": "司空长风是谁"
}

响应结果：

3.5 自动生成的文件

Session管理

里面记录了每次对话的记录。

workspace

根据代码：

private String workspacePath = "./workspace/harness-demo";

会在当前你项目生成记忆文档

04 小结

这里只是简单了搭建了一个技术点，还可以通过@Tool实现Function Call、数据库的持久化、Hook、React、多智能体等。

有兴趣的可以深入探索