Class GuardrailValidatingAiModelInvoker

java.lang.Object

com.flowable.agent.engine.impl.guardrail.GuardrailValidatingAiModelInvoker

All Implemented Interfaces:

AiModelInvoker

public class GuardrailValidatingAiModelInvoker
extends Object
implements AiModelInvoker

Decorator around an AiModelInvoker that enforces guardrails before and after the LLM invocation.

Before the LLM call (input validation):

1. Parameter constraints on input parameters (cheapest, in-process)
2. Operation guardrails in configured order (guardrail agents and external guardrails)

After the LLM call (output validation):

1. Parameter constraints on output parameters (uses the already-parsed AgentInvocationResult)
2. Operation guardrails in configured order (guardrail agents and external guardrails)

This wrapper is only applied to agent models that have guardrails configured. Each guardrail supports failure modes: fail (throw exception), warn (log and continue), skip (skip LLM call, set variable), reject (discard LLM output, set variable), and default (resolve from operation's guardrailDefaults). Validation is fail-fast: if any step fails with fail, skip, or reject, subsequent steps are skipped.

Field Summary

Fields

Modifier and Type	Field	Description
protected AgentEngineConfiguration	agentEngineConfiguration
protected final org.flowable.common.engine.impl.runtime.Clock	clock
protected final AiModelInvoker	delegate
protected ExternalGuardrailInvokerResolver	externalGuardrailInvokerResolver
protected GuardrailAgentEvaluator	guardrailAgentEvaluator
protected final tools.jackson.databind.ObjectMapper	objectMapper
protected static final String	SOURCE_TYPE_EXPRESSION
protected static final String	SOURCE_TYPE_PARAMETER
protected static final String	SOURCE_TYPE_SERVICE

Constructor Summary

Constructors

Constructor	Description
GuardrailValidatingAiModelInvoker(AiModelInvoker delegate, tools.jackson.databind.ObjectMapper objectMapper, org.flowable.common.engine.impl.runtime.Clock clock)

Method Summary

Modifier and Type	Method	Description
protected void	addGuardrailBlockedExchange(AgentInvocationResultResponse.Invocation invocation, GuardrailResult guardrailResult)
protected String	buildConstraintResultJson(boolean passed, String phase, String parameterName, String constraintType, String reason, String action)
protected static String	buildGuardrailAssertionKey(String serviceKey, String operationKey, String applyTo)	Composite identifier <serviceKey>/<operationKey>/<applyTo> written into the guardrail-snapshot JSON's guardrailKey field so test assertions can target service-guardrail outcomes via guardrail.<composite>.<field>.
protected String	buildGuardrailResultJson(boolean passed, String phase, String subType, String sourceKey, String guardrailKey, String reason, String action)
protected String	buildGuardrailResultJson(boolean passed, String phase, String subType, String sourceKey, String guardrailKey, String reason, String action, String sanitizedContent)
protected String	buildGuardrailResultJson(boolean passed, String phase, String subType, String sourceKey, String guardrailKey, String reason, String action, String sanitizedContent, Double confidence)
protected AgentInvocationResult	buildSkipRejectInvocationResult(AgentDefinitionModel.AgentOperation operation, GuardrailResult guardrailResult)	Builds a synthetic AgentInvocationResult containing the skip/reject flag + reason variables when a guardrail blocks the LLM call.
protected AgentInvocationResultResponse	createBlockedResponse(List<AgentInvocationResultResponse.Exchange> guardrailExchanges, GuardrailResult guardrailResult, AgentDefinitionModel.AgentOperation operation)	Creates a blocked response when an input guardrail prevents the LLM call.
protected AgentInvocationResultResponse	createBlockedResponseFromExisting(AgentInvocationResultResponse existingResponse, List<AgentInvocationResultResponse.Exchange> outputGuardrailExchanges, GuardrailResult guardrailResult, AgentDefinitionModel.AgentOperation operation)	Creates a blocked response when an output guardrail rejects the LLM response.
protected AgentInvocationResultResponse.Exchange	createGuardrailExchange(String subType, String inputContent, String outputContent, Instant startTime, Instant endTime)	Creates an AgentInvocationResultResponse.Exchange of type guardrail with the given subType, containing an input part (the content evaluated) and an output part (the result JSON).
protected String	determineConstraintFailureMode(AgentDefinitionModel.AgentOperation operation, List<? extends AgentDefinitionModel.AgentParameter> parameters, GuardrailValidationResult result, boolean isInput)
protected Map<String,Object>	extractOutputParameters(AgentDefinitionModel.AgentOperation operation, AgentInvocationResult invocationResult)
protected static AgentDefinitionModel.AgentOperation	findOperation(AgentDefinitionModel model, String operationKey)
protected String	formatViolations(List<GuardrailViolation> violations)
protected ServiceRegistryRuntimeService	getServiceRegistryRuntimeService()
protected GuardrailResult	handleConstraintFailure(AgentDefinitionModel.AgentOperation operation, List<? extends AgentDefinitionModel.AgentParameter> parameters, GuardrailValidationResult result, boolean isInput, List<AgentInvocationResultResponse.Exchange> guardrailExchanges, String content, Instant startTime, Instant endTime)
protected GuardrailResult	handleGuardrailFailure(AgentDefinitionModel.GuardrailReference ref, AgentDefinitionModel.AgentOperation operation, String reason, String phase, String sourceLabel, String sourceId, String guardrailKey, String sourceType, List<AgentInvocationResultResponse.Exchange> guardrailExchanges, String guardrailType, String content, Instant startTime, Instant endTime, String sanitizedContent, Double confidence)
AgentInvocationResultResponse	invoke(AgentInvocationContext agentInvocationContext)
protected boolean	isOverrideDefined(String serviceKey, Map<?,?> entryMap, String operationKey, String applyTo)
protected void	prependExchanges(AgentInvocationResultResponse.Invocation invocation, List<AgentInvocationResultResponse.Exchange> exchangesToPrepend)
protected String	resolveConstraintErrorCode(AgentDefinitionModel.AgentOperation operation, List<? extends AgentDefinitionModel.AgentParameter> parameters, GuardrailValidationResult result)
protected String	resolveFailureMode(String onFailure, AgentDefinitionModel.GuardrailDefaults defaults, boolean isInput)
protected Map<String,Object>	resolveMockOverride(AgentInvocationContext context, String serviceKey, AgentDefinitionModel.GuardrailReference ref)
void	setAgentEngineConfiguration(AgentEngineConfiguration agentEngineConfiguration)
void	setExternalGuardrailInvokerResolver(ExternalGuardrailInvokerResolver externalGuardrailInvokerResolver)
void	setGuardrailAgentEvaluator(GuardrailAgentEvaluator guardrailAgentEvaluator)
protected boolean	shouldApplyGuardrail(String applyTo, String phase)
protected GuardrailResult	validateDelegateExpressionGuardrail(AgentDefinitionModel.GuardrailReference guardrailReference, AgentDefinitionModel.AgentOperation operation, AgentInvocationContext context, String phase, String outputContent, Map<String,Object> parsedOutputParameters, List<AgentInvocationResultResponse.Exchange> guardrailExchanges)
protected GuardrailResult	validateGuardrailAgent(AgentDefinitionModel.GuardrailReference ref, AgentDefinitionModel.AgentOperation operation, AgentInvocationContext context, String phase, String outputContent, List<AgentInvocationResultResponse.Exchange> guardrailExchanges)
protected GuardrailResult	validateOperationGuardrails(AgentDefinitionModel.AgentOperation operation, AgentInvocationContext context, String phase, String outputContent, Map<String,Object> parsedOutputParameters, List<AgentInvocationResultResponse.Exchange> guardrailExchanges)	Validates guardrails set on the operation in their configured order.
protected GuardrailResult	validateOutputParameterConstraints(AgentDefinitionModel.AgentOperation operation, Map<String,Object> parsedOutputParameters, AgentInvocationContext context, String outputContent, List<AgentInvocationResultResponse.Exchange> guardrailExchanges)
protected GuardrailResult	validateWithServiceRegistry(AgentDefinitionModel.GuardrailReference ref, AgentDefinitionModel.AgentOperation operation, AgentInvocationContext context, String phase, String outputContent, List<AgentInvocationResultResponse.Exchange> guardrailExchanges)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

SOURCE_TYPE_PARAMETER

protected static final String SOURCE_TYPE_PARAMETER

See Also:

• Constant Field Values

SOURCE_TYPE_EXPRESSION

protected static final String SOURCE_TYPE_EXPRESSION

See Also:

• Constant Field Values

SOURCE_TYPE_SERVICE

protected static final String SOURCE_TYPE_SERVICE

See Also:

• Constant Field Values

delegate

protected final AiModelInvoker delegate

objectMapper

protected final tools.jackson.databind.ObjectMapper objectMapper

clock

protected final org.flowable.common.engine.impl.runtime.Clock clock

guardrailAgentEvaluator

protected GuardrailAgentEvaluator guardrailAgentEvaluator

externalGuardrailInvokerResolver

protected ExternalGuardrailInvokerResolver externalGuardrailInvokerResolver

agentEngineConfiguration

protected AgentEngineConfiguration agentEngineConfiguration

Constructor Details

GuardrailValidatingAiModelInvoker

public GuardrailValidatingAiModelInvoker(AiModelInvoker delegate,
 tools.jackson.databind.ObjectMapper objectMapper,
 org.flowable.common.engine.impl.runtime.Clock clock)

Method Details

invoke

public AgentInvocationResultResponse invoke(AgentInvocationContext agentInvocationContext)

Specified by:

invoke in interface AiModelInvoker

createBlockedResponse

protected AgentInvocationResultResponse createBlockedResponse(List<AgentInvocationResultResponse.Exchange> guardrailExchanges,
 GuardrailResult guardrailResult,
 AgentDefinitionModel.AgentOperation operation)

Creates a blocked response when an input guardrail prevents the LLM call. The response contains the guardrail exchanges plus an assistant exchange indicating the input was skipped or the output was rejected.

createBlockedResponseFromExisting

protected AgentInvocationResultResponse createBlockedResponseFromExisting(AgentInvocationResultResponse existingResponse,
 List<AgentInvocationResultResponse.Exchange> outputGuardrailExchanges,
 GuardrailResult guardrailResult,
 AgentDefinitionModel.AgentOperation operation)

Creates a blocked response when an output guardrail rejects the LLM response. Preserves the existing exchanges from the delegate response and appends the output guardrail exchanges plus an assistant exchange indicating the output was rejected.

buildSkipRejectInvocationResult

protected AgentInvocationResult buildSkipRejectInvocationResult(AgentDefinitionModel.AgentOperation operation,
 GuardrailResult guardrailResult)

Builds a synthetic AgentInvocationResult containing the skip/reject flag + reason variables when a guardrail blocks the LLM call. The variable names are resolved from operation.guardrailDefaults (the per-row skip* / reject* fields are surfaced only via the frontend model today; the backend AgentDefinitionModel.GuardrailReference has no equivalent getters yet so the defaults are authoritative). Returns null when no names are configured.

addGuardrailBlockedExchange

protected void addGuardrailBlockedExchange(AgentInvocationResultResponse.Invocation invocation,
 GuardrailResult guardrailResult)

prependExchanges

protected void prependExchanges(AgentInvocationResultResponse.Invocation invocation,
 List<AgentInvocationResultResponse.Exchange> exchangesToPrepend)

extractOutputParameters

protected Map<String,Object> extractOutputParameters(AgentDefinitionModel.AgentOperation operation,
 AgentInvocationResult invocationResult)

validateOutputParameterConstraints

protected GuardrailResult validateOutputParameterConstraints(AgentDefinitionModel.AgentOperation operation,
 Map<String,Object> parsedOutputParameters,
 AgentInvocationContext context,
 String outputContent,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges)

handleConstraintFailure

protected GuardrailResult handleConstraintFailure(AgentDefinitionModel.AgentOperation operation,
 List<? extends AgentDefinitionModel.AgentParameter> parameters,
 GuardrailValidationResult result,
 boolean isInput,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges,
 String content,
 Instant startTime,
 Instant endTime)

resolveConstraintErrorCode

protected String resolveConstraintErrorCode(AgentDefinitionModel.AgentOperation operation,
 List<? extends AgentDefinitionModel.AgentParameter> parameters,
 GuardrailValidationResult result)

determineConstraintFailureMode

protected String determineConstraintFailureMode(AgentDefinitionModel.AgentOperation operation,
 List<? extends AgentDefinitionModel.AgentParameter> parameters,
 GuardrailValidationResult result,
 boolean isInput)

validateOperationGuardrails

protected GuardrailResult validateOperationGuardrails(AgentDefinitionModel.AgentOperation operation,
 AgentInvocationContext context,
 String phase,
 String outputContent,
 Map<String,Object> parsedOutputParameters,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges)

Validates guardrails set on the operation in their configured order. Returns a non-passed GuardrailResult if a skip/reject occurred, null otherwise.

validateDelegateExpressionGuardrail

protected GuardrailResult validateDelegateExpressionGuardrail(AgentDefinitionModel.GuardrailReference guardrailReference,
 AgentDefinitionModel.AgentOperation operation,
 AgentInvocationContext context,
 String phase,
 String outputContent,
 Map<String,Object> parsedOutputParameters,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges)

validateWithServiceRegistry

protected GuardrailResult validateWithServiceRegistry(AgentDefinitionModel.GuardrailReference ref,
 AgentDefinitionModel.AgentOperation operation,
 AgentInvocationContext context,
 String phase,
 String outputContent,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges)

validateGuardrailAgent

protected GuardrailResult validateGuardrailAgent(AgentDefinitionModel.GuardrailReference ref,
 AgentDefinitionModel.AgentOperation operation,
 AgentInvocationContext context,
 String phase,
 String outputContent,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges)

handleGuardrailFailure

protected GuardrailResult handleGuardrailFailure(AgentDefinitionModel.GuardrailReference ref,
 AgentDefinitionModel.AgentOperation operation,
 String reason,
 String phase,
 String sourceLabel,
 String sourceId,
 String guardrailKey,
 String sourceType,
 List<AgentInvocationResultResponse.Exchange> guardrailExchanges,
 String guardrailType,
 String content,
 Instant startTime,
 Instant endTime,
 String sanitizedContent,
 Double confidence)

resolveFailureMode

protected String resolveFailureMode(String onFailure,
 AgentDefinitionModel.GuardrailDefaults defaults,
 boolean isInput)

shouldApplyGuardrail

protected boolean shouldApplyGuardrail(String applyTo,
 String phase)

findOperation

protected static AgentDefinitionModel.AgentOperation findOperation(AgentDefinitionModel model,
 String operationKey)

formatViolations

protected String formatViolations(List<GuardrailViolation> violations)

buildConstraintResultJson

protected String buildConstraintResultJson(boolean passed,
 String phase,
 String parameterName,
 String constraintType,
 String reason,
 String action)

buildGuardrailResultJson

protected String buildGuardrailResultJson(boolean passed,
 String phase,
 String subType,
 String sourceKey,
 String guardrailKey,
 String reason,
 String action)

buildGuardrailResultJson

protected String buildGuardrailResultJson(boolean passed,
 String phase,
 String subType,
 String sourceKey,
 String guardrailKey,
 String reason,
 String action,
 String sanitizedContent)

buildGuardrailResultJson

protected String buildGuardrailResultJson(boolean passed,
 String phase,
 String subType,
 String sourceKey,
 String guardrailKey,
 String reason,
 String action,
 String sanitizedContent,
 Double confidence)

createGuardrailExchange

protected AgentInvocationResultResponse.Exchange createGuardrailExchange(String subType,
 String inputContent,
 String outputContent,
 Instant startTime,
 Instant endTime)

Creates an AgentInvocationResultResponse.Exchange of type guardrail with the given subType, containing an input part (the content evaluated) and an output part (the result JSON).

setGuardrailAgentEvaluator

public void setGuardrailAgentEvaluator(GuardrailAgentEvaluator guardrailAgentEvaluator)

setExternalGuardrailInvokerResolver

public void setExternalGuardrailInvokerResolver(ExternalGuardrailInvokerResolver externalGuardrailInvokerResolver)

setAgentEngineConfiguration

public void setAgentEngineConfiguration(AgentEngineConfiguration agentEngineConfiguration)

getServiceRegistryRuntimeService

protected ServiceRegistryRuntimeService getServiceRegistryRuntimeService()

buildGuardrailAssertionKey

protected static String buildGuardrailAssertionKey(String serviceKey,
 String operationKey,
 String applyTo)

Composite identifier <serviceKey>/<operationKey>/<applyTo> written into the guardrail-snapshot JSON's guardrailKey field so test assertions can target service-guardrail outcomes via guardrail.<composite>.<field>. Two service-type guardrail entries on the same agent targeting the same service+operation but different phases (input vs output) get distinct composites. Returns null when serviceKey is missing.

Used only for the assertion DSL — mock-override matching uses the entry tuple carried in the __flowableMockOverrides input parameter instead.

resolveMockOverride

protected Map<String,Object> resolveMockOverride(AgentInvocationContext context,
 String serviceKey,
 AgentDefinitionModel.GuardrailReference ref)

isOverrideDefined

protected boolean isOverrideDefined(String serviceKey,
 Map<?,?> entryMap,
 String operationKey,
 String applyTo)