AgentScope Java 2.0.1 is the first maintenance release after 2.0.0 GA. It expands the model-provider ecosystem, hardens Harness subagent / HITL / permission behavior, and fixes a set of production-critical issues. Quick links: Quickstart | V1 Migration Guide | Going to Production

Core / Agent

• Middleware execution ordering via MiddlewareBase.order() (higher values wrap outer); ReActAgent.Builder.build() stably sorts descending after all registrations (#2532, #2449)
• Session context clear API on ReActAgent / HarnessAgent to clear model-visible conversation context without creating a new session (#2499, #2496)
• Expose ReActAgent state-cache cleanup APIs for long-lived instances (#2572)
• Emit UserConfirmResultEvent when resuming permission HITL, correlatable with the prior RequireUserConfirmEvent via replyId (#2511)
• Anthropic: support configuring disable_parallel_tool_use (#2257)

Model Providers

• Add OpenAI-compatible extension package as a shared base for third-party compatible vendors (#2208)
• Add DeepSeek as a first-class model provider (deepseek:<model>, DEEPSEEK_API_KEY) (#2307, #2211)
• Add GLM (Zhipu AI) provider and dedicated formatters (#2316)
• Add Kimi (Moonshot AI) provider and dedicated formatters (#2320, #2213)
• Add MiniMax OpenAI-compatible provider (#2299)

Harness / Tools

• Remote subagent event streaming and HITL resume (#2559)
• Wait for async tool results by taskId (#2529)
• Default workspace via AGENTSCOPE_WORKSPACE env var for image packaging (#2310)

AG-UI

• Upgrade AG-UI module event mechanism (#2306, #2202)
• Introduce typed MessageContent / InputContent for multimodal AG-UI messages (#2518, #551)

Spring Boot Starters

• Add Ollama Spring Boot Starter (#2176, #2172)

• Change Toolkit default execution mode to parallel and improve related docs (#2558, follow-up of #2529)
• Abstract session metadata storage to decouple builders from concrete store implementations (#2258, #2068)
• Rebase Kubernetes sandbox store on agent-sandbox CRDs / controllers, with the cluster owning sandbox lifecycle and warm pools (#2308)

Core / Agent

• Prevent pending recovery from consuming HITL approvals (#2109, #2534)
• Apply transformed onModelCall text deltas to the final message so native structured-output parsing does not see stale text (#2469, #2385)
• Repair null streaming tool args from complete raw JSON (#2451, #768)
• Unbind state-saver on ReActAgent.close() to prevent graceful-shutdown registry growth / OOM (#2322, #2321)
• Unbind ShutdownStateSaver on ReActAgent.close() to fix a memory leak (#2384)
• Mark user interrupts with interrupted reason (#2260)
• Handle malformed Unicode when writing agent state files (UnmappableCharacterException) (#2255, #2204)
• Forward reasoning middleware events (e.g. InboxMiddleware HintBlockEvent) to streamEvents() (#2179, #2160)
• Mark ToolResultBlock.error as a structured error (#2174, #2157, #2111)

Model Providers

• DashScope: route qwen3.8-max to the multimodal endpoint (#2553)
• DashScope: preserve SSE error response body so callers can read request_id (#2278, #2197)
• OpenAI: wrap streaming branch in Flux.defer so retries re-issue HTTP requests (#2079)
• OpenAI: terminate stream on [DONE] sentinel (#2104)
• OpenAI: drop non-chunk summary event messages to avoid content duplication (#2367)
• OpenAI: sanitize name field in OpenAIMessageConverter (#2346)
• OpenAI AutoConfiguration: make api-key optional (#2175)
• DeepSeek formatter: preserve system role (#2189, #2168)
• Ollama: honor stream flag in OllamaChatModel (#2415)
• Anthropic: map ToolChoice.None to disable tools (previously incorrectly forced tool use) (#2232, #2221)
• Model provider optimizations and compatibility tweaks (#2474)

Harness / Tools / Sandbox

• Stamp taskId on remote subagent forwarded events (#2575)
• Gate memory prompt guidance on disable flags (#2565)
• Emit subagent end before parent completion to avoid dropped events (#2544)
• Close subagent event stream when the parent is cancelled (#2481, #2480)
• Enforce parent DENY rules for spawned subagents (#2477)
• Preserve RuntimeContext during skill promotion (#2465)
• Enforce Plan Mode for subagents (#2377)
• Reject workspace path traversal (e.g. ../) (#2358)
• Support Windows local shell execution (working-directory commands and charset decoding) (#2304, #2268)
• Isolate static subagent registries by runtime context to prevent multi-tenant crosstalk (#2371, #2328)
• Retain prior summaries in chained compaction to preserve user intent (#2360)
• Preserve skill isolation and tool result history (#2319)
• RemoteFilesystem recursive glob matches files at the search root (#2343)
• Mark optional FilesystemTool params as required=false (#2227)
• Optimize shell-execute working_directory parameter and tool usage hints (#2107)
• Declared subagents inherit parent modelExecutionConfig / toolExecutionConfig (#2252)
• Correct sessionId parameter description (#2195)

Storage / Transport

• PostgreSQL BaseStore schema support (#2273, #2192)
• Fix PostgreSQL upsert SQL syntax error (#2167, #2166)
• Fix JdkHttpTransport SSE stream being cut by absolute timeouts (#1322, #1302)

AgentScope Java 2.0.0 is now Generally Available. This is the first production-ready release of the 2.0 line, marking a milestone in AgentScope Java's evolution into an enterprise-grade harness framework.

Quick links: Quickstart | V1 Migration Guide | Going to Production

AgentScope Java 2.0 is a systematic upgrade centered on one goal: enabling agents to reliably complete tasks. Here is an overview of its core design:

Dual-Layer Agent Architecture

• ReActAgent: A stateless reasoning core providing the "reason → tool call → respond" ReAct loop. In 2.0, agent instances are fully stateless — all per-call mutable state is propagated via Reactor Context, allowing a single instance to safely serve multiple (userId, sessionId) combinations concurrently
• HarnessAgent: Extends ReActAgent through Middleware and Toolkit channels, adding workspace, memory, sandbox, subagents, skills, and plan mode as engineering infrastructure — the core reasoning loop is preserved, only augmented

Message & Event Stream

A unified ContentBlock message model (TextBlock / DataBlock / ToolUseBlock / ToolResultBlock / HintBlock, etc.) paired with streamEvents() emitting 28 typed AgentEvent types, making agent execution observable, interactive, and interruptible. Front-end UIs can follow text deltas, tool calls, user confirmations, and other lifecycle events in real time

Permission System

A new PermissionEngine establishes a three-state decision mechanism for tool calls: allow / require user approval / deny. Decisions are based on static rules, tool type, and input content analysis. Sensitive operations automatically enter a HITL approval flow

Middleware Extension Mechanism

A five-stage onion + pipeline hybrid model (onAgent / onReasoning / onActing / onModelCall / onSystemPrompt), providing flexible extension points for logging, tracing, security checks, business policies, and context injection while keeping the core framework stable

Context Engineering

Structured compaction preserves task objectives, current state, key findings, and next steps. Oversized tool results are automatically offloaded to disk with only placeholders in the context. File tools enforce a "read before edit" policy with built-in caching to reduce redundant IO

Workspace Abstraction

Decouples "what the agent does" from "where it executes." Local filesystem, Docker, Kubernetes, and E2B cloud sandbox backends are unified behind a single interface. A built-in warm-up pool supports parallel RL rollout scenarios

Model Fault Tolerance

A unified Credential + ModelRegistry abstraction covering Qwen / OpenAI / Anthropic / Gemini / DeepSeek / Ollama. Configurable max retries and fallback model — automatic failover when the primary model is unavailable

Enterprise Distributed Deployment

One-line DistributedBackend configuration (Redis / OSS / MySQL / PostgreSQL / COS). AgentStateStore auto-partitions by (userId, sessionId). Cross-replica session recovery, sandbox state snapshots, and subagent cross-replica routing

Protocol Interoperability

Built-in A2A (Agent-to-Agent) and MCP (Model Context Protocol) support, plus AG-UI protocol adaptation, covering standardized inter-agent communication and front-end rendering needs

Multi-Agent Orchestration

Declarative subagent specs (YAML / Markdown), runtime agent_spawn / agent_send with synchronous blocking and background delegation modes. Subagent event streams can be forwarded to the parent's streamEvents() in real time

Skill System

Four-layer skill composition (Classpath / FileSystem / Nacos / Marketplace) + SkillFilter fine-grained filtering + self-learning closed loop (propose → curate → promote)

The following are incremental changes between 2.0.0-RC5 (2026-07-07) and the GA release.

• Fire AllToolsDeniedEvent hook when HITL denies all tool calls, enabling application-level handling of full-denial scenarios (#2083)
• Add guardrails for wait_async_results to prevent repeated long blocking waits (#2093)
• Add PostgresDistributedStore for PostgreSQL-backed distributed HarnessAgent state (#2054)
• Add builder customizers for OpenAI, DashScope, and Anthropic models in Spring Boot starters (#2045)

Core / Agent

• Make seedSystemMsg reactive to avoid block() on NIO threads (#2086)
• Include ASKING ToolUseBlocks in PERMISSION_ASKING result message (#2082)
• Activate SkillToolGroup via activateOnSkill field (#2057)
• Save agent state on user interrupt to prevent session loss (#1970)

Model Providers

• Anthropic: split parallel tool calls into alternating messages to comply with API requirements (#2090)
• OpenAI: make nativeStructuredOutput configurable (#2069)

Harness / Tools / Sandbox

• External tool execution now correctly produces a suspended result (#2071)
• Allow SkillLoadTool in Plan Mode by promoting isReadOnly to the AgentTool interface (#2067)
• Interrupt orphan subagents when AgentSpawnTool parent subscription cancels (#2064)
• Remove unnecessary ReActAgent type restriction in MemoryFlushMiddleware (#2078)
• Resolve leading / paths relative to workspace in ROOTED mode (#2049)
• Pre-stage marketplace skills before workspace projection (#2059)
• Treat null exit code as success in Kubernetes hydrateWithArchive (#1915)
• Use updated WorkspaceSpec when resuming from persisted state (#1928)
• Support nested JSON and banner prefix in AgentRun MCP response (#1930)
• Use resolved workingDir for Docker workspaceRoot (#2033)

Channel

• Include PeerKind in OutboundAddress to fix group message routing (#2060)

A2A

• Merge streaming text chunks to avoid fragmentation (#2058)

This release completes the model-provider modularization (all providers extracted from agentscope-core into independent agentscope-extensions-model-* modules), adds unified multimodal DataBlock support across all providers, introduces native structured output for tool calls, and includes 30+ bug fixes spanning agent lifecycle, sandbox, tracing, A2A, and subagent propagation.

• Model provider modularization: OpenAI, Gemini, Anthropic, DashScope, and Ollama model providers have been moved from agentscope-core into separate agentscope-extensions-model-* extension modules. Applications must add the corresponding extension dependency. (#1890, #1916, #1947, #1972)

• Unified DataBlock support in all provider message converters (OpenAI, DashScope, Gemini, Anthropic), covering single-agent, multi-agent, and tool-result paths (#1933)
• Native structured output handling with tools — models that support structured output can now enforce JSON schema constraints alongside tool calls (#1904)
• Native structured output support for DashScope models (#1935)
• httpRequestCustomizer support in McpClientBuilder for dynamic token injection (e.g. OAuth refresh) (#1992)
• Align AguiEvent with the AG-UI protocol spec — add missing event types (#1862)
• Optional skill allowlist filter for subagents (#1873)
• knownSkillNames support in NacosSkillRepository (#1853)
• CosAgentStateStore, CosBaseStore and CosDistributedStore for Tencent Cloud COS-backed state persistence (#1857)
• Expose cached prompt tokens in ChatUsage (#1868)

• Persist agent state on user interrupt recovery (#2008)
• Wire fallback model into ReActAgent (#1851)
• Fix ReActAgent stream event block end ordering (#1829)
• Update ToolResultBlock state before adding to agent context (#1886)
• Reuse classpath skill JAR file systems to avoid resource leaks (#1981)
• Resolve serializeOnKey gate leak in Flux.create callbacks (#1796)

• Map thinkingBudget to OpenAI-compatible API request (#2028)
• Fix Anthropic stream thinking event handling (#1943)
• Preserve executionConfig in OllamaOptions fromOptions/toBuilder (#2011)
• Degrade forced tool choice in DashScope thinking mode (#1882)

• Restore remote snapshot state deserialization — re-inject RemoteSnapshotClient after Jackson round-trip (#2013)
• Fix THROTTLED memory save mode losing state when recreating instances per request (#1788)
• Propagate userId through wakeup dispatch (#2001)
• Run message bus heartbeat on boundedElastic instead of parallel scheduler (#1974)
• Avoid duplicating GracefulShutdownMiddleware in fromAgent (#1952)
• Escape spaces in skill paths returned by ShellPathPolicy (#2031)
• Fallback to simple key-value extraction when YAML parsing fails (#2027)
• Report sandbox file sizes in ls (#1838)
• Normalize Windows list_files paths (#1892)
• Normalize \r\n to \n for file content in LocalFilesystem.edit() (#2020)
• Treat "." as root equivalent in CompositeFilesystem (#1830)
• Validate working_directory to prevent namespace escape (#1834)
• Fall back to LocalFilesystemSpec when no distributed AgentStateStore is configured (#1841)
• Fix WebSocket race in Kubernetes hydrateWithArchive causing exit=null (#1903)
• Tolerate wrapped sandbox base64 downloads (#1866)
• Remove AgentRun sandbox API version prefix (#1891)
• Add connect JSON codec support for E2B sandbox (#1844)

• Fix orphan spans in OtelTracingMiddleware by reading parent OTel Context from Reactor ContextView (#1940)
• Fix child spans not seeing correct parent spans in OtelTracingMiddleware (#1909)
• Propagate Reactor context to chunk event hooks (#1923)

• Propagate parent RuntimeContext to child agents (#1833)
• Propagate parent middleware to subagents (#1843)

• Handle streaming backpressure (#1734)
• Preserve AgentScope message roles across A2A conversion (#1995)

• Propagate run input and frontend tools (#1895)

• Wrap doFlush in Mono.defer to prevent premature evaluation (#1880)

• Nacos auto-configurations should be opt-in (matchIfMissing=false) and fix A2A server-addr override (#1709)
• Add ObjectMapper bean for MarketContributionService in DataAgent (#1993)

• Clarify stream event blockId semantics (#2016)
• Improve model provider documentation (#1986)
• Remove invalid ChatResponse.isLast references (#1921)
• Fix multi-replica Redis example — declare jedis dependency and add stateStore (#1869)
• Fix MemoryCompactionExample to show memory files and fire compaction (#1978)

This release introduces async tool execution and notification support for the agent harness, adds a persistent spawn registry for subagent session recovery, and includes some critical bugfixes.

• Agent harness now supports async tool execution and notifications, including message bus, async tool registry, and scheduled wakeup dispatching (#1802)
• Added String/Message convenience overloads for agent calls; all formatters now support HintBlock (#1802)
• Persistent spawn registry in tool context state enables subagent cross-replica routing and session recovery (#1817)
• DynamicSkillMiddleware implements ToolkitAware to receive the resolved toolkit dynamically (#1828)
• Kubernetes sandbox now supports injecting environment variables into pods (#1789)

• Fixed SIGKILL race condition in Kubernetes file uploads by using two-phase archive strategy (#1826)
• Fixed resource leak where timed-out sub-agents were not interrupted on retry (#1784)
• Fixed typed attributes being lost when copying RuntimeContext (#1813)
• Fixed JdbcStore table initialization failure under MySQL utf8mb4 charset (#1781)
• Made session JSONL offload idempotent to prevent duplicate writes (#1774)
• Fixed OpenTelemetry context propagation in TelemetryTracer (#1799)
• Fixed NPE in OllamaChatModel when options are null during tool choice retrieval (#1803)
• Added missing Jackson annotations to LocalSandboxSnapshot for proper serialization (#1825)
• Fixed sandbox glob not supporting **/ recursive patterns (#1684)
• Fixed SkillFilter matching using composite ID instead of skill name (#1771)
• Allow custom default vision model in MultiModalTool (#1701)

• Fixed incorrect hook signatures in middleware docs (#1835)
• Fixed references to non-existent .sandboxContext() in doc examples (#1792)
• Fixed getToolName() → getToolCallName() in v2 docs (#1760)
• Added AI context menu to documentation site

Please check the documentation for more details.

• Agent result event — a new event is emitted with the final result immediately before agent-end, so streamEvents() consumers can obtain the result directly from the event stream
• Custom events — generic extensible event type for middleware to push application-level notifications (state changes, team updates, etc.) to front-end subscribers without modifying the core event enum
• Hint block events — one-shot event for delivering complete content such as team messages, background tool results, and user interruptions
• Workspace path normalizer — file paths are now automatically normalized to workspace-relative form based on the active filesystem mode, preventing cross-mode prefix collisions
• Tool name on all tool events — tool call delta, end, and result events now carry the tool name directly, so consumers no longer need to cache the name mapping from the start event

• Unified call / stream core — call() and streamEvents() now share a single implementation, ensuring the middleware chain fires consistently on all invocation paths. Legacy standalone call logic has been removed
• Distributed state always fresh — when a state store is configured, agent state and permissions are reloaded from the store at the start of every call, preventing stale cache reads when sessions drift across machines
• Tool result eviction timing — eviction middleware moved to the correct lifecycle phase where tool results are already persisted, fixing a no-op issue in the previous phase
• Simplified file path resolution logic in local filesystem

Please check the documentation for more details.

• Qwen 3.7 model support — added support for Qwen 3.7 series models (e.g. qwen3.7-plus)
• Direct subagent messaging — send messages directly to a spawned subagent and receive its response without going through the parent agent's reasoning loop
• Subagent event stream forwarding — child agent intermediate events (text deltas, tool calls, etc.) are now forwarded in real time, each carrying a source path identifying the originating agent
• Event source tracking — all agent events now carry a source field to distinguish main vs. subagent events within the same stream, enabling consumer-side demuxing
• Custom model and prompt for Compaction / Memory — compaction and memory extraction now support dedicated lightweight models and custom prompts, independent of the agent's primary model
• Channel integration — new extension module family for IM platform integration (DingTalk, Feishu/Lark, WeCom, GitHub, GitLab), with a built-in ChatUI for an out-of-the-box conversational interface
• Unified distributed backend — new single-point configuration that consolidates all distributed storage components (state store, base store, sandbox snapshot) into one setup call. Built-in implementations for Redis, OSS, and MySQL
• Project-writable mode — when enabled, agent file writes are routed by path: workspace metadata goes to the workspace directory; everything else (code, configs) lands in the project directory. Designed for code-generation agents
• Runtime permission mode switching — dynamically adjust the permission mode per session at runtime
• Plan Mode improvements — improved plan file persistence and recovery, smoother tool-chain interaction, more robust approval flow
• Skill self-evolution enhancements — refined the propose → curate → promote closed loop, improved skill matching accuracy and cross-session reuse
• HTTP client timeout and retry policy adjustments
• Model resolution logic improvements
• Agent state records more running statuses

• Agent fully stateless — agents no longer hold mutable per-session state, a single agent instance can safely serve multiple concurrent sessions
• Unified state store — removed legacy session interfaces; unified on a new AgentStateStore abstraction with built-in in-memory, JSON file, Redis, and MySQL implementations, auto-partitioned by user and session
• Base store package renamed — base store interfaces for RemoteFilesystem moved to a new package; update your import paths accordingly
• Extension module coordinates refactored — several extension Maven coordinates have been reorganized by capability (e.g. agentscope-extensions-session-redis → agentscope-extensions-redis). Update <artifactId> in your POM
• Sandbox implementations extracted — concrete sandbox backends (Docker, Kubernetes, E2B, Daytona, AgentRun) moved from harness core into standalone extension modules. Add the corresponding extension explicitly if you need sandbox support

• Fixed permission state losing context during cross-session restoration
• Fixed agentscope-all missing 4 sandbox extension modules

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

🧰 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

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

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();

• 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

• 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

• Quickstart · Harness · Full Changelog
• Issues · Discussions

• Harness subagents — HarnessAgent can delegate work to ephemeral child agents via agent_spawn / agent_send. Declarations come from SubagentDeclaration, workspace/subagents/*.md, built-in general-purpose, or custom factories; remote HTTP subagents are supported.
• Async subagents — Set timeout_seconds=0 to run subagent tasks in the background. Task state is persisted in the workspace and managed with task_output, task_list, and task_cancel.
• Subagent streaming — When the parent uses stream(), synchronous local subagents forward reasoning, tool, and result events into the parent Flux<Event> with EventSource metadata. Nested subagents are supported; call() keeps the previous blocking behavior.
• Tool strict mode — Tools can be configured with strict JSON-schema validation for more reliable model tool calls.
• MCP protocol versions — McpClientBuilder exposes protocolVersions for explicit MCP protocol negotiation.

• DashScope multimodal tool results — Multimodal content parts in tool results are preserved instead of being dropped.
• OpenAI rate-limit retries — Non-standard rate-limit error payloads are parsed correctly so automatic retries can trigger.
• Subagent runtime context — RuntimeContext (e.g. userId) propagates from parent tool calls into child agents for consistent isolation.
• Glob matching — File globs match both workspace-root files and nested paths (e.g. *.md, *.log.jsonl).
• Skill state APIs — Added methods to set skill states programmatically.

• Improved model tool-call handling; E2E support for Qwen 3.5 series models; dependency bumps (PostgreSQL, Micronaut, OpenTelemetry semconv, zstd-jni).

Build your own OpenClaw-style agent that keeps evolving inside a workspace, while the same stack scales to enterprise, distributed deployments and can run tools and code in a securely isolated execution environment.

This release introduces agentscope-harness, a production-oriented layer on top of agentscope-core’s ReActAgent. The single user-facing entry point is HarnessAgent. Harness does not replace the ReAct loop; it injects hooks and a curated toolkit at the right points so agents can answer: what happens on the next turn, the next day, when context explodes, when state is lost, or when work is too heavy for one agent.

A structured workspace directory is the canonical place for persona (AGENTS.md), consolidated long-term memory (MEMORY.md), domain knowledge, skills (skills/), subagent specs (subagents/), and per-agent session data (agents/<agentId>/). Hooks such as WorkspaceContextHook inject workspace content into the system prompt each turn; memory hooks write back so the agent evolves with use, not only within a single chat.

All file-oriented behavior goes through one abstraction so the same agent logic can target:

• Local disk + shell (default): full file tools and optional shell when the backend supports it.
• Remote / shared storage: durable memory and session data for multi-replica deployments; execute is intentionally not registered by default to reduce remote execution risk.
• Sandbox: isolated file and command execution on the sandbox side, with workspace projection and configurable isolation scope (e.g. session vs user vs global) for multi-tenant patterns.

Stable sessionId (and userId for multi-tenant namespaces) drives:

• Serialized runtime snapshots under agents/<agentId>/context/ for cross-process resume.
• JSONL conversation logs under agents/<agentId>/sessions/ for audit and search, alongside compressed model-facing history.

• Two-layer memory: append-only daily notes under memory/, plus background consolidation into MEMORY.md.
• memory_search / memory_get backed by indexed search (e.g. SQLite FTS) so facts stay retrievable without stuffing everything into context.
• Configurable compaction of long threads; context overflow handling with forced compaction and retry where applicable.
• Large tool-result eviction so oversized tool outputs can be spilled to the filesystem and referenced instead of blowing the context window.

Declarative subagents (workspace markdown with front matter, programmatic specs, built-in general-purpose, or custom factories). Synchronous delegation for blocking workflows and asynchronous tasks with IDs and polling via task tools, with safeguards against unbounded subagent recursion.

Filesystem tools (read_file, write_file, edit_file, grep_files, glob_files, list_files), memory and session search/list/history, and subagent/task management are wired for you; execute appears only when the configured backend supports the intended isolation model.

• Local / single-user agents (e.g. personal assistants, coding-style workflows): workspace + optional shell, memory, compaction, skills.
• Enterprise data / analytics agents: sandbox execution, durable sandbox state, shared memory across replicas, subagents for long or parallel work.
• Online business agents: remote filesystem, no shell by default, explicit business tools only, shared session and memory across instances.

Add the io.agentscope:agentscope-harness dependency, prepare a workspace with at least AGENTS.md, build HarnessAgent with RuntimeContext (sessionId, and userId when you need tenant isolation). See the agentscope-examples/harness-example module (e.g. QuickstartExample) and the harness documentation under docs/zh/harness/ (overview, workspace, memory, filesystem, sandbox, subagent, session, tool, architecture) for full detail.

This release introduces Long-term Memory capabilities, bolsters MCP integration, and adds built-in execution tracing mechanisms, alongside an important refactoring of skill metadata and crucial stability improvements across the core framework.

AgentScope-Java v1.0.12 introduces robust support for Bailian long-term memory (#1188). This significantly enhances the ability of agents to maintain context, recall historical interactions, and build continuous relationships over extended operational sessions.

This release provides developers with deeper insights into agent execution and messaging.

• JSONL Trace Exporter: Introduced a built-in JSONL trace exporter via Hook (#983), allowing developers to easily persist detailed, file-based execution traces for offline debugging and analysis.
• OpenTelemetry Focus: Renamed and aligned official documentation to better highlight Observability & Studio with OpenTelemetry tracing guides (#1186, #1107).

We have expanded the Model Context Protocol (MCP) integrations and overhauled how skills are structured.

• MCP Elicitation & Schemas: Added support for the elicitation feature in MCP (#798) and exposed MCP output schemas directly within tool definitions for tighter ecosystem integration (#1221).
• Map-based Skill Metadata: Executed a major refactoring (refactor(skill)!) to replace fixed skill metadata with a flexible, map-based metadata system, removing legacy template-based constructors in SkillBox (#1275).

• Model Integration & Multimodality:

  • Multimodal Message Blocks: Added native support for image and video block parameters within user message content in the core framework (#1193).
  • Model Family Expansion: Added the Qwen3.6 model family to multimodal API endpoint routing (#1179) and implemented a Kimi model check in DashScopeHttpClient (#1314).
  • Gemini Client Support: Added baseUrl builder support for Gemini connections (#1174).

• Core Automation & Execution:

  • Quartz Initial Messages: Supported passing initial input messages in Quartz scheduler workflows (#1227).
  • Modifiable PreCall Events: Updated PreCallEvent handling to be modifiable, aligning it with PreReasoningEvent patterns (#1155).

• Agent, Tool & Memory Stability:

  • Tool Execution Guardrails: Sanitized tool call arguments JSON on interrupted streams to prevent 400 bad requests (#1148). Prevented presetParameters from being erroneously overridden by tool-call input (#1172). Allowed null values for optional nested object fields (#1170).
  • Agent Logic Refinements: Optimized schema parameter handling for structured outputs (#1312). Ensured assistant messages containing tool_calls always include the content field (#1283). Prevented SubAgent name collisions via deterministic hashing for unsupported characters (#1141). Removed redundant hasPendingToolUse checks in core execution (#1162) and fixed three core agent/tool management bugs (#1161, #1167, #1177).
  • Memory Management: Preserved ToolUseBlock structure during large message compression strategies (#1311). Resolved a list modification detection bug during incremental session updates (#1228).

• Skill Management & Data Stores:

  • Skill Robustness: Ensured thread-safe file uploads in SkillBox utilizing fine-grained path locks (#1109). Fixed an issue where an existing skill prevented others from being saved (#1049). Ignored complex YAML frontmatter to prevent parsing failures (#1043). Supported custom charsets for ZIP extraction (#1276) and validated resource paths before activating skills (#1308).
  • Session & RAG Fixes: Ensured MySQL sessions commit writes properly when auto-commit is disabled (#1091). Added missing payload structures for ElasticsearchStore in RAG setups (#1048).

• Observability, UI & A2A Ecosystem:

  • AG-UI Alignment: Converted SUMMARY events into valid AG-UI messages (#1168). Fixed AG-UI reasoning/tool event handling (#1231) and patched a stream state leak causing duplicate events upon retry (#1300).
  • Telemetry Corrections: Utilized max instead of sum for streaming token usage aggregation to report accurate telemetry (#1098). Handled Map types safely in getChatUsage() post-deserialization (#1118).
  • A2A Comms: Fixed A2A Agent lifecycle events to properly support TTSHooks and reasoning completions (#1150). Hardened host fallback mechanisms and guarded against schema definition conflicts in A2A Servers (#1191).

• Dependencies & Build Systems:

  • Resolved dependency conflicts by downgrading json-schema-validator (v3.0.1 to v2.0.0) (#1241) and added spring-boot-configuration-processor to annotation paths (#1116).
  • Fixed missing imports breaking test suites (#1313).
  • Bumped critical dependencies including Milvus-SDK (v2.6.17), Jedis (v7.4.1), OpenTelemetry BOM (v1.61.0), Google GenAI (v1.45.0), Spring WebFlux (v7.0.7), and Micronaut (v4.10.12).

• @miniceM made their first contribution in #798
• @park338 made their first contribution in #983
• @superjvjkdf made their first contribution in #1049
• @Xiaozhiyao made their first contribution in #1091
• @mvanhorn made their first contribution in #1118
• @xichaodong made their first contribution in #1162
• @rrrjqy66 made their first contribution in #1174
• @Fruank4 made their first contribution in #1167
• @lynx009 made their first contribution in #1168
• @RuleViz made their first contribution in #1191

Full Changelog: https://github.com/agentscope-ai/agentscope-java/compare/v1.0.11...v1.0.12