AgentScope Java 2.0: a Maven framework for long-running distributed agents

The problem AgentScope Java 2.0 targets: agents that outlive a request

Most agent demos are a loop in a single process. The agent calls a model, calls a tool, calls the model again, and returns. That shape breaks the moment the agent has to survive a deploy, run for hours, or be approved by a human before it touches production data.

AgentScope Java 2.0 is aimed at that second shape. The README calls it a framework for building distributed, enterprise-grade agents, with built-in support for long-running, safely-controlled agent execution. The audience is a Java team that already has a service tier, a session store and a deployment pipeline, and wants an agent to live inside it rather than beside it.

The framing is explicit in the release history. v2.0.0-RC2 introduced a fully stateless agent and a one-line DistributedBackend. v2.0.0-RC4 added subagent cross-replica routing and session recovery. Those are not features you add to a demo. They are features you add when a request can land on any replica.

Dual-layer architecture: core, harness and the extension modules

The repository is a Maven multi-module build. The top level shows agentscope-core, agentscope-harness, agentscope-extensions, agentscope-service, agentscope-examples, agentscope-distribution and agentscope-dependencies-bom, plus a root pom.xml.

The split matters when you pick dependencies. The README says that if you only need a bare ReActAgent without workspace, persistence or sandbox, you depend on agentscope-core alone. Everything else, meaning the workspace filesystem, session persistence, sandbox execution and declarative subagent orchestration, lives in agentscope-harness. That harness layer arrived in v1.1.0 and is the layer most of the 2.0 documentation describes.

Model providers are separate artifacts rather than a single bundled client. The README lists agentscope-extensions-model-dashscope, agentscope-extensions-model-openai, agentscope-extensions-model-anthropic, agentscope-extensions-model-gemini and agentscope-extensions-model-ollama. The release notes for v2.0.0-RC5 describe this as model provider modularization. The practical consequence is that swapping providers is a pom change, and that you cannot accidentally depend on a provider SDK you did not ask for.

Events, permissions and middleware in the reasoning-acting loop

Three mechanisms sit inside the loop and are worth understanding before you write code.

The event system is a unified stream with 31 typed events, per the README. The stated purpose is real-time frontend rendering and human-in-the-loop. v2.0.0-RC3 added AgentResultEvent, CustomEvent and HintBlockEvent, and unified call() and streamEvents() on one execution core. If you are building a UI that shows what the agent is doing, this is the surface you read from, not log scraping.

The permission system gates tool calls into three outcomes: allow, require user approval, or deny. This is the part that makes long-running execution defensible. An agent that can call a shell tool for six hours needs a policy layer that is not the prompt.

Middleware is AOP-style hook interception, described in the README as a way to extend the reasoning-acting loop. The combination is coherent: events tell you what happened, middleware lets you change what happens, and permissions decide whether it is allowed to happen. What the README does not do is document a rollback path for a denied or partially applied tool call, so plan for that gap yourself.

Installing AgentScope Java with Maven and running a first agent

AgentScope Java requires JDK 17 or higher, per the README. The artifacts are published under the io.agentscope group and the current release is 2.0.1.

Add the harness artifact to your pom. This pulls the agent layer that includes workspace, persistence and sandbox support:

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
</dependency>

Model providers are separate modules in 2.0, so add the one you intend to call. The README gives DashScope as the example:

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-dashscope</artifactId>
    <version>2.0.1</version>
</dependency>

Alternatives named in the README are agentscope-extensions-model-openai, agentscope-extensions-model-anthropic, agentscope-extensions-model-gemini and agentscope-extensions-model-ollama. Pick one; the README does not suggest loading several.

The README's Hello AgentScope example builds a HarnessAgent with a name and a system prompt. The builder comment states that ModelRegistry resolves the model string and reads the matching API-key environment variable automatically, naming OPENAI_API_KEY and DEEPSEEK_API_KEY as examples:

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import java.nio.file.Paths;

