<!-- <nav> -->
- [Akka](../index.html)
- [Reference](index.html)
- [Migration guide](migration-guide.html)

<!-- </nav> -->

# Migration guide

## <a href="about:blank#_sdk_3_7_2"></a> SDK 3.7.2

### <a href="about:blank#migrating-from-the-evalkit-evaluators"></a> Migrating from the EvalKit evaluators

The evaluation runner of the TestKit no longer has its own evaluators and judges. The checks of an experiment are [evaluator components](../sdk/evaluators.html), bound to the agent in the test configuration, and the runner reads their verdicts from the ledger. See [Getting started with evaluation](../testing/evaluation/getting-started.html).

| SDK 3.7.1 | SDK 3.7.2 |
| --- | --- |
| `Evaluators.replyShouldNotContain`, `shouldCallTool`, `shouldNotCallTools`, `replyShouldNotContainPaymentCard` and the other built-in evaluators | An `Evaluator` component in `src/test/java` that reads the interaction from the ledger, bound to the agent with `TestKit.Settings.withAdditionalConfig` |
| Evaluators given to `EvalCase.of(id, command, evaluators…​)` | `EvalCase.of(id, command)`. The bound evaluators judge every case. |
| `EvalCase<C>` with the command type, for example `List<EvalCase<String>>` | `EvalCase<C, V>` with the command type and the reply type of the command handler. A case without an expected reply is an `EvalCase<C, Object>`, for example `List<EvalCase<String, Object>>`, and runs against a handler with any reply type. `EvalCase.of(id, command, expected)` declares a case with an expected reply. See [Cases with an expected reply](../testing/evaluation/getting-started.html#expected-reply). |
| `Experiment` returned by `agent(…​)` | `Experiment<V>` with the reply type of the command handler. `grade(Grader<V>)` compares the reply of an attempt with the expected reply of its case. |
| An evaluator with the component id `expected` | Refused by the experiment. The id names the comparison result of the runner, next to `target`. Rename the evaluator. |
| `Gate.passRateShouldBeAtLeast(rate)` and `Gate.passRateShouldBeAtLeast(evaluatorClass, rate)` with a rate outside 0.0 to 1.0 | `IllegalArgumentException`. The rate is a share of the attempts. |
| `Judge.modelBased(testKit)`, `JudgeAgent`, `ModelBasedJudge` | A judge agent and a judge evaluator written by the project, with the criterion and the threshold as [configuration properties of the evaluator](../sdk/evaluators/examples.html#judging) |
| `replyShouldMatch(pattern)` and `replyShouldNotMatch(pattern)` for a refusal | A judge criterion, gated on a pass rate |
| A custom evaluator that checks a stub for a side effect | A <a href="../sdk/agents/guardrails.html">`ToolCallGuardrail`</a> that denies the tool call, and `Gate.guardrailShouldDeny(name)` in the experiment |
| `Gate.passRateShouldBeAtLeast(Evaluators.ReplyLacks.class, rate)` with a built-in evaluator class | `Gate.passRateShouldBeAtLeast(MyEvaluator.class, rate)` with the class of the evaluator component |
| `EvalCaseParser`, `ToolBindings` and the replay of recorded interactions | Removed. `EvalCases.readJsonLines(path, commandType)` reads cases from a JSON Lines file. |
| `EvaluationResult` and the `ToxicityEvaluator`, `SummarizationEvaluator` and `HallucinationEvaluator` agents | Deprecated. A [judge evaluator](../sdk/evaluators/examples.html#judging) bound to the agent, with the check as its criterion, see [below](about:blank#migrating-from-the-built-in-evaluator-agents) |
An evaluator can end with `effects().notApplicable(reason)` when the interaction gave it nothing to evaluate, see [Outcomes of an evaluation](../sdk/evaluators.html#outcomes). The telemetry attribute `akka.evaluation.outcome` has the new value `not_applicable`.

### <a href="about:blank#migrating-from-the-built-in-evaluator-agents"></a> Migrating from the built-in evaluator agents

`ToxicityEvaluator`, `SummarizationEvaluator` and `HallucinationEvaluator` are agents that a component of the service calls with the text to check, and they reply with an `EvaluationResult`. Replace the call with a [judge evaluator](../sdk/evaluators/examples.html#judging) bound to the agent whose replies it checks. The runtime triggers the judge evaluator after each interaction of that agent, without a call from the service, and records the verdict in the ledger. The check becomes the criterion of the binding:

```conf
akka.javasdk.evaluation.evaluators.judge {
  criterion = "The reply contains no toxic, offensive or harmful language."
  threshold = 0.9
  agents.activity-agent { trigger = interaction }
}
```
For a summarization check, the criterion states that the reply keeps the facts of the source text. For a hallucination check, the criterion states that the reply claims nothing that the request and the tool results do not support. The [multi-agent tutorial](../getting-started/planner-agent/eval.html) shows a judge evaluator with a fixed criterion and a typed verdict.

## <a href="about:blank#_sdk_3_7_0"></a> SDK 3.7.0

### <a href="about:blank#migrating-from-text-guardrail"></a> Migrating from TextGuardrail

`TextGuardrail` is deprecated. Implement one of the guardrail interfaces that return a `Decision` instead. Choose the interface by the `use-for` value of the configuration entry:

- For `model-request`, implement `ModelCallGuardrail`.
- For `model-response`, implement `AgentResponseGuardrail`.
- For `mcp-tool-request`, implement `ToolCallGuardrail`.
- For `mcp-tool-response`, implement `ModelCallGuardrail`. It sees the MCP tool result as a `ToolCallResponse` in `newMessages()` before the model does. A `ToolCallResponse` does not say where the tool runs, so the guardrail sees function tool results and MCP tool results alike. If the `RemoteMcpTools` has a `ToolInterceptor`, the guardrail sees the result that `interceptResponse` returns.
A `ModelCallGuardrail` that replaces an `mcp-tool-response` entry behaves differently:

- It sees the MCP tool result after the tool-result sanitizers have masked it.
- It runs before the next model call, after all tool calls of the round. The `TextGuardrail` ran right after each MCP tool call.
- When it blocks, the interaction record in the ledger already holds the MCP tool result.
- In an autonomous agent, some rounds end the iteration without another model call. This happens when the model response also calls a control tool. It also happens when a tool call of the round fails. The runtime stores such a round in session memory and the ledger before a `ModelCallGuardrail` checks it. If the task continues, the `ModelCallGuardrail` checks it before the first model call of the next iteration.
- The failure message starts with `Before model call guardrail blocked`, not with `MCP response guardrail blocked`.
A `ToolCallGuardrail` that replaces an `mcp-tool-request` entry behaves differently:

- The runtime records the `ToolCallGuardrail` decision in the ledger.
- On the same MCP tool call, the runtime evaluates `ToolCallGuardrail` entries before `TextGuardrail` entries with `mcp-tool-request`. The `TextGuardrail` entries run only when no blocking `ToolCallGuardrail` stopped the call.
The runtime records no guardrail decision for a `TextGuardrail`. The experiment runner therefore reports a turn that a `TextGuardrail` stopped as a failed `target` result, not as a `guardrail` result. When the agent maps the failure to a reply in `onFailure`, the attempt is inconclusive. `Gate.guardrailShouldStop(name)` and `Gate.guardrailShouldDeny(name)` do not see a `TextGuardrail`.

Remove `use-for` from the migrated entry. The service fails to start when a `ModelCallGuardrail`, `AgentResponseGuardrail`, or `ToolCallGuardrail` entry defines `use-for`.

All `use-for` values are deprecated. At startup, the SDK logs a warning for each enabled `TextGuardrail` entry that sets `use-for`.

For the built-in `SimilarityGuard`, see [Migrating from SimilarityGuard](about:blank#migrating-from-similarity-guard).

For an agent that returns `StreamEffect`, the runtime does not evaluate a `TextGuardrail` on the reply unless the entry sets `report-only = true`. The runtime logs warning `AK-01208` instead. An `AgentResponseGuardrail` works differently. The service fails to start when an `AgentResponseGuardrail` entry without `report-only = true` binds such an agent. See [Kinds of guardrail](../sdk/agents/guardrails.html#_kinds_of_guardrail) for the ways to fix the startup failure.

### <a href="about:blank#migrating-from-similarity-guard"></a> Migrating from SimilarityGuard

`SimilarityGuard` is deprecated for every `use-for` value. For `model-request` and `mcp-tool-response`, use `ModelCallSimilarityGuard`. It checks the user message and the tool results before each model call. The SDK has no built-in replacement for `model-response` or `mcp-tool-request`. For `mcp-tool-request`, implement a `ToolCallGuardrail`. See [Similarity guardrail](../sdk/agents/guardrails.html#_similarity_guardrail) for the `ModelCallSimilarityGuard` configuration.

To move the built-in guard entry, enable `"default model-call jailbreak"` for the same agents and agent roles. Copy any settings that you changed on `"default jailbreak"`, such as `threshold` or `report-only`. Then remove the agents and agent roles from `"default jailbreak"`.

`ModelCallSimilarityGuard` behaves differently from `SimilarityGuard` with `use-for = ["model-request"]`:

- It checks the user message after the model-call sanitizers have masked it.
- The service fails at startup if `bad-examples-resource-dir` is not on the classpath. It also fails if `threshold` is not greater than 0 and at most 1.
`ModelCallSimilarityGuard` behaves differently from `SimilarityGuard` with `use-for = ["mcp-tool-response"]`:

- It checks the user message and the function tool results as well as the MCP tool results.
- It checks the MCP tool result before the next model call.
- If the `RemoteMcpTools` has a `ToolInterceptor`, `ModelCallSimilarityGuard` checks the result that `interceptResponse` returns.

### <a href="about:blank#tool-call-guardrail-on-mcp-tools"></a> ToolCallGuardrail on MCP tool calls

A `ToolCallGuardrail` entry runs on MCP tool calls as well as function tool calls. An entry without the `tools` key runs on every MCP tool call of its agents. To run the entry on some tools only, list their names in `tools`. The `tools` key matches by name only. To tell a function tool from an MCP tool, check `origin()` on the `CallContext`. See [Guardrails](../sdk/agents/guardrails.html) for the entry configuration.

### <a href="about:blank#tool-interceptor-changes"></a> ToolInterceptor changes

A `RemoteMcpTools.ToolInterceptor` behaves differently in these cases:

- `ToolInterceptorContext.toolName()` returns the name of the tool on the MCP server. When the model uses another name for the tool, the interceptor no longer gets that name.
- The ledger records the arguments that `interceptRequest` returns as the arguments of the tool call. Before, it recorded the arguments from the model. The `ToolCall` in the interaction record still holds the arguments from the model.
- A `null` from `interceptResponse` fails the tool call with an MCP tool call error. The agent can handle the error in `onFailure`.

### <a href="about:blank#library-components-opt-in"></a> Components from libraries are loaded only when listed

A service no longer loads the components of a library jar automatically. List the library components that the service uses in `akka.javasdk.library.components`, as described in [Using components from libraries](../sdk/setup-and-dependency-injection.html#_using_components_from_libraries). On startup, the service logs a warning that lists the library components it found and the configuration that loads them.

You do not need to rebuild a library built with an earlier SDK version. The service treats its component descriptor as a library descriptor, so you list its components like the components of any other library.

Build a component library with the `non-akka-service` property set to `true`. A library built with SDK 3.7.0 without this property marks its component descriptor as a service descriptor, and a service that depends on it fails to start.

On the first build after the upgrade, the Akka parent pom removes the build output from the earlier SDK version. For a build without the Akka parent pom, run a clean build once after the upgrade.

## <a href="about:blank#_sdk_3_5_5"></a> SDK 3.5.5

Akka SDK 3.5.5 deprecates the `@AgentDescription` annotation in favor of using `@Component` for agent metadata (name and description) and the new `@AgentRole` annotation for specifying agent roles. This change aligns agent configuration with other component types and provides a more consistent API.

### <a href="about:blank#_migrating_from_agentdescription_to_component_and_agentrole"></a> Migrating from @AgentDescription to @Component and @AgentRole

The `@AgentDescription` annotation is now deprecated. To migrate your agent classes:

**For agent name and description**:

- Remove the `@AgentDescription` annotation
- If using `@AgentDescription.role` field, add an `@AgentRole` annotation instead.
- Add or update the `@Component` annotation with `name` and `description` fields:
Before:
```java
@Component(id = "my-agent")
@AgentDescription(
    name = "My Agent",
    description = "An agent that does something useful",
    role = "worker")
public class MyAgent extends Agent {
    // ...
}
```
After:
```java
@Component(
    id = "my-agent",
    name = "My Agent",
    description = "An agent that does something useful")
@AgentRole("worker")
public class MyAgent extends Agent {
    // ...
}
```
**Update imports**:

- Add `import akka.javasdk.annotations.AgentRole;` if you are using agent roles
- Keep `import akka.javasdk.annotations.Component;`
**Backward compatibility**:

- The framework will continue to support `@AgentDescription` for backward compatibility
- However, you cannot use both the old and new annotations for the same fields (e.g., both `@AgentDescription.name` and `@Component.name` will cause a validation error)
- New features and improvements will only be available with the new annotation style

## <a href="about:blank#_sdk_3_5_4"></a> SDK 3.5.4

Akka SDK 3.5.4 introduces a new `@Component` annotation, replacing the legacy `@ComponentId` for identifying components. This change streamlines component configuration and enables new features and improvements. The migration is straightforward and ensures backward compatibility for existing codebases.

## <a href="about:blank#_migrating_from_componentid_to_component"></a> Migrating from @ComponentId to @Component

The `@ComponentId` annotation is now deprecated in favor of the new `@Component` annotation. To migrate your codebase:

**Replace usages of `@ComponentId`**:

- Remove the `@ComponentId("your-id")` annotation from your component classes.
- Add the `@Component` annotation, specifying the required `id` and optionally `name` and `description` fields:

```java
@Component(id = "your-id",
           name = "Your Name",
           description = "Description")
public class YourComponent { ... }
```
**Update imports**:

- Change `import akka.javasdk.annotations.ComponentId;` to `import akka.javasdk.annotations.Component;`
**Test backward compatibility**:

- The framework will continue to support `@ComponentId` for backward compatibility, but new features and improvements will only be available with `@Component`.

## <a href="about:blank#_sdk_3_3_0"></a> SDK 3.3.0

This release introduces support for Java 21 virtual threads across all user component and endpoint logic. As a result, it is now safe to perform blocking I/O operations without occupying underlying OS threads.

You no longer need to use `CompletionStage` or `CompletableFuture` composition when making calls using component clients, HTTP clients, or gRPC clients. Where services previously used `.invokeAsync()` and handled a future, you can now simply use `.invoke()` and work directly with the returned result.

### <a href="about:blank#_breaking_changes"></a> Breaking Changes

To simplify usage and improve developer experience, this release includes a few breaking changes. If your service
relies on any of the following features, you will need to update your implementation:

- gRPC endpoints for unary and client streaming methods now return the response message directly, instead of wrapping it in a `CompletionStage`.
- gRPC clients now return the response value directly for unary and client streaming calls. For asynchronous behavior, the request builder APIs (`grpcClient.someMethod().invokeAsync(parameter)`) are still available.

### <a href="about:blank#_deprecations"></a> Deprecations

Timer scheduling and cancellation via `TimerScheduler.startSingleTimer(…​)` and `TimerScheduler.cancel()` are now
deprecated. Instead, use `TimerScheduler.createSingleTimer(…​)` and `TimerScheduler.delete()`. Note that these two
new methods are blocking operations that return `void`.

If you still prefer non-blocking operations, new asynchronous alternatives have been introduced: `createSingleTimerAsync()` and `deleteAsync()`.

### <a href="about:blank#_blocking_and_parallelism"></a> Blocking and Parallelism

To support parallel execution of blocking logic within completion stages, the Service Setup, Endpoints, Consumers, Timed Actions, and Workflows can now accept a `java.util.concurrent.Executor` via their constructors.

The Akka SDK provides a virtual-thread-enabled executor that is safe for running blocking operations. When using the standard Java `CompletableFuture` or `CompletionStage` APIs, you can supply this executor as an additional parameter to methods accepting lambdas, enabling safe parallelism for blocking tasks.

<!-- <footer> -->
<!-- <nav> -->
[JSON Web Tokens (JWTs)](jwts.html) [Release notes](release-notes.html)
<!-- </nav> -->

<!-- </footer> -->

<!-- <aside> -->

<!-- </aside> -->