agentscope-java

AgentScope Java 2.0 is a production-ready framework for building distributed, enterprise-grade agents, providing essential abstractions that work with rising model capability and built-in support for long-running, safely-controlled agent execution.

• Event System → A unified event stream with 32 typed events for real-time frontend rendering and human-in-the-loop.
• Permission System → Tool-call gating: allow / require user approval / deny.
• Middleware → AOP-style hook interception for flexibly extending the reasoning-acting loop.
• Workspace & Sandbox → Run tools in isolated environments — local, Docker, Kubernetes, or AgentRun cloud sandbox.
• Multi-Agent Orchestration → Multiple subagent definition patterns with agent_spawn / agent_send and real-time event forwarding.
• Distributed Deployment → True distributed session and memory management (Redis / MySQL / PostgreSQL / OSS / COS) with cross-replica session recovery.
• Agent Evolution → Provides Agent observability and auditing, Agent evaluation and experimentation, and Agent asset management and continuous optimization.

• [2026-08] AgentScope Service: An agent Control Plane and Dashboard for agent observation, registration and orchestration, designed to be compatible with AgentScope, LangChain, ADK, and Claude / Qoder, etc.
• [2026-07] v2.0.0 GA: First production-ready release! Dual-layer agent architecture, event stream, permission system, middleware, workspace sandbox, multi-agent orchestration, and distributed deployment all ready. Docs | Release Notes
• [2026-07] v2.0.0-RC5: Model provider modularization; unified DataBlock multimodal support; native structured output; Channel IM integration; Tencent Cloud COS state persistence. Release Notes
• [2026-06] v2.0.0-RC4: Async tool execution and scheduled wakeup dispatching; subagent cross-replica routing and session recovery. Release Notes
• [2026-06] v2.0.0-RC3: Unified call() / streamEvents() execution core; AgentResultEvent, CustomEvent, HintBlockEvent new event types. Release Notes
• [2026-06] v2.0.0-RC2: Fully stateless agent; one-line DistributedBackend; subagent event forwarding; Channel module (DingTalk, Feishu, WeCom); A2A / AG-UI protocol support. Release Notes
• [2026-05] v2.0.0-RC1: First 2.0 RC — harness engineering, enterprise distributed deployment, event stream / message model / middleware / HITL full redesign. Release Notes
• [2026-05] v1.1.0: Introduced agentscope-harness and HarnessAgent; Workspace (persona / memory / skills / subagents); pluggable filesystem (local / shared store / sandbox); session persistence with cross-process resume; layered memory and context compaction; declarative subagent orchestration. Release Notes

Welcome to join our community on

Discord	DingTalk	WeChat

AgentScope Java requires JDK 17 or higher.

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

Model providers are shipped as separate extension modules in 2.0. Add the one you need — for example, DashScope:

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

Other options: agentscope-extensions-model-openai, agentscope-extensions-model-anthropic, agentscope-extensions-model-gemini, agentscope-extensions-model-ollama. See the Model docs for details.

For typed text and image classification, see OpenAI Decisions, available in 2.1.0-SNAPSHOT builds containing the extension.

To use the reasoning and tool APIs of ReActAgent and compose application capabilities yourself, depend on agentscope-core and your model extension.

Configure a shared Builder at startup, then use builder.build() to create and close an Agent for each request. The same identity and persistent storage keep the conversation across instances. Set DASHSCOPE_API_KEY before running:

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

public class FirstAgent {
    // Configure once at startup; requests only call build().
    private static final HarnessAgent.Builder AGENT_BUILDER = HarnessAgent.builder()
            .name("assistant")
            .agentId("assistant")
            .sysPrompt("You are a helpful AI assistant.")
            .model("dashscope:qwen-plus")
            .workspace(Paths.get(".agentscope/workspace"));

