ToolCallGuardrail

All Superinterfaces:: Guardrail

public non-sealed interface ToolCallGuardrail extends Guardrail

A guardrail that decides whether a tool call may be dispatched.

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.ToolCallGuardrail.CallContext) via ToolCallGuardrail.CallContext. Guardrails are enabled via configuration; see the agent documentation.

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

ToolCallGuardrail.CallContext

Per-call context passed to a ToolCallGuardrail during decide(akka.javasdk.agent.ToolCallGuardrail.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(ToolCallGuardrail.CallContext ctx)

Decides whether the tool call described by ctx may be dispatched.

default CompletionStage<Decision>

decideAsync(ToolCallGuardrail.CallContext ctx)

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

Method Details
- decide
  
  Decision decide(ToolCallGuardrail.CallContext ctx)
  
  Decides whether the tool call described by ctx may be dispatched.
  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(ToolCallGuardrail.CallContext ctx)
  
  Async variant of decide(akka.javasdk.agent.ToolCallGuardrail.CallContext), for implementations that prefer composing futures.
  The default implementation delegates to decide(akka.javasdk.agent.ToolCallGuardrail.CallContext). When this method is overridden, decide(akka.javasdk.agent.ToolCallGuardrail.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