AgentScope Java 2.0: A Distributed, Enterprise‑Grade Foundation for Intelligent Agents

AgentScope is an open‑source framework for building and deploying large‑model‑driven agents. Version 2.0 adds a Java implementation that targets enterprise requirements such as long‑term stability, distributed deployment, zero‑downtime rolling updates, multi‑tenant isolation and security auditing.

1. Distributed session and sandbox management

In development the workspace directory is used locally with zero configuration. In production the state backend can be swapped for a distributed store, externalizing conversation history, context summaries, plans, to‑do lists and permission rules. Sandbox mode additionally packages the container’s cloned repository, dependencies and temporary files into a snapshot stored in object storage or Redis, allowing any replica to restore the full workspace on the next call. The framework validates the configuration at assembly time and aborts start‑up if a remote store is used without also switching the session state.

2. Multi‑tenant isolation across the execution chain

The userId and sessionId fields are propagated through workspace paths, KV namespaces and sandbox slots, driving resource addressing. Developers choose the isolation granularity (per‑conversation, per‑user, shared tools, or global) and the framework enforces data visibility without requiring business code checks.

3. Unified abstract file system layer

All file operations are routed through AbstractFilesystem, which automatically attaches the current session and user identity, isolating reads/writes to the tenant’s namespace. Three backend implementations are supported: local file system (zero‑config, for development), sandbox file system (container‑isolated with snapshot persistence), and remote file system (key‑value or object storage shared across replicas). The same code works unchanged across development, testing and production.

4. Harness – a one‑stop solution for stable, distributed agents

The core ReAct reasoning loop is kept intact, while the HarnessAgent builder adds workspace, filesystem, long‑term memory, context compression, sub‑agent orchestration, sandboxing and planning capabilities. Switching to the harness requires no changes to business logic.

HarnessAgent agent = HarnessAgent.builder()
    .name("demo-agent")
    .model("dashscope:qwen-max") // ModelRegistry resolves, reads DASHSCOPE_API_KEY
    .workspace(Paths.get(".agentscope/workspace")) // AGENTS.md / MEMORY.md / skills / subagents
    .filesystem(new DockerFilesystemSpec()
        .isolationScope(IsolationScope.USER)) // same user shares across sessions
    .build();
agent.call(msg, RuntimeContext.builder()
    .sessionId("demo").userId("alice").build()).block();

5. Context management for long‑running tasks

AgentScope 2.0 upgrades context handling from simple window compression to a structured strategy that retains task goals, current state, key findings, next steps and long‑term information. Large tool results (e.g., git diff, mvn test output) are off‑loaded to the workspace, with only a concise placeholder kept in the prompt. The framework automatically retries compression when the context length is exceeded.

6. Robust model integration

Support for Qwen, Anthropic, DeepSeek, Gemini, OpenAI and others is retained, with a new Credential + ChatModel abstraction and a FallbackModel wrapper that retries and switches to a backup model on failure, timeout or rate‑limit, preserving task continuity.

7. Message and event system

Messages are represented by sealed ContentBlock classes, with DataBlock handling base64 or URL data. The event system streams typed events (model start, text delta, tool call, tool result, user confirmation, external execution) via Project Reactor Flux, enabling front‑ends to subscribe and display real‑time progress.

8. Permission system

Three‑state decisions (allow / user approval / deny) are applied to tool calls, file access and command execution based on static rules, tool type and input content. High‑risk actions trigger a human‑in‑the‑loop (HITL) approval flow.

9. Middleware extensibility

Five hook stages ( onAgent, onReasoning, onActing, onModelCall, onSystemPrompt) let developers inject custom logic such as logging, rate limiting, security checks or dynamic prompt augmentation without modifying the core framework.

Overall, AgentScope Java 2.0 provides a cloud‑native, multi‑tenant, fault‑tolerant foundation for enterprise‑grade AI agents, allowing the same agent code to run locally, in containers or on remote storage with minimal changes.