agentscope-java

1. Project Overview

AgentScope Java is a production-ready Java framework for building distributed, enterprise-grade AI agents with built-in support for long-running, safely-controlled execution — it takes agent development beyond prototyping and into operational, multi-tenant production environments.

2. Background & Positioning

• Core mission: Most agent frameworks focus on making a single agent "work" in a demo. AgentScope Java (version 2.0) was built to close the gap between a working prototype and a system that can run reliably in production — with observability, permission control, sandboxing, and distributed session recovery as first-class concerns rather than afterthoughts.
• How it differs from similar projects: Rather than being just a thin wrapper around LLM calls, AgentScope Java layers a "harness" on top of the classic ReAct (reason-act) loop — adding middleware hooks, a typed event stream, human-in-the-loop approval gates, and pluggable sandboxes (local, Docker, Kubernetes, or cloud). It is designed natively for the JVM ecosystem, making it a natural fit for teams that already run Java/Spring-based backend infrastructure and want enterprise-grade agent capabilities without leaving that ecosystem.

3. Feature Categories

• ⚙️ Foundation Framework — Core primitives for building agents. Representative examples: 28 typed events for streaming agent state, unified content blocks (text/files/images/audio/video), the ReAct execution loop, and human-in-the-loop as a built-in interaction pattern. Purpose: give developers a consistent, typed vocabulary for agent behavior instead of ad-hoc JSON payloads.
• 🧩 Harness Engineering — Middleware layered over the core loop. Representative examples: self-evolving skill repositories, layered memory (conversation history + curated markdown + fact logs), sub-agent spawning, automatic context management, and a "plan mode" for multi-step tasks. Purpose: extend and customize how an agent reasons and acts without modifying core framework code.
• 🏢 Enterprise Deployment — Capabilities for running agents at scale. Representative examples: multi-tenant isolation, secure sandboxing, fine-grained permission controls, and cross-replica session recovery for zero-downtime rolling updates. Purpose: make agents safe and resilient to run behind real production traffic.
• 🔌 Integrations — Modular connectors to the outside world. Representative examples: LLM providers (OpenAI, Anthropic, DashScope, Gemini, DeepSeek, Ollama), enterprise IM channels (DingTalk, Feishu, WeCom), and interoperability protocols (A2A, AG-UI). Purpose: let agents plug into existing model vendors and communication tools without custom glue code.
• 💾 State & Persistence — Backends for storing agent and session state. Representative examples: in-memory, JSON file, MySQL, Redis, and PostgreSQL. Purpose: allow agents to resume and recover state across restarts or replicas.

4. Key Highlights

• Typed event stream — 28 distinct event types give frontends and orchestrators precise, structured visibility into what an agent is doing in real time, rather than parsing free-text logs.
• Human-in-the-loop by design — A permission system lets operators selectively approve or deny individual tool calls before they execute, which is critical for agents that can take real-world actions.
• Middleware-based extensibility — AOP-style hooks intercept the reasoning-acting loop at five distinct stages, so teams can add logging, guardrails, or custom logic without forking the core.
• Flexible sandboxing — Tool execution can be isolated locally, in Docker, in Kubernetes, or in the AgentRun cloud environment, matching the isolation level to the sensitivity of the workload.
• Multi-agent orchestration — Native agent_spawn and agent_send primitives support subagent patterns with real-time event forwarding between parent and child agents.
• Distributed session recovery — Session state can survive replica restarts and rolling deployments using Redis, MySQL, PostgreSQL, OSS, or COS as backing stores.

5. Use Cases by Role

• General developers: Build agentic features (chatbots, task automation, tool-using assistants) directly in Java/Spring applications using familiar Maven dependencies instead of bridging to a Python service.
• DevOps/SRE: Deploy agents behind rolling updates with confidence, since session state and in-flight tasks can recover across replicas rather than being lost on redeploy.
• Project managers: Use the permission system and event stream to enforce human review gates on sensitive agent actions, giving oversight into what agents are doing before they act.

6. Getting Started

