AgentScope Java 2.0 Unveiled: Major Upgrades for Production‑Ready AI Agents

AgentScope Java Overview

AgentScope Java is an Alibaba‑open‑source, JVM‑based framework that implements the ReAct (Reason‑Act‑Tool) paradigm. Agents decide which tool to invoke and how to reason without hard‑coded workflows, and the framework supports pause, cancel, and human‑in‑the‑loop control.

Key capabilities: multi‑model support (Tongyi Qianwen, OpenAI, Ollama), custom tools via @Tool, cross‑session memory and RAG, multi‑agent collaboration with A2A protocol, enterprise features such as multi‑tenant isolation, sandboxing, three‑state permissions, and distributed session recovery.

2.0 Release Highlights (v2.0.0‑RC4)

1. Harness Engineering – Long‑Running Agents

Skill repository : Successful experiences are persisted as Markdown files and automatically reloaded.

Layered memory : Combines conversation context, a MEMORY.md file, and a disk‑based fact log that compresses automatically.

Sub‑agents : Child agents are declared in Markdown; the main agent dispatches tasks on demand.

Plan mode : Plans are generated first and stored under workspace/plans/ before execution.

The ReAct reasoning loop remains unchanged while the infrastructure for long‑running jobs is added.

2. Enterprise‑Grade Distributed Deployment

Multi‑tenant isolation : Dimensions (session, user, agent, org) are encoded in RuntimeContext and propagated through workspace and storage.

Secure sandbox : Execution can be isolated in a local process, Docker container, or Kubernetes pod, with snapshot‑based recovery.

Three‑state permissions : Allow / approve / reject, with optional human‑in‑the‑loop confirmation for sensitive actions.

Session recovery : State persisted in Redis or MySQL enables any node to take over a user session.

3. Framework Refactor – Development Improvements

Unified message model : Text, images, tool results, etc., are represented by ContentBlock.

Event‑streaming output : streamEvents() returns 28 typed events, enabling real‑time UI rendering.

Middleware replaces Hook : Five lifecycle stages ( onAgent, onReasoning, onActing, onModelCall, onSystemPrompt) clarify extensions.

Model fault tolerance : Automatic retry and fallback to backup models.

Agent Execution Overview

When a long‑running HarnessAgent task runs, the Workspace synchronously updates skills, memory, and plan files so that subsequent turns inherit the accumulated experience.

Hands‑On Examples

Environment : JDK 17+, Maven or Gradle.

Basic Conversational Agent

Maven dependency:

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version>1.0.12</version>
</dependency>

Minimal Java program:

import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.model.DashScopeChatModel;

public class HelloAgent {
    public static void main(String[] args) {
        ReActAgent agent = ReActAgent.builder()
            .name("小助手")
            .sysPrompt("你是一个乐于助人的 AI 助手。")
            .model(DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-max")
                .build())
            .build();
        Msg response = agent.call(Msg.builder().textContent("你好，介绍一下你自己！").build()).block();
        System.out.println(response.getTextContent());
    }
}

Set the environment variable DASHSCOPE_API_KEY (Tongyi Qianwen API key) before running.

Long‑Running Task with HarnessAgent

Maven dependency:

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.0‑RC4</version>
</dependency>

Example:

import io.agentscope.harness.HarnessAgent;
import io.agentscope.harness.context.RuntimeContext;
import io.agentscope.core.message.Msg;
import java.nio.file.Paths;

public class HarnessDemo {
    public static void main(String[] args) {
        var agent = HarnessAgent.builder()
            .name("coder")
            .model("qwen-max")
            .workspace(Paths.get(".agentscope/workspace"))
            .build();
        var ctx = RuntimeContext.builder()
            .sessionId("demo-session")
            .userId("alice")
            .build();
        Msg reply = agent.call(Msg.builder().textContent("帮我列一下当前工作区有哪些文件").build(), ctx).block();
        System.out.println(reply.getTextContent());
    }
}

The combination of Workspace and RuntimeContext stores persona, skills, and memory on disk, ensuring isolation between users and sessions.

Adding a Tool

Define a tool with @Tool annotation; the framework generates the tool description automatically.

public class ToolDemo {
    public static class Calculator {
        @Tool(name = "add", description = "计算两个整数的和")
        public int add(@ToolParam(name = "a", description = "第一个数") int a,
                       @ToolParam(name = "b", description = "第二个数") int b) {
            return a + b;
        }
    }
    public static void main(String[] args) {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new Calculator());
        ReActAgent agent = ReActAgent.builder()
            .name("计算助手")
            .sysPrompt("你可以使用工具帮用户做计算。")
            .model(DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-max")
                .build())
            .toolkit(toolkit)
            .build();
        Msg response = agent.call(Msg.builder().textContent("请帮我算 123 加 456 等于多少").build()).block();
        System.out.println(response.getTextContent());
    }
}

When the user asks a math question, the agent automatically decides to invoke the add tool, demonstrating ReAct’s avoidance of explicit conditional branches.

Real‑Time Streaming Output

Use streamEvents() to receive typed events such as TextDeltaEvent for a typewriter effect.

import io.agentscope.core.ReActAgent;
import io.agentscope.core.event.TextDeltaEvent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.model.DashScopeChatModel;

public class StreamDemo {
    public static void main(String[] args) {
        ReActAgent agent = ReActAgent.builder()
            .name("流式助手")
            .model(DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-max")
                .build())
            .build();
        agent.streamEvents(Msg.builder().textContent("用三句话介绍 AgentScope Java").build())
            .doOnNext(event -> {
                if (event instanceof TextDeltaEvent delta) {
                    System.out.print(delta.getDelta());
                }
            })
            .blockLast();
    }
}

The repository includes StreamingWebExample that demonstrates Spring Boot integration.

Project address: https://github.com/agentscope-ai/agentscope-java