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

Why AgentScope Java 2.0 Is Needed

Developers often experience the “Demo Curse”: an agent that works in a proof‑of‑concept quickly collapses in production due to distributed scaling issues, multi‑tenant data leakage, unstable runtimes, missing permission checks, and uncontrolled context growth.

Version 2.0 targets these pain points by making stability, security, and flexible integration first‑class framework features.

Core Architecture

The framework introduces two hierarchical agents:

ReActAgent : the original reasoning‑action loop (think → call tool → observe → think) that remains unchanged.

HarnessAgent (recommended entry) : a thin wrapper around ReActAgent that bundles workspace, session, memory compression, sub‑agents, sandbox, skills, and plan mode via a Builder pattern.

In plain terms, ReActAgent is the engine, while HarnessAgent adds the fuel tank, wheels, brakes, and dashboard.

Workspace Design

All persistent state is expressed as plain Markdown/JSON files under a workspace/ directory: workspace/AGENTS.md: agent persona definition. workspace/MEMORY.md: long‑term factual memory. workspace/subagents/<id>.md: sub‑agent declarations.

This file‑driven approach enables:

Auditability : git diff shows every change.

Hot‑reload : edit a file and the change takes effect without restarting the JVM.

Portability : the whole workspace can be packaged and moved to another machine.

Distributed Deployment

AgentScope treats distributed deployment as a first‑class citizen. The same business code can run on a single node or scale horizontally in Kubernetes. State is externalized to pluggable stores:

RuntimeContext (per‑call, not persisted).

Workspace (file‑based, persisted locally or remotely).

Session (persisted via AgentStateStore implementations such as InMemoryAgentStateStore, JsonFileAgentStateStore, RedisAgentStateStore, MysqlAgentStateStore).

During startup the framework validates configuration consistency, preventing runtime surprises caused by mismatched storage backends.

Multi‑Tenant Isolation

Isolation is enforced end‑to‑end:

RuntimeContext carries userId and sessionId through every file path, storage namespace, and sandbox.

AbstractFilesystem abstracts all file operations; each call is automatically scoped to the current tenant.

Developers simply choose an isolation granularity (per‑conversation, per‑user, or shared tools) and the framework enforces it without additional code.

Middleware Extension Mechanism

Version 2.0 replaces the old Hook API with a five‑point Middleware system that can inject custom logic at key moments of the ReAct loop:

#1 onAgent: before agent initialization (logging, tenant binding, tracing).

#2 onReasoning: before LLM inference (inject workspace files, token budgeting).

#3 onActing: before tool execution (permission check, parameter validation, audit logging).

#4 onModelCall: after model response (caching, retry, downgrade).

#5 onSystemPrompt: during system prompt construction (add time‑sensitive info, replace placeholders).

Each Middleware is single‑purpose, ordered by priority, and activates automatically once registered.

Hands‑On Example

The article walks through building a conversational agent:

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

Key steps:

Configure the model (API key, model name, streaming, thinking mode).

Build a HarnessAgent with a name, system prompt, model, and workspace path.

Call the agent with a UserMessage and an empty RuntimeContext (later you can pass userId / sessionId for multi‑tenant isolation).

Line‑by‑line analysis explains how the Builder pattern sets model parameters, how enableThinking(true) activates internal reasoning, and how the empty context demonstrates the isolation mechanism.

Tool Integration

Using the @Tool annotation, any Java method can be exposed to the agent. The framework scans the annotation, extracts Javadoc, converts it to a JSON schema, and automatically makes the tool callable without manual prompt engineering.

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

When the LLM decides a weather lookup is needed, it calls getWeather transparently.

Model Fault Tolerance & Event Stream

AgentScope wraps model calls with a unified retry configuration and a fallback model. Example configuration retries up to three times with exponential back‑off and falls back from gpt‑4o to gpt‑3.5‑turbo if the primary model fails.

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();

The framework emits a typed event stream covering the whole lifecycle (reply start/end, model call start/end, text chunk, tool call start/end, tool result, human intervention). This enables real‑time UI rendering and fine‑grained observability.

Permission System

Three levels control what an agent can do:

ALLOW : free execution.

REJECT : block the operation.

CONFIRM : pause for human approval (used for critical business actions).

The system integrates with AbstractFilesystem to enforce file‑level access.

Sub‑Agent Orchestration

Agents can dynamically spawn sub‑agents via the built‑in agent_spawn tool. Two delegation modes are supported:

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

Asynchronous : set timeout_seconds = 0 and let the sub‑agent run in the background, notifying the parent when done.

Sub‑agents are declared in workspace/subagents/<id>.md, making their persona and behavior version‑controlled.

Comparison with Other Java Agent Frameworks

A concise side‑by‑side comparison highlights:

AgentScope Java 2.0 : native distributed deployment, full multi‑tenant isolation, file‑driven workspace, typed event stream, robust permission system.

LangChain4j : richer feature set and RAG support but requires manual assembly for distribution and isolation.

Spring AI : seamless Spring Boot integration, lower learning curve, but less built‑in distributed capabilities.

The article recommends AgentScope for high‑concurrency, multi‑tenant, security‑critical enterprise services; LangChain4j for feature‑rich experimental projects; Spring AI for quick Spring‑centric AI prototypes.

Pros & Cons

Advantages

Native distributed deployment with externalizable state.

End‑to‑end multi‑tenant isolation.

Workspace‑driven configuration (git‑friendly).

Three‑level permission control.

Model fault tolerance and observable event stream.

Drawbacks

Steeper learning curve due to new concepts (HarnessAgent, Workspace, Middleware).

Ecosystem still maturing (new release, limited community examples).

Java‑only; teams using other languages must switch to the Python/TypeScript variants.

Advanced features (sub‑agent orchestration, sandbox snapshots) require deeper understanding of the persistence layer.

Suitable Scenarios

Enterprise multi‑tenant AI assistants (customer service, internal help desks).

Kubernetes‑deployed agents needing horizontal scaling.

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

Long‑chain, complex tasks that benefit from sub‑agent delegation.

Conclusion

AgentScope Java 2.0 is not just an SDK for calling LLMs; it is a full‑stack engineering foundation that brings distributed deployment, multi‑tenant safety, observability, and fine‑grained control to Java‑based AI agents, allowing Java developers to stay productive in the large‑model era.

If you found this guide helpful, consider sharing it with peers exploring Java + Agent development.