# AgentScope Java

> JVM framework for distributed, long-running agents with events, permissions and sandboxes

- Category: Agents & Automation / Multi-Agent Systems
- Language: Java
- Licence: Apache-2.0
- Repository: https://github.com/agentscope-ai/agentscope-java
- Website: https://java.agentscope.io/
- Canonical page: https://ai-tldr.dev/tools/agentscope-java/
- Updated: 2026-07-10

## In short

AgentScope Java is the JVM sibling of the AgentScope family, aimed at production agents that run for a long time and are supervised while they do it. It sits in the Multi-Agent Systems category of the Agents & Automation tools and is open-source, written in Java and licensed Apache-2.0. To get started: add the harness dependency.

## Overview

AgentScope Java is the JVM sibling of the AgentScope family, aimed at production agents that run for a long time and are supervised while they do it. Version 2.0, generally available since July 2026, is built around a dual-layer agent architecture: `agentscope-core` gives you a bare ReAct agent, and `agentscope-harness` adds the workspace, persistence and sandbox machinery on top. It requires JDK 17 or newer and is published to Maven Central under `io.agentscope`.

Four abstractions carry most of the framework's weight. A unified event stream emits 31 typed events so a front end can render a run in real time and a human can step in mid-loop. A permission system gates every tool call as allow, require-approval or deny. AOP-style middleware intercepts hooks in the reasoning-acting loop so behaviour can be extended without forking the loop itself. And a workspace abstraction runs tools in an isolated environment — local, Docker, Kubernetes or the AgentRun cloud sandbox.

For work that spans machines, subagents are defined declaratively and coordinated with `agent_spawn` and `agent_send`, with events forwarded back up to the parent, and session plus memory state is stored in Redis, MySQL, PostgreSQL, OSS or COS so a session recovers across replicas. Model providers ship as separate extension modules in 2.0 — DashScope, OpenAI, Anthropic, Gemini and Ollama — and a companion AgentScope Service acts as a control plane and dashboard for registering, observing and orchestrating agents, including ones built on other frameworks.

## What it does

- Dual-layer architecture — agentscope-core for a bare ReActAgent, agentscope-harness for workspace, persistence and sandbox
- Unified event stream with 31 typed events for real-time rendering and human-in-the-loop intervention
- Permission system gating each tool call as allow, require user approval, or deny
- AOP-style middleware hooks for extending the reasoning-acting loop without rewriting it
- Workspace and sandbox execution across local, Docker, Kubernetes and the AgentRun cloud sandbox
- Declarative subagents with agent_spawn / agent_send, cross-replica routing and event forwarding to the parent
- Distributed session and memory state over Redis, MySQL, PostgreSQL, OSS or COS with cross-replica session recovery
- Pluggable model provider modules (DashScope, OpenAI, Anthropic, Gemini, Ollama), A2A and AG-UI protocol support, and IM channels for DingTalk, Feishu and WeCom

## Getting started

AgentScope Java requires JDK 17 or higher and is consumed as Maven Central dependencies. In 2.0 the model provider is a separate artifact from the framework itself.

1. Add the harness dependency

   Depend on agentscope-harness for the full runtime. If you only want a bare ReActAgent without workspace, persistence or sandbox, depend on agentscope-core alone.

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

2. Add a model provider module

   Pick the extension matching your provider. The other options are agentscope-extensions-model-openai, -anthropic, -gemini and -ollama.

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

3. Build your first agent

   HarnessAgent takes a name, a system prompt and a model string. ModelRegistry resolves the string and reads the matching API-key environment variable — for example OPENAI_API_KEY or DEEPSEEK_API_KEY — automatically.

```java
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;

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

4. Choose an execution mode

   call() runs the agent to completion; streamEvents() exposes the unified event stream so a UI can render tool calls, approvals and results as they happen.

5. Go distributed

   Make the agent stateless, attach a DistributedBackend for session and memory storage, and point the workspace at Docker, Kubernetes or the AgentRun sandbox. The production guide on java.agentscope.io covers the backend options and cross-replica session recovery.

## When to use it

- Reach for it when the agent has to live inside an existing JVM service rather than a Python sidecar
- Reach for it when tool calls need explicit approval gates and a full audit of what the agent did
- Reach for it for long-running agents that must survive a restart and resume on a different replica
- Reach for it when one supervisor agent needs to spawn and coordinate subagents across machines

## Version history

- 2026-07-10 v2.0.0: First production-ready release: dual-layer agent architecture, 31-event stream, permission system, middleware, workspace sandbox, multi-agent orchestration and distributed deployment.
