AgentScope Java
A Java framework for distributed, long-running, production-grade agents.
- Source repo
- agentscope-ai/agentscope-java
- Stars
- ★ 6.3k
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Java
- FA score
- 49/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Java backend team building a multi-tenant agent service that must isolate state by
session,user,agent, andorg. - Not a fit if
- Teams wanting a finished end-user chat app
- Projects that cannot use JDK 17+ and Maven
- Teams unwilling to wire up a model provider and storage
- Source review
- 49/100 · Major gaps
What does this agent do, and when should you use it?
AgentScope Java 2.0 is a production-oriented Java agent framework built around ReActAgent and the engineering-focused HarnessAgent. It supports blocking execution through call() and real-time output through streamEvents(), enabling frontend rendering and human-in-the-loop workflows. Its message model uses ContentBlock for text, files, images, audio, video, and tool results, while the event system defines 28 typed events. HarnessAgent adds workspaces, layered memory, context compaction, Markdown skills, and subagent orchestration; AgentStateStore backends support persisted state and cross-replica session recovery. It fits Java teams prepared to integrate a model provider, storage backend, tools, and deployment environment rather than teams seeking a finished end-user chat application.
Developers configure a HarnessAgent with HarnessAgent.builder(), including a name, system prompt, model, and workspace, then create a RuntimeContext with values such as sessionId and userId. A model can be specified by a string such as "dashscope:qwen-plus", resolved by ModelRegistry, or supplied as a ChatModel; provider support is packaged as separate 2.0 extension modules. The agent accepts a UserMessage and either returns through agent.call(..., ctx).block() or emits a sequence through agent.streamEvents(..., ctx), including text-delta and tool-call-start events. Middleware can intercept the onAgent, onReasoning, onActing, onModelCall, and onSystemPrompt stages, while HarnessAgent can coordinate subagents with agent_spawn and agent_send. Workspaces and tool execution can use local environments, Docker, Kubernetes, or AgentRun cloud sandboxes, and state can be stored in memory, JSON files, MySQL, Redis, or PostgreSQL.
- A Java backend team building a multi-tenant agent service that must isolate state by
session,user,agent, andorg. - An application team that needs to stream text, tool activity, and user-confirmation events into its own real-time frontend.
- A platform team that runs agent tools in local, Docker, or Kubernetes isolation and needs approval gates for sensitive actions.
- An enterprise team that needs sessions to survive rolling deployments or recover on another replica.
- A Java developer delegating long tasks to declared child-agent specifications through
agent_spawnandagent_send.
How do you install or deploy this agent?
Use JDK 17 or later. Add Maven dependency io.agentscope:agentscope-harness:2.0.0, for example: <dependency><groupId>io.agentscope</groupId><artifactId>agentscope-harness</artifactId><version>2.0.0</version></dependency>. Add the model-provider extension you need; for DashScope: <dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-model-dashscope</artifactId><version>2.0.0</version></dependency>. The README also names OpenAI, Anthropic, Gemini, and Ollama extensions. Configure the matching provider API-key environment variable; documented examples include OPENAI_API_KEY and DEEPSEEK_API_KEY. For a bare ReActAgent without workspace, persistence, or sandboxing, depend on agentscope-core only.
How do you use this agent?
Build a HarnessAgent with .name("assistant"), .sysPrompt(...), .model("dashscope:qwen-plus"), and .workspace(Paths.get(".agentscope/workspace")); then build RuntimeContext.builder().sessionId("demo").userId("alice").build(). A first blocking invocation is agent.call(new UserMessage("Hello!"), ctx).block(). For a live UI, use agent.streamEvents(new UserMessage("Summarize today in three bullets."), ctx), handle events such as TEXT_BLOCK_DELTA and TOOL_CALL_START, and finish with .blockLast().
What are this agent's strengths and limitations?
call()andstreamEvents()cover both synchronous requests and real-time event consumption, with events suited to frontend rendering and human intervention.- Its permission system has three explicit outcomes—allow, require approval, and deny—for gated tool calls.
AgentStateStoredocuments in-memory, JSON-file, MySQL, Redis, and PostgreSQL backends, including cross-replica session recovery.- HarnessAgent layers workspace, memory, context compaction, skills, and subagents over ReActAgent for long-running task infrastructure.
- It requires JDK 17+ and a separate provider extension plus API-key configuration for the chosen model.
- Modular providers mean switching providers requires dependency and model-configuration changes; the supplied material does not describe feature parity between providers.
- Sandbox choices such as Docker, Kubernetes, E2B, and AgentRun require the corresponding environment or service to be available.
- A move from 1.x may require adapting to redesigned events, messages, and Middleware; the supplied material describes 2.0 as a major redesign.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AgentScope Java This agent | 49 · Major gaps | Library / SDKFree + model costs | ★ 6.3k | 1d ago | Java | OpenAI API · Claude API |
| Open Swarm | 40 · Major gaps | — | ★ 827 | 25d ago | JavaScript | Claude API |
| AgentScope 2.0 | 70 · Some gaps | Library / SDKFree + model costs | ★ 35k | 2d ago | Python | OpenAI API · Claude API |
| AgentField AI Backend | 45 · Major gaps | CLIFree + model costs | ★ 2.6k | 2d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes permission system (allow/approve/deny) and HITL support, but no implementation details or security audit. User confirmation mechanism exists but not deeply verified. Data flow transparency limited, no detailed explanation of data flow or storage. Sensitive data handling not explicitly mentioned. Dependency security lacks vulnerability scanning or lock files. External effects (tool execution) have sandbox description but not verified. Rollback mechanism not mentioned. Source attribution has contributor list but not verified. Deductions: lack of concrete implementation evidence and verification.
Evidence shows: README and CI config are consistent, build process clear. Dependency availability via Maven Central and CI caching, but not verified. Failure messages not explicit in docs. Deductions: insufficient failure handling details.
Evidence shows: README targets enterprise developers, scenarios clear (distributed, long-running). Capability boundaries clear via module separation (core, harness, extensions). Trigger precision not detailed. Environment fit supports JDK 17+, multiple OS. Deductions: trigger mechanism details insufficient.
Evidence shows: Information architecture clear, with doc links and module separation. Install notes detailed (Maven dependencies). Naming stable (io.agentscope). Examples rich (Hello AgentScope). Known limitations not explicitly listed. License Apache-2.0. Versioning changelog via release notes. Maintenance responsibility not explicit. Deductions: missing known limitations and maintenance responsibility.
Evidence shows: Output usability via event stream and examples. Marginal value high (production-grade framework). Cost-benefit not quantified. Deductions: cost-benefit lacks data.
Evidence shows: Claims in README have doc links, but no independent verification. Cross-source corroboration limited (only README and CI). Fact and inference not clearly separated. Deductions: lack of independent verification and clear separation.
- Specific implementation details of permission system and HITL are not shown in provided files; further code review needed.
- Dependency security lacks vulnerability scanning or lock files; recommend checking dependency versions and known vulnerabilities.
- Rollback mechanism not mentioned; potential risk for production-grade framework.
- Known limitations not listed; users may lack awareness of framework boundaries.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
AgentScope Service 2.1.0-BETA1 预发布现已提供 Docker 镜像、Compose/Helm 安装包，以及 CLI 和 Runtime Host。 安装及使用请参阅[官方中文文档](https://java.agentscope.io/v2/zh/service/index)或 [English documentation](https://java.agentscope.io/v2/en/service/index)。View on GitHub ↗ -
Release notes excerpt
AgentScope Java 2.0.4 adds OpenAI Responses API support, a redesigned AgentScope Service, new channel and storage integrations, and stronger isolation for concurrent agent runs, tools, and skills. Added Core / Models - Add the OpenAI Responses API module ([#3078](https://github.com/agentscope-ai/agentscope-java/pull/3078)). - Support returnDirect tool results to short-circuit the reasoning loop ([#2891](https://github.com/agentscope-ai/agentscope-java/pull/2891)). …View on GitHub ↗ -
Release notes excerpt
This release introduces Anthropic prompt caching, a deliver_artifact tool for sandboxed agents, a FinalAnswerFilterMiddleware for ReAct streams, state versioning and optimistic concurrency primitives for agent state stores, an AgentProtocolEventBus for pluggable SSE event handling, and a console transcript overhaul, and includes a broad set of reliability fixes across the core reasoning loop, harness, sandbox, and AG-UI protocol layers. …View on GitHub ↗
FAQ
Which model providers are documented?
ChatModel object to be passed directly.How are sensitive tool actions controlled?
Can sessions survive restarts?
AgentStateStore using JSON files, MySQL, Redis, or PostgreSQL, and the README states that cross-replica session recovery is supported.Is HarnessAgent mandatory?
agentscope-core and ReActAgent; workspace, persistence, and sandbox capabilities are provided by HarnessAgent.