AgentScope Java 2.0.0-RC1

AgentScope Java steps up from a "build an agent" toolkit toward a complete platform for running agents in production.

2.0 aims to preserve compatibility with 1.x where possible so that most users can upgrade smoothly — see the Migration Guide below.

Full docs: docs/v2/en, docs/v2/zh · Full changelog: change-log.md (java.agentscope.io)

Highlights

🧰 Harness engineering — the harness scaffolding for long-running tasks, layered on top of the ReAct core:

• Self-evolving Markdown skill repository under workspace/skills/, shared across sessions
• Layered memory: in-context conversation / MEMORY.md / append-only fact log, with auto-compaction
• Sub-agents declared in Markdown, spawned sync or in background; completions pushed back via system-reminder
• Plan Mode + persistent workspace/plans/ to decouple intent from action
• Workspace as the single on-disk source of persona, knowledge, skills, sub-agent specs

🏢 Enterprise-grade distributed deployment — stateless horizontal scaling out of the box:

• session / user / agent / org multi-tenant isolation via AbstractFilesystem
• Sandbox execution (local / Docker / remote AgentRun) with snapshot & resume
• Three-state PermissionEngine (allow / approve / deny) with HITL as a first-class concern
• Session abstraction (InMemory / JsonSession / MySQL / Redis) for zero-downtime rolling deploys

⚙️ Foundation framework upgrade — leaner, more orthogonal core:

• agent.streamEvents() → Flux<AgentEvent> covering 28 typed events (model calls, deltas, tool execution, HITL)
• Unified ContentBlock message model with role-strict construction
• Five-stage Middleware (onAgent / onReasoning / onActing / onModelCall / onSystemPrompt) replaces v1 hooks
• ModelRegistry resolves "provider:model" strings; Builder gains .maxRetries(int) / .fallbackModel(...) for auto-retry

Quick start

:::xml
<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-harness</artifactId>
  <version>2.0.0-RC1</version>
</dependency>

:::java
var agent = HarnessAgent.builder()
    .name("coder")
    .model("qwen-max")
    .workspace(Paths.get(".agentscope/workspace"))
    .filesystem(new DockerFilesystemSpec().isolationScope(IsolationScope.USER))
    .build();

agent.call(msg, RuntimeContext.builder().sessionId("demo").userId("alice").build()).block();

Migration Guide

Required — compile errors or runtime exceptions if you don't migrate

• ReActAgent.Builder.memory(...) / .statePersistence(...) removed → .session(...).sessionKey(...); Session auto save/load on every call()
• io.agentscope.core.session.SessionManager removed → configure Session + SessionKey on the builder
• io.agentscope.core.pipeline.* (Pipeline, SequentialPipeline, FanoutPipeline, MsgHub) removed → middleware + sub-agents + event stream
• io.agentscope.core.model.tts.* (14 files) removed → integrate upstream TTS SDK directly
• state package restructure: AgentMetaState → AgentState; StateModule / StatePersistence removed; ToolkitState moved to session.legacy
• Msg content is now validated against role at construction (USER allows only Text/Data/Image/Audio/Video; SYSTEM only Text) → prefer UserMessage / AssistantMessage / SystemMessage / ToolResultMessage

Recommended — @Deprecated(forRemoval = true), removed in the next minor

• SkillBox → AgentSkillRepository via Builder.skillRepository(...)
• Entire io.agentscope.core.hook package → Middleware (old hooks bridged via LegacyHookDispatcher)
• Memory and all implementations → AgentState.getContext() + Session
• All Flux<Event> stream(...) overloads → streamEvents() returning Flux<AgentEvent> (aligns with Python 2.0's reply_stream())
• RAG (Knowledge / KnowledgeRetrievalTools / RAGMode) and long-term memory modules deprecated — being rewritten on the v2 architecture; don't depend on them in new code
• tool.coding.* / tool.file.* deprecated (no workspace/permission isolation) → use the agentscope-harness equivalents

Links

• Quickstart · Harness · Full Changelog
• Issues · Discussions