public class FirstAgent {
    public static void main(String[] args) {
        HarnessAgent agent = HarnessAgent.builder()
                .name("assistant")
                .sysPrompt("You are a helpful AI assistant.")
                .build();
    }
}

The README excerpt stops inside the builder chain, so the exact accessor for the model string is not shown there. Check the model documentation page for the builder method and the corresponding environment variable before you run this. If you only need a bare ReActAgent, depend on agentscope-core rather than agentscope-harness and skip the workspace wiring entirely.

Where AgentScope Java 2.0 is the wrong tool

The framework assumes infrastructure. Distributed session and memory management is listed against Redis, MySQL, PostgreSQL, OSS and COS, with cross-replica session recovery. If you have none of those and no intention of running more than one replica, you are paying for a harness you will not use. agentscope-core plus a plain ReActAgent is the honest choice at that size.

The API surface is also young. v2.0.0 went GA in July 2026 and v2.0.1 followed on 2026-08-06. The release history shows a rapid RC cadence: RC1 in May 2026, RC2, RC3 and RC4 in June, RC5 in July. Code written against an RC is unlikely to survive unchanged. Budget for that.

There is a documentation gap around failure. The README describes session recovery across replicas but does not document rollback semantics for a tool call that was approved and then failed midway. For an agent that writes files or calls external APIs, that is the case you actually care about. Treat it as unverified until you find it in the docs.

Finally, the licence. The repository has a LICENSE file at the top level and a .licenserc.yaml, but the licence identifier is not stated in the README. Read the LICENSE file before you plan distribution.

AgentScope Java compared with AgentScope Python

The most direct alternative is AgentScope Python, the sibling implementation. The difference is not the agent concept; it is the deployment target. AgentScope Java ships as Maven artifacts under io.agentscope, requires JDK 17 or higher, and its distributed story is built around the session and memory backends a Java service tier already runs: Redis, MySQL, PostgreSQL, OSS and COS. The Python line is the natural choice if your surrounding code is Python and you do not need JVM process management or a Spring-style service tier.

If your team is Java-first and your agents need to survive a rolling deploy, the Python implementation means running a second runtime and a second deployment pipeline next to the one you already operate. That is the real cost comparison, not language preference.

AgentScope Service is a related piece rather than an alternative. The README describes it as an agent control plane and dashboard built on AgentScope Harness, with agent registration, discovery and distributed coordination, and states it is designed to be compatible with AgentScope, LangChain, ADK and Claude / Qoder. That compatibility claim is broad and worth verifying against your own runtime before you rely on it.

Maintenance, upgrades and the licence question

The repository is not archived, and the last push was on 2026-08-06, which is the same date as the v2.0.1 release. The release cadence across 2026 is dense: v1.1.0 in May, five release candidates between May and July, v2.0.0 GA in July, v2.0.1 in August.

That cadence cuts both ways. Fixes arrive quickly. So do breaking changes, and the 2.0 line already restructured the event stream, the message model, middleware and the human-in-the-loop path relative to 1.x. If you are on agentscope-harness from the 1.1.0 era, the migration to 2.0.1 is not a version bump.

The upgrade cost you can control is the model extension boundary. Because each provider is its own artifact, a provider SDK change is a single dependency edit rather than a framework upgrade. Keep that boundary clean and most upgrades shrink to the harness and core artifacts.

On licence: the repository carries a LICENSE file and a .licenserc.yaml, and the README links to ./LICENSE. The README does not state which licence applies. Check that file and the licence headers before you redistribute anything, and treat the absence of a stated identifier as something to resolve rather than assume.

Editorial conclusion

Adopt AgentScope Java 2.0 if you are already on the JVM, need tool-call approval gating and cross-replica session recovery, and can accept a young API surface where v2.0.1 landed on 2026-08-06. Do not adopt it if you want a single-file Python script, if you cannot run JDK 17, or if you need a documented rollback path. Before committing, verify three things in your own environment: that your chosen model extension module resolves at 2.0.1, that the Redis or SQL backend you intend to use is the one the going-to-production page names, and that the permission policy you configure actually emits the events your frontend consumes.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes