AgentScope Java 2.0 Released: Enterprise‑Ready Multi‑Agent Framework Explained

Introduction

AgentScope Java 2.0 (released June 2026) extends the Python and TypeScript 2.0 releases to the JVM ecosystem. It targets enterprise‑grade scenarios where a demo‑level agent often fails in production because of lost sessions, missing tenant isolation, and unstable runtimes.

Why AgentScope Java 2.0?

Version 1.0 already provided transparent development, but five pain points remain for production use:

Distributed scaling – single‑node agents cannot expand horizontally and lose state on node switches.

Multi‑tenant security – shared environments cause data leakage and file tampering.

Stability – model timeouts, rate limits and errors interrupt tasks without fault‑tolerance.

Permission control – tools can delete system files without boundaries.

Context blow‑up – long conversations accumulate history, leading to memory overflow or loss of relevance.

2.0 makes distributed deployment, multi‑tenant isolation, security, and fault‑tolerance native framework features.

Core Architecture

The architecture spans from the application layer down to infrastructure. Key components are described below.

2.1 ReActAgent vs HarnessAgent

ReActAgent implements the core reasoning loop (think → call tool → observe → think) and is retained from 1.x.

HarnessAgent (recommended entry) wraps ReActAgent with a Builder that adds workspace, session, memory compression, sub‑agents, sandbox, skills, and plan mode. It does not rewrite the reasoning loop; it only binds a RuntimeContext at each call and forces compression/retry when the model reports context overflow. All other capabilities are injected via ReActAgent hooks.

2.2 Workspace

All persistent data is expressed as Markdown or JSON files on disk rather than scattered in code or databases. Important files: workspace/AGENTS.md – agent persona definition. workspace/MEMORY.md – long‑term factual memory. workspace/subagents/<id>.md – sub‑agent declarations.

Benefits:

Auditable : git diff shows persona changes.

Editable : modify AGENTS.md and changes take effect without JVM restart.

Portable : the whole workspace/ directory can be moved to another machine.

Composable : configuration lives in files, eliminating drift between code and config.

2.3 Distributed Deployment

Production replaces the in‑process state store with a distributed backend (Redis, MySQL, OSS, etc.). Three shared objects are used:

RuntimeContext – holds sessionId, userId, extra metadata (per‑call, no persistence).

Workspace – maps file reads/writes to a configurable location (persistent, local or remote).

Session – restores runtime state across calls (persistent via AgentStateStore).

During development the state lives in the local workspace; in production the same code works with a distributed AgentStateStore such as RedisAgentStateStore or MysqlAgentStateStore.

2.4 Multi‑Tenant Isolation

Isolation is enforced end‑to‑end:

RuntimeContext penetration : userId and sessionId travel through workspace paths, storage namespaces, and sandbox slots.

Unified filesystem abstraction : all file operations go through AbstractFilesystem, which automatically scopes reads/writes to the tenant’s namespace.

Three permission levels – ALLOW, REJECT, CONFIRM – let developers choose the granularity of control.

2.5 Middleware Extension Mechanism

Five hook points replace the old 1.x Hook interface:

#1 onAgent: set logging context, bind tenant, init tracing.

#2 onReasoning: inject workspace files into the prompt, check token budget.

#3 onActing: perform permission checks, parameter validation, audit logging before tool calls.

#4 onModelCall: cache responses, trigger retry or downgrade.

#5 onSystemPrompt: dynamically append time‑sensitive info.

Each middleware does one thing, is ordered by priority, and runs automatically once registered.

Hands‑On Walkthrough

3.1 Environment Setup (JDK 17+)

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

3.2 Minimal Chat Agent

package com.example;

import io.agentscope.core.model.OpenAIChatModel;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.harness.HarnessAgent;
import java.nio.file.Path;

public class BasicChatExample {
    public static void main(String[] args) {
        String apiKey = System.getenv("DEEPSEEK_API_KEY");
        // 1. Create model (OpenAI‑compatible)
        OpenAIChatModel model = OpenAIChatModel.builder()
            .apiKey(apiKey)
            .modelName("deepseek-chat")
            .baseUrl("https://api.deepseek.com")
            .stream(true)               // enable streaming output
            .enableThinking(true)       // enable thinking mode
            .build();
        // 2. Build HarnessAgent (recommended entry)
        HarnessAgent agent = HarnessAgent.builder()
            .name("Assistant")
            .sysPrompt("You are a helpful AI assistant, answer briefly.")
            .model(model)
            .workspace(Path.of("./workspace"))
            .build();
        // 3. Call the agent
        UserMessage userMsg = new UserMessage("你好，请介绍一下自己");
        String reply = agent.call(userMsg, RuntimeContext.empty())
            .block()
            .getTextContent();
        System.out.println(reply);
    }
}

Line‑by‑line analysis:

Step 1 configures the model (API key, model name, endpoint) and enables streaming and thinking.

Step 2 builds a HarnessAgent with a workspace directory.

Step 3 creates an empty RuntimeContext; in production you would fill userId and sessionId to obtain multi‑tenant isolation.

3.3 Tool Integration

Annotate any Java method with @Tool to expose it to the LLM:

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;

public class WeatherTools {
    @Tool(description = "查询指定城市的天气")
    public String getWeather(@ToolParam(description = "城市名称") String city) {
        // Call a real weather API here
        return "城市 " + city + " 当前天气：晴朗，24℃";
    }
}

Toolkit toolkit = new Toolkit();
toolkit.register(new WeatherTools());

HarnessAgent agent = HarnessAgent.builder()
    .name("智能天气助手")
    .sysPrompt("你是专业天气助手，可以使用getWeather工具查询天气。")
    .model(model)
    .toolkit(toolkit)
    .workspace(Path.of("./workspace"))
    .build();

