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.

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

Core / Agent

• Propagate ToolResultBlock.metadata through fine-grained v2 tool-result events (ToolResultTextDeltaEvent / ToolResultDataDeltaEvent / ToolResultEndEvent) so event-stream consumers can access tool-specific context (#2315)
• Introduce AgentProtocolEventBus for pluggable SSE event handling in the agent-protocol layer (#2634)
• State versioning and optimistic concurrency primitives — VersionedState, ConflictPolicy, and ConcurrentSessionModificationException — enabling AgentStateStore implementations to detect and reject stale writes

Middleware

• FinalAnswerFilterMiddleware — an opt-in filter that buffers text events per model call, suppresses intermediate reasoning-round text when a tool call is produced, and emits only the final user-facing answer (#2926, #2872)

Model Providers

• Anthropic prompt caching: set cache_control breakpoints on tools, system, and the last message; surface cache_read_input_tokens and cache_creation_input_tokens in usage (#2350, #2223)
• Anthropic + Gemini ResponseParser read cachedTokens into usage (#2568)
• Explicit no-cache semantics: CACHE_CONTROL=false metadata maps to {"type":"no_cache"} for OpenAI and DashScope converters, so a single message can opt out of caching (#2685, #2684)

Harness / Tools

• deliver_artifact tool for sandboxed agents — an ArtifactDeliveryTarget SPI + tool that lets an agent inside a sandbox hand out produced files; the workspace prompt now references it when a target is configured, and states plainly that no cross-boundary mechanism exists otherwise (#2667, #2663)
• MCP server registration results — an optional McpServerRegistrationListener with SUCCESS / FAILED / SKIPPED terminal states, so host services can identify and retire unhealthy MCP configurations (#2877, #2875)
• description field on SubagentFactoryEntry so the orchestrator gets useful subagent selection context instead of a bare name (#1506, #1504)
• Public Toolkit API to assign an already-registered tool to an additional group (#2836, #2835)
• Stream ranged file reads in ReadFileTool — positive line ranges are read incrementally and stop at the requested end line, avoiding loading the full file into memory (#2402)

AG-UI

• CopilotKit + AG-UI full-stack example covering threads, shared state, generative UI, A2UI workbench, and HITL flows end-to-end (#2554)
• Configure agent interruption on AG-UI disconnect (#2719, #2715)

Console

• Transcript overhaul — one bubble per user question, with text and tool calls rendered as ordered content blocks in chronological order; react-markdown rendering, syntax-highlighted tool I/O cards, SSE auto-reconnect with exponential backoff, and session.error rendering (#2640)

Examples

• User binding preferences CRUD API for the DataAgent example (#2711)
• v2 application-layer RAG example (#2794)

• Move AguiRuntimeContextRequest / AguiRuntimeContextResolver / AguiRequestBodyParser down from the example layer into the extensions-agui protocol layer (#2822)
• Replace the Java service control plane with the Go aistiod control plane, keeping the Java gateway, data, and scheduler planes; the agentscope-builder example is promoted to the top-level agentscope-service module
• Isolate HITL sessions by user — key ThreadSessionManager / AgentResolver by (userId, threadId) so hasMemory and agent reuse no longer mix tenants, and unwrap harness/stop interrupts via AguiUtil.asReActAgent so demo stopThread and processor interrupts target the live session (#2856, #2855)

Core / Agent

• Propagate ChatResponse.metadata to Msg.metadata in ReasoningContext (#2931)
• Propagate agent state load failures instead of silently replacing conversation state with a fresh session on backend / I/O / decoding errors (#2760)
• Preserve caller-supplied permission context when loading legacy v1 session state, so 1.x → 2.0 migration does not silently downgrade to DEFAULT permission mode (#2769, #2768)
• Retry empty final responses instead of finishing silently when a reasoning model emits its answer into reasoning_content with empty content (#2755, #2750)
• Persist the current turn's user input and safe context on model call failure so a resumed session can see the last question (#2799)
• Reconcile dangling tool_use blocks on interrupt before persisting AgentState, fixing a window between reasoning and acting where pending tool calls were left unmatched (#2410, #2409)
• Return suspended results for external tools instead of converting them to generic errors; emit RequireExternalExecutionEvent for suspended tool calls (#1668, #1582)
• Emit ExternalExecutionResultEvent when external tool results resume (#2605)
• Restore event emitter for detached tool calls (#2483)
• Include field path in tool validation error messages (#2718)
• Simplify ReActAgent pending tool and error result handling (#2666)
• Normalize model-call tools in middleware to avoid duplicate or malformed tool definitions (#2756)
• Avoid event-loop blocking in WorkspaceContextMiddleware#onSystemPrompt (#2632)
• Use call-scoped AgentState for ReActAgent shutdown retry recovery so the shutdownInterrupted flag is checked and cleared against the per-session state for the current (userId, sessionId) call, instead of the default session state (#2712, #2708)

Model Providers

• Gemini: apply ModelUtils.applyTimeoutAndRetry to response streams so configured timeout and retry settings take effect (#2356)
• RAGFlow: preserve final retry response body so callers can read error details (#2631)
• RAGFlow: type rerankId as String to match the RAGFlow API (#2776)

Harness / Tools / Sandbox

• Stop skill-cache orphan GC from deleting live directories (#2840, #2787)
• Make Nacos skill source paths Windows-safe (#2921)
• Make memory flush fire-and-forget to unblock conversation completion; add HarnessBackgroundTaskQuiescenceExtension so tests drain background flush before @TempDir teardown (#2777, #2935)
• Handle SIGTERM in Docker keep-alive to avoid 30s stop delay (#2885)
• Bound filesystem search tool output size (#2832)
• Isolate sandbox binding per call to fix concurrent corruption (#2675)
• Make concurrent sandbox uploads safe — unique hydrate temp names and native transfer for relative paths (#2762)
• Fix Windows Docker sandbox session file upload via tar stream (#2557)
• E2B: preserve zero exit code in JSON stream (#2609); reject incomplete process streams without exit code (#2828); reset projection state when recreating sandbox (#2586)
• Kubernetes sandbox: bump fabric8 to 7.8.0 to fix watch NPE with Jackson 2.19+ (#2766); follow redirects so file API downloads survive gateway 307 (#2748)
• Keep persisted snapshot id when resume falls back to fresh create (#2775)
• Add reply IDs to subagent lifecycle events (#2680)
• Inherit memory config in subagents (#2611)
• Make orphan sweep timeout boundary inclusive (#2619)
• Do not downgrade a user-interrupted session to a compaction failure (#2659)

AG-UI

• Assign per-tool result message ids (#2908)
• Emit frontend tool args from fragment deltas (#2874)
• Isolate HITL sessions by user (#2856)
• Emit AG-UI interrupt for permission-type HITL tool confirmation (#2495, #2437)
• Parse request bodies with Jackson 2 codec for Boot 4 / multimodal MessageContent (#2638)
• Suppress ReActAgent handshake events in AG-UI converters (#2639)
• Stop emitting RUN_FINISHED after RUN_ERROR by default (#2646)
• Cancel MVC subscription on disconnect (#2786)

Protocol

• Clear task submit context before publishing terminal status to close an await race in AgentProtocolTaskStore (#2802)

Storage

• MySQL: remove path-separator check from MysqlAgentStateStore session id validation (#2022)

Console / Frontend

• Allow owners to edit agent settings and add model field (#2630)
• Render session.error events in managed session chat (#2598, #2596)
• Add cache-control headers to console static serving (#2607)

Full Changelog: https://github.com/Activiti/Activiti/compare/7.21.0-rc.578...7.21.0-rc.579

Full Changelog: https://github.com/Activiti/Activiti/compare/7.21.0-rc.577...7.21.0-rc.578

• d2d3149: [build] add a daily workflow to update the pinned CDDL specs (#17972) (Titus Fortner) #17972
• 9d0ae9e: [py] resolve aliased CddlType members when generating BiDi annotations (Titus Fortner)
• 56e5c61: [py] stop sharing the default ClientConfig proxy between instances (Titus Fortner)
• f580b8d: [build] fix invalid escape sequence in the Java atom line format (Titus Fortner)
• 23c8a89: [py] fix swapped assert arguments in async script array tests (Titus Fortner)
• 50cc58f: [py] add missing assert in device serial options test (Titus Fortner)
• 802accd: [py] remove no-op port self-assignment from the test web server (Titus Fortner)
• ed2dda5: [rust] fix Windows architecture detection under WOW64 (#17987) (Titus Fortner) #17987
• 77ea3d0: [build] build Selenium Manager Linux binaries natively and pin the Rust toolchain (#17988) (Titus Fortner) #17988
• 0a6ea44: [rb] assert Safari returns a sharedId for a located node instead of failing on our own construction (Titus Fortner)
• 539dfe2: [rb] fix local dev execution (Titus Fortner)
• 2e98990: [build] Automated Dependency Update (#17937) (Selenium CI Bot) #17937
• 2df05d0: [rb] report the driver version that actually served each spec run (Titus Fortner)
• 5807971: [build] stop uploading changes.patch as a GitHub release asset (Titus Fortner)

• bdba26c: [java] shrink published javadoc jars (#17957) (Titus Fortner) #17957
• a710cbd: [build] skip redundant Rust tests when releasing (Titus Fortner)
• b0b4a7a: [build] pin the rules_rs zlib bootstrap to an immutable snapshot (#17985) (Titus Fortner) #17985

• 989e662: [grid] Fix 500 when downloading a file whose name contains spaces (#17968) (Ashraf Ali) #17968
• d6bf2fb: [java] add the LICENSE and NOTICE files to the jars created (#17601) (joerg1985) #17601
• f3ccc60: [java] Remove deprecated GET /session/{sessionId}/se/files/{fileName} endpoint (#17982) (Diego Molina) #17982

• When the fluent API was used with XLogger/LoggerWrapper in the slf4j-ext module, caller location was incorrectly reported. To correct this, LoggerWrapper now delegates makeLoggingEventBuilder() to the wrapped logger so that the application caller can be correctly extracted. This issue was reported in issues/464.

• In slf4j-api/DefaultLoggingEventBuilder, a failing toString() invocation on a key-value value, including StackOverflowError, no longer aborts logging. The builder now substitutes [FAILED toString()], matching the existing behaviour of MessageFormatter for message arguments. This issue was reported in issues/448.

• The isLoggable() method in SLF4JPlatformLogger now maps System.Logger.Level.ALL and Level.OFF the same way as log(), that is ALL as TRACE and OFF as ERROR, instead of treating both as always loggable. This is a follow-up to the changes introduced in 2.0.17. See issues/430.

• Published JAR files now package each module's own LICENSE.txt under META-INF/. Previously the parent POM copied the repository-root MIT license into every module, so Apache-2.0 modules such as jcl-over-slf4j and log4j-over-slf4j shipped the wrong license text. This issue was reported in issues/465.

• A bit-wise identical binary of this version can be reproduced by building from source code at commit f0fc3e52a16d5053039495f4f3b64d191508204f associated with the tag v_2.0.19. Release built using Java "21" 2023-10-17 LTS build 21.0.1.+12-LTS-29 under Linux Debian 11.6.

Full Changelog: https://github.com/Activiti/Activiti/compare/7.21.0-rc.576...7.21.0-rc.577