SanitizeUserPrompt policy

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

The SanitizeUserPrompt policy protects AI applications from harmful content by sanitizing user prompts sent to generative AI models. The policy usesModel Armor to evaluate user prompts for harmful content, enabling native protection for AI workloads using Apigee.Model Armor is a Google Cloud service offering AI security and safety measures to mitigate the risks associated with large language models (LLMs).

This policy works in conjunction with theSanitizeModelResponse policy.

This policy is anExtensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, seePolicy types.

Before you begin

Before you use the SanitizeUserPrompt policy, complete the following tasks:

Create a Model Armor template. Complete this step before you create a SanitizeUserPrompt policy.
Set the API endpoint for the Model Armor service.
Create a SanitizeModelResponse policy. Complete this task before you deploy the SanitizeUserPrompt policy.

Required roles

To get the permissions that you need to apply and use the SanitizeUserPrompt policy, ask your administrator to grant you the following IAM roles on the service account you use to deploy Apigee proxies:

Model Armor User (roles/modelarmor.user)
Model Armor Viewer (roles/modelarmor.viewer)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Enable APIs

Enable the Model Armor API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

`<SanitizeUserPrompt>` element

Defines a SanitizeUserPrompt policy.

Default Value	SeeDefault Policy tab, below
Required?	Required
Type	Complex object
Parent Element	N/A
Child Elements	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<TemplateName>` `<UserPromptSource>`

The<SanitizeUserPrompt> element uses the following syntax:

Syntax

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>  <DisplayName>Sanitize-Text-sample</DisplayName>  <ModelArmor>    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>  </ModelArmor>  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource></SanitizeUserPrompt>

Default Policy

The following example shows the default settings when you add a SanitizeUserPrompt policy to your request flow in the Apigee UI:

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>  <DisplayName>Sanitize-Text-sample</DisplayName>  <ModelArmor>    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>  </ModelArmor>  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource></SanitizeUserPrompt>

When you insert a new SanitizeUserPrompt policy using the Apigee UI, the template contains stubs for all possible operations. See below for information on required elements.

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
`name`	N/A	Required	The internal name of the policy. The value of the`name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the`<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.
`continueOnError`	false	Optional	Set to`false` to return an error when a policy fails. This is expected behavior for most policies. Set to`true` to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
`enabled`	true	Optional	Set to`true` to enforce the policy. Set to`false` toturn off the policy. The policy will not be enforced even if it remains attached to a flow.
`async`	false	Deprecated	This attribute is deprecated.

The following table provides a high level description of the child elements of<SanitizeUserPrompt>:

Child Element	Required?	Description
`<DisplayName>`	Optional	The name of the policy.
`<IgnoreUnresolvedVariables>`	Optional	Specifies whether processing stops if the variable used for the template name or Model Armor payload is unresolved.
`<ModelArmor>`	Required	Contains the required information for specifying the Model Armor template.
`<UserPromptSource>`	Optional	The location of the payload for the user prompt text to be extracted. Only string text values are supported. This field supports Apigee message template syntax, including the use of variables orJSON Path functions. For example: {jsonpath('$.input.prompt.text',request.content,false)}

Example

This section provides an example using the<SanitizeUserPrompt>.

This example uses all default values for model detection and prompt extraction:

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>  <DisplayName>Sanitize-Text-sample</DisplayName>  <ModelArmor>    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>  </ModelArmor></SanitizeUserPrompt>

Child element reference

This section describes the child elements of<SanitizeUserPrompt>.

`<DisplayName>`

Use in addition to thename attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The<DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit`<DisplayName>`, the value of the policy's`name` attribute is used.
Type	String
Parent Element	<`PolicyElement`>
Child Elements	None

The<DisplayName> element uses the following syntax:

Syntax

<PolicyElement><DisplayName>POLICY_DISPLAY_NAME</DisplayName>  ...</PolicyElement>

Example

<PolicyElement><DisplayName>My Validation Policy</DisplayName></PolicyElement>

The<DisplayName> element has no attributes or child elements.

<IgnoreUnresolvedVariables>

Determines whether processing stops when a variable is unresolved. Set totrue to ignore unresolved variables and continue processing.

Default Value	False
Required?	Optional
Type	Boolean
Parent Element	`<SanitizeUserPrompt>`
Child Elements	None

`<ModelArmor>`

Contains the required information for specifying the Model Armor template.

Default Value	N/A
Required?	Required
Type	String
Parent Element
Child Elements	`<TemplateName>`

The<ModelArmor> element uses the following syntax:

Syntax

<ModelArmor>  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName></ModelArmor>

Example

This example uses Apigee flow variables to populate the required information.

<ModelArmor><TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName></ModelArmor>

The following table provides a high-level description of the child elements of<ModelArmor>.

Child Element Required? Description

Child Element	Required?	Description
`<TemplateName>`	Required	String The Model Armor template used to sanitize the user prompt. This value can be templated using the following Apigee flow variables: projects/{organization.name}/locations/{system.region.name}/templates/{id}

<TemplateName>

Required

String

The Model Armor template used to sanitize the user prompt.

This value can be templated using the following Apigee flow variables:

projects/{organization.name}/locations/{system.region.name}/templates/{id}

`<UserPromptSource>`

The location of the payload for the user prompt text to be extracted. This field supports Apigee message template syntax, including the use of variables orJSON Path functions. For example:

{jsonpath('$.input.prompt.text',request.content,false)}

Default Value	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
Required?	Optional
Type	String
Parent Element	`<SanitizeUserPrompt>`
Child Elements	None

Flow variables

Flow variables configure dynamic runtime behavior for policies and flows, basedon HTTP headers or message content, or the context available in the Flow. For more informationabout flow variables, seeFlow variables reference.

This policy provides the following set ofread-only flow variables during execution. You can use these flow variables with theDataCapture policy to create custom analytics reports. For more information, seeCollecting customer data with the Data Capture policy.

Variable name	Description
`SanitizeUserPrompt.POLICY_NAME.templateUsed`	Specifies which model armor template is used. For example:`projects/myproject/locations/us-west1/templates/mytemplate`
`SanitizeUserPrompt.POLICY_NAME.userPrompt`	Specifies the prompt content used for the call to Model Armor to sanitize the content.
`SanitizeUserPrompt.POLICY_NAME.modelResponse`	Specifies the LLM response content used for the call to Model Armor to sanitize the content.
`SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor`	Specifies the json response from Model Armor.
`SanitizeUserPrompt.POLICY_NAME.filterMatchState`	Specifies whether the filter matched. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.invocationResult`	A field indicating the outcome of the invocation, irrespective of match status. It can have the following: SUCCESS: All filters executed successfully. PARTIAL: Some filters were skipped or failed execution. FAILURE: All filters were skipped or failed execution.
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState`	Rai filter execution result. Valid values include`EXECUTION_SUCCESS` and`EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState`	Rai filter match state. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState`	Sdp filter inspect result execution state. Valid values include`EXECUTION_SUCCESS` and`EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState`	Sdp filter inspect result match state. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState`	Sdp filter de identify result execution state. Valid values include`EXECUTION_SUCCESS` and`EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState`	Sdp filter de identify result match state. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState`	Prompt injection and Jailbreak filter results execution state. Valid values include`EXECUTION_SUCCESS` and`EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState`	Prompt injection and Jailbreak filter results match state. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState`	CSAM filter execution state. Valid values include`EXECUTION_SUCCESS` and`EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState`	CSAM filter match state. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState`	Malicious URI filter execution state. Valid values include`EXECUTION_SUCCESS` and`EXECUTION_SKIPPED`.
`SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState`	Malicious URI filter match state. Valid values include`MATCH_FOUND` and`NO_MATCH_FOUND`.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode`	Custom overridden Error code if present in Model Armor response.
`SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage`	Custom overridden Error code if present in Model Armor response.
`SanitizeUserPrompt.POLICY_NAME.csamFilterMatched`	Boolean value indicating whether the CSAM filter matched.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIs`	Appended list of malicious URIs detected by the malicious URI filter.
`SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected`	Boolean value indicating whether the malicious URI filter matched.
`SanitizeUserPrompt.POLICY_NAME.matchesFound`	Boolean value indicating whether any of the filters matched.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected`	Boolean value indicating whether the prompt injection filter matched.
`SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence`	Confidence level of prompt injection detection.
`SanitizeUserPrompt.POLICY_NAME.raiMatchesFound`	Boolean value indicating whether the RAI filter matched.
`SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor`	Boolean value indicating whether a request was sent to Model Armor.
`SanitizeUserPrompt.POLICY_NAME.sanitizeOperation`	Specifies the operation performed by the policy. Valid values include`SANITIZE_USER_PROMPT` and`SANITIZE_MODEL_RESPONSE`.

Error reference

This section describes the fault codes and error messages that Apigee returns and the fault variables that Apigee sets for the SanitizeUserPrompt policy. This information is important to know if you are developing fault rules tohandle faults. To learn more, seeWhat you need to knowabout policy errors andHandlingfaults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.sanitize.user.prompt.response.FilterMatched`	`400`	This error occurs if the user prompt does not pass the Model Armor template check.
`steps.sanitize.user.prompt.SanitizationResponseParsingFailed`	`500`	This error occurs if the Model Armor response cannot be parsed.
`steps.sanitize.user.prompt.FailedToExtractUserPrompt`	`500`	This error occurs if the automatic user prompt extraction for the default value failed.
`steps.sanitize.user.prompt.InternalError`	`500`	This error occurs if there is an internal server error.
`steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed`	`500`	This error occurs if the template name cannot be resolved.
`steps.sanitize.modelarmor.AuthenticationFailure`	`500`	This error occurs if the service account does not have permission to call the Model Armor API.
`steps.sanitize.modelarmor.ModelArmorAPIFailed`	`500`	This error occurs if the Model Armor API throws an error.
`steps.sanitize.modelarmor.ModelArmorCalloutError`	`500`	This error occurs if the Model Armor API call fails.
`steps.sanitize.modelarmor.ServiceUnavailable`	`500`	This error occurs if the Model Armor service is unavailable.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
`The ModelArmor/TemplateName element is required.`	Occurs if the <TemplateName> element in <ModelArmor> is not present.
`The TemplateName element value is required.`	Occurs if the <TemplateName> value is empty.

