Package akka.javasdk.agent

Interface ModelCallGuardrail

All Superinterfaces:

Guardrail

All Known Implementing Classes:

ModelCallSimilarityGuard

public non-sealed interface ModelCallGuardrail
extends Guardrail

A guardrail that decides whether a model call may proceed. The runtime evaluates it before every model invocation, with the conversation entering the call.

An implementation has a public constructor, optionally taking a GuardrailContext parameter, which gives access to the guardrail's configured name and config section. The per-call data is delivered to decide(akka.javasdk.agent.ModelCallGuardrail.CallContext) via ModelCallGuardrail.CallContext.

The runtime shares one instance across concurrent calls from different sessions and agents. An implementation must be thread safe.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	ModelCallGuardrail.CallContext	Per-call context passed to a ModelCallGuardrail during decide(akka.javasdk.agent.ModelCallGuardrail.CallContext).

Nested classes/interfaces inherited from interface akka.javasdk.agent.Guardrail

Guardrail.GuardrailException, Guardrail.Message, Guardrail.Result

Method Summary

Modifier and Type	Method	Description
Decision	decide(ModelCallGuardrail.CallContext ctx)	Decides whether the model call described by ctx may proceed.
default CompletionStage<Decision>	decideAsync(ModelCallGuardrail.CallContext ctx)	Async variant of decide(akka.javasdk.agent.ModelCallGuardrail.CallContext), for implementations that prefer composing futures.

Method Details

decide

Decision decide(ModelCallGuardrail.CallContext ctx)

Decides whether the model call described by ctx may proceed.

Use Decision.Deny to refuse the call. Returning Decision.Fail and throwing are equivalent: both mean the guardrail reached no verdict, which is distinct from refusing the call.

This is the method to implement. It may block: guardrails are always evaluated on virtual threads.

Returns:

the decision

decideAsync

default CompletionStage<Decision> decideAsync(ModelCallGuardrail.CallContext ctx)

Async variant of decide(akka.javasdk.agent.ModelCallGuardrail.CallContext), for implementations that prefer composing futures.

The default implementation delegates to decide(akka.javasdk.agent.ModelCallGuardrail.CallContext). When this method is overridden, decide(akka.javasdk.agent.ModelCallGuardrail.CallContext) is no longer used, and it is then safe to have it throw UnsupportedOperationException or return null.

Completing with Decision.Fail, failing the returned stage, and throwing are equivalent: all three mean the guardrail reached no verdict, which is distinct from refusing the call.

Returns:

a CompletionStage with the decision