• How to find what you need: Browse the module layout in the repository (agentscope-core, agentscope-harness, agentscope-extensions, agentscope-examples) or read the full documentation at java.agentscope.io.
• How to install/integrate: Requires JDK 17+. Add the harness module as a Maven dependency:

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

  Then create an agent:

  HarnessAgent agent = HarnessAgent.builder()
      .name("assistant")
      .model("dashscope:qwen-plus")
      .workspace(Paths.get(".agentscope/workspace"))
      .build();
  
  agent.call(new UserMessage("Hello!"), ctx).block();
  

• How to contribute: Fork the repository at github.com/agentscope-ai/agentscope-java, review the contribution guidelines, and open a pull request. Join the community via Discord, DingTalk, or WeChat for discussion before larger contributions.

7. Project Structure

agentscope-java/
├── agentscope-core/               # Core framework: events, content blocks, ReAct loop
├── agentscope-harness/            # Production harness: middleware, memory, plan mode
├── agentscope-extensions/         # LLM provider and channel integrations
├── agentscope-service/            # Control plane and dashboard
├── agentscope-distribution/       # Distribution packaging
├── agentscope-dependencies-bom/   # Centralized dependency version management
├── agentscope-examples/           # Example implementations and quick-start code
└── docs/                          # Documentation source

Key directories: agentscope-core holds the foundational abstractions every agent is built on; agentscope-harness is what most application developers depend on directly, since it wraps the core with production-grade middleware; agentscope-extensions is where new LLM providers or channel integrations are added.

8. Related Ecosystem

• Upstream dependencies: LLM providers — OpenAI, Anthropic, DashScope (Alibaba Cloud), Google Gemini, DeepSeek, and Ollama (for local models).
• Deployment targets: Docker and Kubernetes for sandboxing; Redis, MySQL, and PostgreSQL for state persistence; OSS and COS (cloud object storage) for distributed recovery data.
• Complementary tools: Enterprise IM platforms DingTalk, Feishu, and WeCom for chat-based agent deployment; A2A and AG-UI protocols for interoperability with other agent ecosystems.
• Sibling project: AgentScope (Python), the original framework this Java implementation is conceptually aligned with, for teams working across both language ecosystems.

9. License

Licensed under the Apache License 2.0.

• ✅ Free to use, modify, and distribute, including in commercial and proprietary products.
• ✅ Permits patent use grants from contributors.
• ❌ Provides no warranty — the software is offered "as is."
• ℹ️ Modified files should retain attribution notices, and a copy of the license must be included when redistributing.

10. FAQ

Q: Do I need to know Python to use AgentScope Java?
A: No. AgentScope Java is a native JVM framework (JDK 17+) with its own Maven artifacts — no Python runtime or bridge is required.

Q: Which LLM providers are supported out of the box?
A: OpenAI, Anthropic, DashScope (Alibaba), Gemini, DeepSeek, and Ollama are supported as modular extension integrations.

Q: Can agents run untrusted or risky tool calls safely?
A: Yes. The built-in permission system lets you gate individual tool calls for manual approval, and the workspace/sandbox layer can isolate execution in Docker, Kubernetes, or a cloud sandbox (AgentRun).

Q: What happens to agent state if a service instance restarts or is rolled out?
A: Sessions can be persisted to Redis, MySQL, or PostgreSQL, allowing cross-replica recovery during rolling deployments without losing in-progress work.

Q: How do I coordinate multiple agents working together?
A: Use the agent_spawn and agent_send primitives to create subagents and forward events between them in real time.

11. Quick Links

• Repository: github.com/agentscope-ai/agentscope-java
• Official documentation: java.agentscope.io
• Contributing: See the repository's contribution guidelines for pull request and issue conventions.
• Community: Discord, DingTalk, and WeChat channels linked from the repository README.

12. Summary

AgentScope Java brings production-grade agent infrastructure — typed events, permission gating, sandboxing, and distributed session recovery — natively to the JVM ecosystem. It is best suited for Java and Spring teams that want to build long-running, enterprise-grade AI agents without adopting a separate Python-based stack, and for organizations that need operational guarantees like human oversight and zero-downtime deployment around their agents from day one.