    public static void main(String[] args) {
        try (HarnessAgent agent = AGENT_BUILDER.build()) {
            RuntimeContext ctx = RuntimeContext.builder()
                    .sessionId("demo").userId("alice").build();
            agent.call(new UserMessage("Hello!"), ctx).block();
        }

        // COMMENT_Summarize today in three bullets.
        try (HarnessAgent agent = AGENT_BUILDER.build()) {
            RuntimeContext ctx = RuntimeContext.builder()
                    .sessionId("demo").userId("alice").build();
            agent.streamEvents(new UserMessage("Summarize today in three bullets."), ctx)
                    .doOnNext(event -> {
                        switch (event.getType()) {
                            case TEXT_BLOCK_DELTA -> System.out.print(
                                    ((TextBlockDeltaEvent) event).getDelta());
                            case TOOL_CALL_START -> System.out.println(
                                    "\n[tool] " + ((ToolCallStartEvent) event).getToolCallName());
                            default -> { }
                        }
                    })
                    .blockLast();
        }
    }
}

Start with call / streamEvents for ordinary replies, multi-turn chat and workflow steps; follow the Quick Start. Both also record Harness conversation history by default. Introduce AgentSession when work must continue after a page closes, queue while busy or resume after interruption. The recoverable chat example shows the full integration.

AgentScope Service — an Agent as a Service platform for business applications. Publish capabilities such as proposal writing, document verification, and exception investigation through APIs. Users start work, handle decisions, and review delivery inside their existing product.

• Business integration. Offer background tasks, interactive assistants, or specialist process steps through Endpoints. Applications retain their interface, data authorization, and acceptance rules.
• Persistent work and delivery. Follow status, snapshots, and events through Invocations, handle human interaction, and retrieve results and files for the business process.
• Execution suited to the task. Run AgentScope Harness, connect an existing Agent application, or reuse a Coding Agent. Add Teams and Workflows when needed.

Choose an integration in Use cases, then complete a call with the API quickstart.

AgentScope Java 2.0 is a major step up from a "build an agent" toolkit toward a complete platform for running agents in production. The improvements fall into three focus areas:

A bare ReAct loop solves one reasoning turn. HarnessAgent layers engineering infrastructure on top of ReActAgent via Middleware and Toolkit channels — the reasoning core stays untouched, capabilities layer on:

• Self-evolution & skill repository — successful patterns auto-save as Markdown skills, shared across sessions and loaded on demand
• Layered memory — in-context conversation + agent-curated MEMORY.md + on-disk fact log, with auto-compaction to bound the prompt
• Sub-agents — declare child agent specs in Markdown, agent_spawn / agent_send at runtime, sync or background delegation
• Auto context management — structured compaction preserves goals / state / findings / next steps; oversized tool results offload to disk
• Plan Mode — read-only planning state for long tasks, plan files persist and drive execution

Production agents must serve many tenants, run untrusted code safely, and survive rolling restarts. AgentScope 2.0 is built for stateless horizontal scaling:

• Multi-tenant isolation — session / user / agent / org dimension isolation, RuntimeContext keys flow through workspace paths, KV namespaces, and sandbox state slots
• Secure sandbox — local subprocess / Docker / Kubernetes / E2B cloud sandbox, with snapshot and resume
• Permission control — three-state engine (allow / approve / deny), sensitive tools require HITL approval
• Session recovery — AgentStateStore (in-memory / JSON file / MySQL / Redis / PostgreSQL) backs zero-downtime rolling deploys

Messages, events, and the extension model are smaller, more orthogonal — HITL and event streaming are part of how the framework runs, not add-ons:

• Event stream — 32 typed events covering model calls, text deltas, tool execution, and user confirmations in real time
• Message model — text / files / images / audio / video / tool results unified into ContentBlock, role-strict validation at construction
• Middleware — onAgent / onReasoning / onActing / onModelCall / onSystemPrompt / onAgentStateReady six stages replace v1's flat hooks
• HITL first class — confirm tool arguments, approve sensitive actions, hand off to external systems, agent pauses and resumes exactly

For the complete architecture overview, see the documentation.

We welcome contributions from the community! Please refer to our CONTRIBUTING.md for guidelines on how to contribute.

AgentScope is released under Apache License 2.0.

All thanks to our contributors: