Skip to content

v3.7.0

Choose a tag to compare

@patriknw patriknw released this 16 Oct 12:00
· 127 commits to main since this release
2390557

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-ratio to evaluate a share of the interactions, and trigger-on-failure to 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-level setting 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.
  • WebSocketRouteTester can send request headers and test a rejected upgrade.

Changes that affect existing code

See the SDK 3.7.0 section of the migration guide.

  • TextGuardrail and SimilarityGuard are deprecated. All use-for values are deprecated.
  • A service loads the components of a library jar only when akka.javasdk.library.components lists them. Build a component library with the non-akka-service property set to true.
  • RemoteMcpTools.ToolInterceptor gets the tool name of the MCP server. A null from interceptResponse fails the tool call.
  • The service fails to start when the configuration defines the regex-sanitizers or predefined-sanitizers key of akka.javasdk.sanitization. Configure each sanitizer as a named entry of akka.javasdk.sanitization.sanitizers.
  • Sanitizer is deprecated. Use SanitizerClient.
  • The identity headers are on by default. Set akka.javasdk.agent.identity-headers = off to turn them off.
  • Anthropic and Bedrock report cached prompt tokens outside inputTokens. Use totalInputTokens for 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 onFailure handler that matches on the exception type.
  • JwtClaims.getString returns the JSON text of a claim that is not a string, instead of empty. This includes audience() when aud is an array. The typed getters, such as expirationTime(), return numeric and boolean claims.
  • APIs that were deprecated in SDK 3.5.x are removed. The it Maven profile is removed. Run integration tests with mvn verify.
  • The service fails to start when the configuration sets akka.javasdk.event-sourced-entity.cleanup-deleted-after. Use akka.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

Full Changelog: v3.6.6...v3.7.0