Fault variables

This policy sets these variables when it triggers an error at runtime. For more information, seeWhat you need to know about policy errors.

Variables	Where	Example
`fault.name="FAULT_NAME"`	`FAULT_NAME` is the name of the fault, as listed in theRuntime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`SanitizeUserPrompt.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`SanitizeUserPrompt.sanitize-prompt.failed = true`

Example error response

Note: For error handling, the best practice is to trap theerrorcode part of the error response. Do not rely on the text in thefaultstring, because it could change.

{"fault":{"faultstring":"SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]","detail":{"errorcode":"steps.sanitizeuserprompt.UnresolvedVariable"}}}

Example fault rule

<FaultRule name="SanitizeUserPrompt Faults">    <Step>        <Name>SUP-CustomSetVariableErrorResponse</Name>        <Condition>(fault.name = "SetVariableFailed")</Condition>    </Step>    <Condition>(sanitizeuserprompt.failed = true)</Condition></FaultRule>

Model Armor template error code and error messages

The Model Armor template supports overriding error codes and error messages thrown by the SanitizeUserPrompt policy's API requests. If the user sets the overrides, then the Model Armor error codes and error messages populate the flow variables.

For example, a response with Model Armor error codes and messages could look like the following:

{"sanitizationResult":{"filterMatchState":"MATCH_FOUND","filterResults":{...},"sanitizationMetadata":{"errorCode":"890","errorMessage":"get out"},"invocationResult":"SUCCESS"}}

Schemas

Each policy type is defined by an XML schema (.xsd). For reference,policy schemas are available on GitHub.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.

Movatterモバイル変換

SanitizeUserPrompt policy Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles

Enable APIs

<SanitizeUserPrompt> element

Syntax

Default Policy

Example

Child element reference

<DisplayName>

Syntax

Example

<IgnoreUnresolvedVariables>

<ModelArmor>

Syntax

Example

<UserPromptSource>

Flow variables

Error reference

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Model Armor template error code and error messages

Schemas

SanitizeUserPrompt policy

`<SanitizeUserPrompt>` element

`<DisplayName>`

`<ModelArmor>`

`<UserPromptSource>`