AgentScope Java
A Java framework for distributed, long-running, production-grade agents.
Per-dimension scores and reasoning
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.
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.
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 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().
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.