Repository navigation
v3.7.0
Highlights
This release adds governance features. This functionality evolves quickly, the behavior and APIs might change between releases without further notice. The SDK uses Akka Runtime 1.7.2.
- Guardrails have a new API. A guardrail runs before each model call, on the final reply of the agent, or before a function tool call or an MCP tool call, and allows or denies it.
- Classifiers map text to a score or a label. Guardrails, evaluators, sanitizers, and application code call a configured classifier by name.
- Evaluators are a new component. The runtime runs an evaluator in the background after an interaction of a bound agent and records the verdict in the ledger. A durable evaluator runs in several steps and resumes after a restart.
- An evaluator binding can set
sampling-ratioto evaluate a share of the interactions, andtrigger-on-failureto also evaluate the failed interactions. - An evaluator reads its own configuration properties with
EvaluationContext.config(). A binding can override a property for one agent. - The ledger client fetches the recorded agent interactions and their evaluations.
- Sanitizers are named configuration entries. Each entry can define where it masks and for which agents. You can implement your own sanitizer. A sanitizer that throws fails the agent request with a
SanitizerException. - Session memory stores the text that the runtime sent to the model, with user messages and tool results masked.
- A control id names the control that a guardrail, sanitizer, or evaluator implements. The runtime records it in the ledger.
- Access control lists can match the SPIFFE identity of the caller, to allow a single component, a component type, or a service.
- EvalKit can run every case several times, and writes each report as a JSON file.
- A tool of an MCP endpoint can return an object type. Akka sends it to the client as structured content and lists an output schema for the tool.
- The runtime retries failed model calls for all built-in model providers. It also retries the model call of a streamed reply when the agent has not emitted any part of the response.
- The Vertex AI model provider has a
thinking-levelsetting for Gemini 3 models. - The runtime adds agent id, flow id, and interaction id headers to each model request. When tracing is on, it also adds the W3C trace context.
- Token usage includes the prompt cache read and write counts, also for autonomous agents and in the ledger.
- The runtime gives an MCP tool result that has the error flag to the model as an error tool result. Tool interceptors and session memory keep the flag.
- The JSON schemas that the SDK generates, for example for tool parameters, list the same properties as Jackson. They apply
@JsonProperty,@JsonIgnore, and naming strategies. TaskClient.result()keeps waiting when a task rule rejects a result, because the agent retries.WebSocketRouteTestercan send request headers and test a rejected upgrade.
Changes that affect existing code
See the SDK 3.7.0 section of the migration guide.
TextGuardrailandSimilarityGuardare deprecated. Alluse-forvalues are deprecated.- A service loads the components of a library jar only when
akka.javasdk.library.componentslists them. Build a component library with thenon-akka-serviceproperty set totrue. RemoteMcpTools.ToolInterceptorgets the tool name of the MCP server. AnullfrominterceptResponsefails the tool call.- The service fails to start when the configuration defines the
regex-sanitizersorpredefined-sanitizerskey ofakka.javasdk.sanitization. Configure each sanitizer as a named entry ofakka.javasdk.sanitization.sanitizers. Sanitizeris deprecated. UseSanitizerClient.- The identity headers are on by default. Set
akka.javasdk.agent.identity-headers = offto turn them off. - Anthropic and Bedrock report cached prompt tokens outside
inputTokens. UsetotalInputTokensfor a count that does not depend on the provider. - A failed Bedrock or Vertex AI model call can fail the agent with another exception type than before. Review an
onFailurehandler that matches on the exception type. JwtClaims.getStringreturns the JSON text of a claim that is not a string, instead of empty. This includesaudience()whenaudis an array. The typed getters, such asexpirationTime(), return numeric and boolean claims.- APIs that were deprecated in SDK 3.5.x are removed. The
itMaven profile is removed. Run integration tests withmvn verify. - The service fails to start when the configuration sets
akka.javasdk.event-sourced-entity.cleanup-deleted-after. Useakka.javasdk.entity.cleanup-deleted-after. - The TestKit uses JUnit 6. The Akka parent POM imports the JUnit BOM, so all JUnit artifacts in a project use the same version.
What's Changed
- chore: merge main into feature/governance by @pvlugter in #1687
- feat: enhanced guardrails - API adaptations by @octonato in #1652
- Merge main into feature/governance by @johanandren in #1694
- feat: evaluator component for agentic evaluations by @pvlugter in #1688
- feat: cross service SPIFFE id propagation by @johanandren in #1681
- feat: SPIFFE id ACLs by @johanandren in #1695
- feat: ledger client for accessing interaction records by @pvlugter in #1699
- feat: introduce initial version of Classifiers (#5334) by @retronym in #1700
- feat: expose multimodal contents to Guardrail by @octonato in #1692
- feat: async guardrails by @octonato in #1714
- feat: sync-first decide/classify with default async variants by @octonato in #1717
- feat: before-agent-response guardrail enforcement by @octonato in #1718
- docs: governance APIs (guardrails, classifiers, evaluators, ledger, SPIFFE) by @retronym in #1712
- Merge main into feature/governance by @retronym in #1726
- docs: apply the writing guide to the governance pages by @retronym in #1723
- feat: workflow evaluator by @aludwiko in #1708
- chore: merging main into governance branch by @octonato in #1892
- chore: renaming WorkflowEvaluator to DurableEvaluator by @aludwiko in #1903
- feat: interactionId in AgentReply by @aludwiko in #1914
- feat: before-model-call guardrail enforcement by @octonato in #1719
- feat: ledger extension to get all evaluations by interaction id by @aludwiko in #1915
- chore: No Co-Authored-By (governance) by @patriknw in #1931
- feat: Make sanitizers configurable and scoped by @patriknw in #1918
- feat: one verdict per evaluation record + evaluation subject with one interaction kind by @aludwiko in #1949
- Auto PR - Bump SDK versions to 3.6.6 by @github-actions[bot] in #1967
- docs: SDK 3.6.6 release notes by @johanandren in #1968
- chore: Add feat to conventional commit prefixes by @patriknw in #1971
- docs: note Homebrew tap trust requirement for the CLI by @mblund in #1973
- feat: control-id for guardrail, sanitizer and evaluator by @patriknw in #1957
- feat: eval report written as JSON file after each experiment by @aludwiko in #1972
- feat: new Guardrail SPI by @octonato in #1978
- Auto PR - Akka Runtime version 1.7.0 by @kalix-bot in #1977
- feat: session memory stores the text that the runtime sent to the model by @patriknw in #1959
- feat: evalkit run cases multiple times by @aludwiko in #1979
- docs: state that the Federation Plane uses short-lived credentials by @JustinPihony in #1984
- Auto PR - Akka Runtime version 1.7.1 by @kalix-bot in #1986
- feat: add ModelCallSimilarityGuard and deprecate SimilarityGuard by @octonato in #1940
- Merge main into feature/governance by @patriknw in #1987
- docs: akka CLI docs by @github-actions[bot] in #1991
- Akka CLI 3.0.77 released by @olofwalker in #1992
- feat: fail startup on blocking response guardrail for streaming agent by @octonato in #1933
- docs: governance docs by @aludwiko in #1956
- chore: merge feature/governance into main by @patriknw in #1996
- feat: inconclusive attempts do not pass by @aludwiko in #1985
- chore: Handle unknown ledger spi enums by @patriknw in #1997
- docs: publish Optimize docs as part of the full docs by @ennru in #1988
- build: reduce Maven Central downloads in CI by @patriknw in #2000
- feat: cache token counts by @johanandren in #1999
- build: enable Coursier cache fallback in the docs job by @patriknw in #2001
- feat: Include controlId on ledger evaluation records by @patriknw in #1989
- build: delete the caches of a closed PR by @patriknw in #2002
- feat: built-in flow-id and agent-id headers in model requests by @patriknw in #1901
- chore: Optimize docs helper; sparse checkout by @ennru in #1998
- chore: License change date for 3.7.0-M1 by @patriknw in #2004
- docs: require database storage autogrow in the BYOK8s readiness checklist by @JustinPihony in #1994
- docs: Fix cost and training CLI commands to match akka optimize by @olofwalker in #2005
- docs: Add tutorial for serving a model in an Akka region by @olofwalker in #2006
- build(docs): improve Markdown conversion speed with one Node process by @ennru in #2009
- docs: describe workflow step timeout and retry behavior for agent steps by @JustinPihony in #2020
- chore: upgrade to using Kalix v1 APIs by @jroper in #1993
- bump: proto-google-common-protos 2.78.0 by @lightbend-tools-secure in #2022
- fix: use surefire 3.1.2 in the parent so JUnit 5.14 tests are discovered by @JustinPihony in #2015
- fix: reject control ids longer than the ledger bound by @aludwiko in #2028
- build(docs): speed up documentation CI builds by @ennru in #2021
- docs: Release notes for SDK 3.7.0-M1 by @patriknw in #2008
- docs: update to optimize 0.8 by @pvlugter in #2034
- fix: read typed JWT claims from the raw claim value by @efgpinto in #2029
- Auto PR - Akka Runtime version 1.7.2 by @kalix-bot in #2040
- feat: pass the evaluation telemetry context to evaluator clients by @aludwiko in #1974
- docs: model retry doc improvements by @johanandren in #1975
- docs: Release notes for Akka Runtime 1.7.2 by @patriknw in #2049
- docs: add backup and restore gates to the production readiness checklists by @JustinPihony in #2044
- docs: use review instead of walk in the production readiness pages by @JustinPihony in #2047
- docs: add code review items to the production readiness checklists by @JustinPihony in #2046
- feat: ToolCallGuardrails on MCP tools by @octonato in #1995
- build: limit what libraries gets autobumps by @johanandren in #2050
- feat: SanitizerException and SANITIZER failure reason by @patriknw in #2035
- feat: WebSocketRouteTester support for request headers and rejected upgrades by @johanandren in #2048
- fix: keep MCP tool error flag in interceptors and session memory by @johanandren in #2041
- feat: cache tokens for autonomous agent and ledger by @johanandren in #2030
- feat: sampling ratio and trigger on failure for an evaluator binding by @patriknw in #2019
- chore: Remove deprecated since 3.5.x by @patriknw in #2027
- feat: cancelled failure reason of the ledger client by @patriknw in #2026
- chore: License change date for 3.7.0-M2 by @patriknw in #2055
- bump: sbt-java-formatter 0.14.0 (was 0.13.1) by @lightbend-tools-secure in #2038
- docs: make installing through your AI harness the default setup and move the CLI install into Getting started by @TylerJewell in #2058
- docs: move logging in to its own Getting started page by @TylerJewell in #2059
- docs: add a CLI conventions page to the reference by @TylerJewell in #2060
- docs: say that login is for remote Akka Platform environments and link to the login page by @TylerJewell in #2061
- docs: organize the CLI reference by domain and reduce Operating's CLI pages to platform tasks by @TylerJewell in #2064
- docs: align the Inference pages with the akka models CLI and reduce the section to two levels by @TylerJewell in #2065
- docs: render the generated CLI blocks as source blocks and fix the optimize output formats by @TylerJewell in #2067
- docs: add production readiness page for Akka Optimize by @JustinPihony in #2010
- docs: present the data flows as a full-screen grid by @TylerJewell in #2052
- docs: retire Using the Akka CLI so each of its tasks has one home in Operating by @TylerJewell in #2072
- docs: fix contradictions in the Understanding section by @TylerJewell in #2077
- docs: explain JWT validation on WebSocket methods by @efgpinto in #2076
- chore: more ForwardCompat.knownOr usages by @octonato in #2062
- docs: present the Akka Agentic AI Platform in About Akka by @TylerJewell in #2078
- docs: rebuild Understanding to explain every platform concept by @TylerJewell in #2080
- bump: awaitility 4.3.0 (was 4.2.2) by @lightbend-tools-secure in #2084
- bump: maven-core 3.10.0 (was 3.9.16) by @lightbend-tools-secure in #2083
- bump: guava 33.7.2-jre (was 33.3.1-jre) by @lightbend-tools-secure in #2082
- docs: restructure Operating to two levels with one set of readiness pages by @TylerJewell in #2081
- docs: Release notes for SDK 3.7.0-M2 by @patriknw in #2070
- docs: Concepts instead of Understanding (move down in nav) by @ennru in #2088
- docs: more identity-headers on model requests by @patriknw in #2075
- chore: use awaitility from the testkit in samples by @patriknw in #2091
- fix: align JUnit versions in user projects through the parent POM by @patriknw in #2090
- feat: Vertex AI thinking level for Gemini 3 models by @johanandren in #1990
- fix: keep waiting in TaskClient.result() when a rule rejects a result by @JustinPihony in #2012
- feat: MCP endpoint structured tool output by @johanandren in #1542
- bump: junit-jupiter 6.1.3 (was 5.14.4) by @lightbend-tools-secure in #2085
- docs: add a production readiness page for agentic AI workloads by @JustinPihony in #2045
- fix: align generated JSON schema properties with Jackson by @johanandren in #2071
- feat: evaluator settings on the evaluation context by @aludwiko in #2087
- docs: document akka organizations auth test on the OIDC setup page by @efgpinto in #2033
- feat: opt in components from libraries through config by @johanandren in #1893
- chore: License change date for 3.7.0 by @patriknw in #2094
- docs: Document workload identity for data management and split setup by cloud provider by @jroper in #2036
Full Changelog: v3.6.6...v3.7.0