Build distributed, enterprise-grade agents.
AgentScope Java is the open-source agent framework for the JVM. ReAct reasoning, Harness engineering infrastructure, multi-agent orchestration, and MCP/A2A protocol support — from local prototype to enterprise-scale deployment.
var agent = HarnessAgent.builder() .name("coder") .model("qwen-max") // resolved via ModelRegistry; reads DASHSCOPE_API_KEY .workspace(Paths.get(".agentscope/workspace")) // AGENTS.md · MEMORY.md · skills · subagents .filesystem(new DockerFilesystemSpec() // sandboxed exec: local · Docker · remote KV swap in one line .isolationScope(IsolationScope.USER)) // shared across sessions of the same user .build(); agent.call(msg, RuntimeContext.builder() .sessionId("demo").userId("alice").build()).block();
io.agentscope:agentscope-harness:${agentscope.version}
The engineering scaffolding for agents that stay up.
A bare ReActAgent only solves "one inference turn." HarnessAgent uses the two extension channels — Middleware and Toolkit — to package workspace, memory, sandbox, sub-agents, skills, and Plan Mode into a complete infrastructure for long-running agents. The reasoning loop is left intact; the harness layers on, never replaces.
- Identity persists — the workspace is the agent's persona + long-term memory + domain knowledge, re-injected every turn
- Context stays bounded — auto-compaction, large tool-result offloading, plus context-overflow retry as last-resort
- State is recoverable — same
sessionIdacross processes resumes the full conversation; sandboxes snapshot too - Capabilities accrue — four-layer Skill composition with curation gate; declarative sub-agent orchestration
Make execution observable and interruptible.
Messages flow as typed ContentBlocks — text, files, images, model thinking, tool results. A single call() no longer just returns the final text; it streams typed events: model calls, text deltas, tool invocations, tool results, user confirmations. Human-in-the-loop and permission approvals are first-class framework concerns.
- Typed events —
streamEvents()emits step-by-step; no manual diffing on the frontend - Multi-modal messages —
DataBlockaccepts both base64 and URL data sources - Three-state permission — static rules + tool category + input analysis → allow / approve / deny
- External execution loop — tools can pause for an outside system to complete, then resume the task
The building blocks of a dependable agent system
From model fault-tolerance to sandboxed execution, AgentScope Java 2.0 ships every engineering piece needed to keep an agent stable.
Model fault-tolerance
Unified Credential + ChatModel abstraction across Qwen / OpenAI / Anthropic / Gemini / DeepSeek / Ollama. Configure max retries and a fallback model — the framework auto-switches when the primary is unavailable.
Learn about models →Context engineering
Structured compaction preserves goals / state / key findings / next steps; oversized tool results offload to disk with a placeholder in context; file IO enforces "read-before-edit" to cut redundant reads.
Learn about memory →Middleware
Four onion hooks (onAgent / onReasoning / onActing / onModelCall) plus the onSystemPrompt transformer. Plug in logging, tracing, permission checks, context injection, business policy — all without forking the core.
Workspace abstraction
Decouples "what the agent does" from "where it runs." WorkspaceBase unifies identity, lifecycle, resource discovery, and context offload. Switch local disk, Docker, and E2B cloud sandbox with one line; built-in warm-pool fits RL rollouts.
Learn about workspace →Multi-agent
Declare sub-agent specs in Markdown; the parent spawns them on demand with agent_spawn / agent_send in either synchronous or background mode. Background-task completion is pushed back via a system-reminder — no polling required.
Tools & MCP
Annotation-driven tool registration with automatic batch / sequential / concurrent dispatch by tool attributes. Plug in any MCP-compatible server (filesystem, database, browser, code interpreter) with a central workspace/tools.json allowlist.
Ready to build?
Follow the quickstart and run a ReActAgent in minutes. When you need the long-running engineering layer, swap to HarnessAgent — same reasoning core, capabilities layered in as needed, business code untouched.
Frequently asked
Full Q&A in the FAQ, or ask on GitHub Discussions.
Which Java version is required?
JDK 17 or later. The framework relies on Records, Sealed Classes, and other modern features, and runs on a Project Reactor non-blocking reactive execution model. For ultra-low cold-start latency, compile a GraalVM native image via Quarkus.
Which LLM providers are supported?
Out of the box: OpenAI (and OpenAI-compatible endpoints including vLLM, DeepSeek, Kimi, Moonshot), Anthropic Claude, Alibaba Qwen via DashScope, Google Gemini, xAI Grok, and local Ollama. Each is a dedicated ChatModel implementation behind a unified builder. Retry and a fallback model can be configured at the model layer for graceful failover.
How does Harness differ from a plain ReActAgent?
ReActAgent is the "reason → tool → reply" core loop. HarnessAgent layers in workspace, memory, compaction, sub-agents, sandbox, Plan Mode, and skills via Middleware and Toolkit on top of the same core. Start from ReActAgent; when you need long-running stability, move to HarnessAgent without touching business logic.
Is 2.0 backward-compatible with 1.0?
AgentScope Java 2.0 aims to preserve compatibility with 1.x where possible so that most users can upgrade smoothly. That said, 2.0 does introduce API-level breaking changes (typed events, the permission system, the Middleware stack, the Workspace abstraction, and more). See the Changelog for details.
Does it work with Spring Boot or Quarkus?
Yes. The core modules are framework-agnostic Java libraries — drop them into Spring Boot, Quarkus, Micronaut, or any JVM application. Quarkus can also compile a GraalVM native image for sub-100 ms cold-start.
How does it scale horizontally in production?
AgentScope Java is built for stateless horizontal scaling. Session state is persisted by Session (defaulting to WorkspaceSession); workspaces can be mounted on a remote KV / object store; in sandbox mode even the execution environment itself resumes across calls. Combined with Kubernetes + HPA, any replica can pick up the full context of any user.