The framework scans @Tool annotations, extracts Javadoc and parameter descriptions, and converts them into a JSON schema that the LLM can invoke without manual prompt engineering.

3.4 Streaming Events

Use streamEvents() to receive a typed event flow instead of a single final answer:

agent.streamEvents(userMsg, RuntimeContext.empty())
    .doOnNext(event -> {
        switch (event.getType()) {
            case "reasoning_start":
                System.out.println("🤔 AI 开始思考...");
                break;
            case "text_chunk":
                System.out.print(event.getContent()); // real‑time output
                break;
            case "tool_call":
                System.out.println("🔧 调用工具: " + event.getToolName());
                break;
            case "human_confirmation":
                System.out.println("✋ 需要人工确认: " + event.getMessage());
                break;
        }
    })
    .blockLast();

Event types include REPLY_START/END, MODEL_CALL_START/END, TEXT_BLOCK_DELTA, TOOL_CALL_START/END, TOOL_CALL_RESULT, and HUMAN_INTERVENTION, enabling UI rendering, monitoring, and human‑in‑the‑loop workflows.

Six Core Features

4.1 Model Fault Tolerance & Event Stream

Configure retry and fallback models:

OpenAIChatModel model = OpenAIChatModel.builder()
    .apiKey(apiKey)
    .modelName("gpt-4o")
    .retryConfig(RetryConfig.builder()
        .maxAttempts(3)
        .backoffDelay(1000)
        .backoffMultiplier(2.0)
        .build())
    .fallbackModel(OpenAIChatModel.builder()
        .modelName("gpt-3.5-turbo")
        .apiKey(fallbackApiKey)
        .build())
    .build();

If the primary model fails, the fallback model is invoked automatically, keeping long‑running tasks alive.

4.2 Permission System

Three levels – ALLOW, REJECT, CONFIRM – control tool usage, file access, and command execution. CONFIRM is commonly used for critical business actions, pausing the agent until a human approves.

4.3 Sub‑Agent Orchestration

Agents can spawn sub‑agents at runtime via the agent_spawn tool. Two delegation modes exist:

Synchronous : set timeout_seconds > 0 and wait for the sub‑agent result.

Background : set timeout_seconds = 0 for asynchronous execution with automatic callback.

Sub‑agents are declared in workspace/subagents/<id>.md files, enabling declarative persona and behavior.

Pros & Cons

Advantages

Native distributed deployment with external state stores.

Full‑stack multi‑tenant isolation via RuntimeContext.

File‑driven Workspace provides auditability, hot‑reload, and portability.

Three‑level permission system ensures secure tool usage.

Model retry + fallback plus typed event streams give observability and resilience.

Disadvantages

Steeper learning curve due to concepts like HarnessAgent, Workspace, Middleware, and sub‑agent orchestration.

Ecology is still maturing; documentation and community examples are newer than LangChain4j.

Tied to the JVM ecosystem – not suitable for teams primarily using Python or Go.

Advanced features (e.g., sub‑agent snapshots) require understanding of the underlying persistence mechanisms.

Use‑Case Recommendations

Strongly recommended for:

Enterprise multi‑tenant AI services (customer support, internal service desks).

Kubernetes‑based deployments needing horizontal scaling and zero‑downtime upgrades.

Applications with strict security and audit requirements (finance, compliance, government).

Complex long‑chain tasks such as code review assistants, operations bots, or multi‑step data analysis.

Less suitable for quick prototypes, single‑model chat bots, or non‑Java teams.

Horizontal Comparison

Dimension: Positioning – AgentScope Java 2.0: enterprise distributed agent base; LangChain4j: all‑purpose LLM framework; Spring AI: Spring official AI integration.

Core advantage – AgentScope: distributed deployment, multi‑tenant, Workspace; LangChain4j: rich features, strong RAG, large ecosystem; Spring AI: seamless Spring ecosystem, strong engineering support.

Distributed capability – AgentScope: native (session externalization, state snapshots); LangChain4j: needs manual assembly; Spring AI: relies on Spring Cloud.

Multi‑tenant isolation – AgentScope: end‑to‑end enforced; LangChain4j & Spring AI: application‑level implementation.

Permission system – AgentScope: Allow/Reject/Confirm granularity; others: limited.

Workspace – AgentScope: file‑driven, config‑as‑code; others: ❌ none.

Event stream – AgentScope: native typed events; others: limited.

Sub‑agent orchestration – AgentScope: native dynamic delegation; LangChain4j: manual implementation required; Spring AI: limited support.

Learning curve – AgentScope: medium; LangChain4j: higher; Spring AI: low.

Typical scenario – AgentScope: high‑concurrency multi‑tenant agents; LangChain4j: experimental projects, feature‑rich needs; Spring AI: quick Spring Boot AI integration.

Selection Guidance

Choose AgentScope Java 2.0 when you need high concurrency, strict tenant isolation, and fine‑grained security in a Java‑centric stack.

Choose LangChain4j for the broadest feature set and RAG capabilities outside the Spring ecosystem.

Choose Spring AI for rapid AI feature addition within an existing Spring Boot / Spring Cloud codebase.

Conclusion

AgentScope Java 2.0 is not a simple SDK for calling large models; it is a complete engineering foundation that embeds distributed deployment, multi‑tenant isolation, permission control, model fault‑tolerance, and human‑in‑the‑loop capabilities directly into the framework. It enables Java developers to build production‑grade multi‑agent systems without abandoning their familiar Spring Boot and Kubernetes toolchain.

GitHub project address : https://github.com/agentscope-ai/agentscope-java