Your gateway now serves a customer-facing assistant and several internal agents, on models from more than one provider. Your responsible AI review asks for one consistent rule: every prompt and every response is screened for harmful content, whichever model or tool handles it. In this lab you add a content safety policy at the gateway, tune it per category, and see what a blocked call looks like to a client.
Before you begin
One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.
- Choose where to run commandsEvery track except the portal
- Sign in to AzureOn your own machine. Cloud Shell is already signed in.
- Install the
aigatewayextensionThe Azure CLI tracks and the Verify steps - Clone the labs repoThe Bicep + azd and Terraform tracks, the notebooks, and the code samples
You've done the one-time setup that this lab uses.
On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway, model, and
key, so you can skip this section. You need only the one-time setup above.
- Complete Publish a Foundry model and make your first call. You need a gateway, an imported model, a callable alias, and a runtime API key from AccessAPI keys.
- Permission to change the gateway, for example Contributor on the resource group.
- Run the scripts and samples from the lab's folder,
~/aigateway/labs/08-content-safety.
Set these variables once. Every track and the Verify section reuse them.
# Name your gateway, its model provider, and the backend model that gets the policy
export RG="<resource-group>"
export GATEWAY="<gateway>" # 24 characters or fewer
export PROVIDER="<provider-name>" # for example foundry-models
export MODEL="<model-name>" # the backend model name under that provider
# Read the gateway's runtime URL, which apps call
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Read the alias that apps send in the model field: for Foundry imports, it matches the deployment's model name
export AI_GATEWAY_MODEL="$(az aigateway model show -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" \
-n "$MODEL" --query properties.deployment.modelName -o tsv)"
echo "🔖 Model alias: $AI_GATEWAY_MODEL"
# Paste the runtime key you created in Access › API keys, without showing it: don't commit it or write it to a file
printf "AI Gateway API key: " && read -rs AI_GATEWAY_API_KEY && export AI_GATEWAY_API_KEY && echo
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Name your gateway, its model provider, and the backend model that gets the policy
$RG = "<resource-group>"
$GATEWAY = "<gateway>" # 24 characters or fewer
$PROVIDER = "<provider-name>" # for example foundry-models
$MODEL = "<model-name>" # the backend model name under that provider
# Read the gateway's runtime URL, which apps call
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Read the alias that apps send in the model field: for Foundry imports, it matches the deployment's model name
$env:AI_GATEWAY_MODEL = az aigateway model show -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER `
-n $MODEL --query properties.deployment.modelName -o tsv
Write-Host "🔖 Model alias: $env:AI_GATEWAY_MODEL"
# Paste the runtime key you created in Access › API keys, without showing it: don't commit it or write it to a file
$env:AI_GATEWAY_API_KEY = Read-Host "AI Gateway API key" -MaskInput
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"How it works
A content safety policy screens prompts, tool inputs, and responses with Azure AI Content Safety. It rates
content in four categories: Hate, Self-harm, Sexual, and Violence. You set a severity threshold
for each category independently. When content reaches the threshold, the gateway blocks the call and returns
400. A blocked prompt never reaches the backend.
The threshold is the lowest severity that gets blocked, so a lower threshold blocks more:
| Portal label | CLI and REST value | What it blocks |
|---|---|---|
| Strict | Low | The most content: low, medium, and high severity |
| Balanced (default) | Medium | Medium and high severity |
| Lenient | High | Only the most concerning, high-severity content |
| Off | None | Nothing in this category |
You can attach content safety to models, aliases, and MCP servers, or set it gateway-wide so that it covers every compatible asset, including ones added later. On an MCP server, it screens the tool inputs that agents send and the results that tools return. Every applicable policy is evaluated, and any one of them can block the call.
Foundry deployments have their own Content filter, shown on the model's details page in Models. That filter runs inside Foundry, for that one deployment. The gateway policy runs before the backend, applies the same rules to models from any provider and to MCP tool traffic, and is managed by the platform team in one place. Keep both: a request has to pass each of them.
Add content safety to the model
Pick one track. Each track produces the same policy: Balanced (Medium) for Hate, Self-harm, and Sexual,
and Strict (Low) for Violence. The portal, CLI, and REST tracks put it on your model. The Bicep + azd and
Terraform tracks create a new gateway and put it on a new alias of the model. The stricter Violence threshold makes the test in
Verify more likely to show a block, using only a mild, non-graphic prompt.
Create the policy
The Add policy wizard doesn't list Content safety for AI Gateway resources, so create the policy with
the Azure CLI, for example in Azure Cloud Shell, with the variables from
Before you begin. Then set the thresholds in the portal. The commands read the model's policies, add
Balanced (Medium) content safety on all four categories, and write the array back, so every other policy on
the model stays:
# Read the model's policies, drop any content safety policy, and add one at Medium (Balanced) in all four categories
POLICIES="$(az aigateway model policy list -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" -o json |
jq -c '[.[] | select(.type != "contentSafety")]
+ [{"type":"contentSafety","hateSeverity":"Medium","violenceSeverity":"Medium","sexualSeverity":"Medium","selfHarmSeverity":"Medium"}]')"
# Write the merged array back: --policies replaces the whole array
az aigateway model update -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--policies "$POLICIES" --output none &&
echo "🔐 Content safety on $MODEL is Balanced (Medium) for all four categories"# Read the model's policies, drop any content safety policy, and add one at Medium (Balanced) in all four categories
$current = az aigateway model policy list -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
-o json | ConvertFrom-Json
$policies = @($current | Where-Object { $_ -and $_.type -ne 'contentSafety' })
$policies += [pscustomobject]@{
type = 'contentSafety'; hateSeverity = 'Medium'; violenceSeverity = 'Medium'; sexualSeverity = 'Medium'; selfHarmSeverity = 'Medium'
}
# Write the merged array back from a file, which keeps the JSON quotes intact: --policies replaces the whole array
ConvertTo-Json -InputObject $policies -Depth 10 -Compress | Set-Content -Path policies.json
az aigateway model update -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
--policies '@policies.json' --output none
if ($?) { Write-Host "🔐 Content safety on $MODEL is Balanced (Medium) for all four categories" }
Remove-Item policies.jsonSet the thresholds
Open the AI Gateway portal and select your gateway from the gateway switcher. Select Policies. The list shows a Content safety policy with your model under Scope and Balanced filtering under Configuration. Select Balanced filtering to open the policy, then select Edit.
In the Edit policy panel, choose how strictly each category is filtered:
| Field | Value |
|---|---|
| Hate | Balanced |
| Violence | Strict |
| Self-harm | Balanced |
| Sexual | Balanced |
Select Save. The portal confirms Policy updated.
Under Configuration, the policy shows Hate Filtering: Balanced, Violence Filtering: Strict, Sexual Filtering: Balanced, and Self Harm Filtering: Balanced, with your model under Applies to. In Policies, its configuration now reads Strict filtering, the strictest level among the categories.
Set the policy
Policies live in the model's properties.policies array. The aigateway extension 1.0.0b34 removed its content
safety commands until they match API version 2026-11-01, so set the policy with az aigateway model update --policies. It replaces the whole array, so read the array first, swap in the new content safety policy, and
write the result back. That keeps every other policy on the model.
# Read the model's policies, drop any content safety policy, and add one: Medium, with Low for Violence
POLICIES="$(az aigateway model policy list -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" -o json |
jq -c '[.[] | select(.type != "contentSafety")]
+ [{"type":"contentSafety","hateSeverity":"Medium","violenceSeverity":"Low","sexualSeverity":"Medium","selfHarmSeverity":"Medium"}]')"
# Write the merged array back: --policies replaces the whole array
az aigateway model update -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--policies "$POLICIES" --output none &&
echo "🔐 Content safety on $MODEL is Balanced (Medium), with Strict (Low) for Violence"# Read the model's policies, drop any content safety policy, and add one: Medium, with Low for Violence
$current = az aigateway model policy list -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
-o json | ConvertFrom-Json
$policies = @($current | Where-Object { $_ -and $_.type -ne 'contentSafety' })
$policies += [pscustomobject]@{
type = 'contentSafety'; hateSeverity = 'Medium'; violenceSeverity = 'Low'; sexualSeverity = 'Medium'; selfHarmSeverity = 'Medium'
}
# Write the merged array back from a file, which keeps the JSON quotes intact: --policies replaces the whole array
ConvertTo-Json -InputObject $policies -Depth 10 -Compress | Set-Content -Path policies.json
az aigateway model update -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
--policies '@policies.json' --output none
if ($?) { Write-Host "🔐 Content safety on $MODEL is Balanced (Medium), with Strict (Low) for Violence" }
Remove-Item policies.jsonThe command prints 🔐 Content safety on <model-name> is Balanced (Medium), with Strict (Low) for Violence. Each
threshold accepts None, Low, Medium, or High. To change another category, change its value in the
contentSafety object: hateSeverity, selfHarmSeverity, or sexualSeverity.
Confirm the policy
# List the model's policies, to check the content safety thresholds
echo "🔐 Policies on $MODEL:"
az aigateway model policy list -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" -o json# List the model's policies, to check the content safety thresholds
Write-Host "🔐 Policies on ${MODEL}:"
az aigateway model policy list -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL -o jsonThe output lists your other policies unchanged, plus "type": "contentSafety" with "violenceSeverity": "Low",
"Medium" for the other three categories, and "scope": "resource", which the service adds to every model policy.
Read the current policies
Policies live inline in the model's properties.policies array. A PATCH replaces the whole array, so
always read it first and keep the policies you didn't mean to change.
# Read your subscription ID, and build the management URL of your model, which holds its policies
SUB="$(az account show --query id -o tsv)"
URL="https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.ApiManagement/aigateways/$GATEWAY/workspaces/default/modelProviders/$PROVIDER/models/$MODEL?api-version=2026-11-01"
echo "🆔 Subscription: $SUB"
# Read the model's current policies, so that you know what the merge must keep
echo "🔐 Policies on $MODEL:"
az rest --method get --url "$URL" --query properties.policiesReplace the content safety policy and keep everything else
# Read the policies, drop any content safety policy, and add the new one: Medium, with Low for Violence
POLICIES="$(az rest --method get --url "$URL" | jq -c '
[(.properties.policies // [])[] | select(.type != "contentSafety")]
+ [{"type":"contentSafety","hateSeverity":"Medium","violenceSeverity":"Low","sexualSeverity":"Medium","selfHarmSeverity":"Medium"}]')"
# Send the merged array back: a PATCH replaces the whole policies array
az rest --method patch --url "$URL" --body "{\"properties\":{\"policies\":$POLICIES}}" --output none &&
echo "🔐 Content safety on $MODEL is Balanced (Medium), with Strict (Low) for Violence"# Read your subscription ID, and build the management URL of your model, which holds its policies
$SUB = az account show --query id -o tsv
$URL = "https://management.azure.com/subscriptions/$SUB/resourceGroups/$RG/providers/Microsoft.ApiManagement/aigateways/$GATEWAY/workspaces/default/modelProviders/$PROVIDER/models/$MODEL`?api-version=2026-11-01"
Write-Host "🆔 Subscription: $SUB"
# Read the policies, drop any content safety policy, and add the new one: Medium, with Low for Violence
$current = az rest --method get --url $URL | ConvertFrom-Json
$policies = @($current.properties.policies | Where-Object { $_ -and $_.type -ne 'contentSafety' })
$policies += [pscustomobject]@{
type = 'contentSafety'; hateSeverity = 'Medium'; violenceSeverity = 'Low'; sexualSeverity = 'Medium'; selfHarmSeverity = 'Medium'
}
# Send the merged array back from a file, which keeps the JSON quotes intact: a PATCH replaces the whole array
$body = @{ properties = @{ policies = $policies } } | ConvertTo-Json -Depth 10 -Compress
$body | Set-Content -Path patch.json
az rest --method patch --url $URL --body '@patch.json' --output none
if ($?) { Write-Host "🔐 Content safety on $MODEL is Balanced (Medium), with Strict (Low) for Violence" }
Remove-Item patch.jsonRunning the GET again returns your other policies unchanged plus one contentSafety entry with
"violenceSeverity": "Low" and "scope": "resource".
What you need: only the one-time setup from Before you begin. This track doesn't use your gateway from lab 02:
azd up creates a new one, so it works on its own.
Choose what to declare
A Bicep deployment sends a PUT, which replaces the whole resource. Redeclaring a model you imported in the
portal risks dropping settings you didn't copy. Instead, this template adds a new alias,
<model-name>-safe, that targets the same backend model and carries the content safety policy. Existing clients
keep calling the original alias. Callers that you move to the new alias get screened.
The policy is one contentSafety object with a threshold for each category: hateSeverity, selfHarmSeverity,
sexualSeverity, and violenceSeverity. Each accepts the API values from How it works: Low,
Medium, High, or None.
Review the templates
infra/main.bicep creates the resource group rg-<environment name> and calls the quick start's
resources.bicep for the gateway, the Foundry model, its default alias, and the
app-first-call key. Then it calls infra/safe-alias.bicep with the four thresholds:
// Lab 08 with azd: "azd up" creates the resource group rg-<environment name>, the quick start's gateway, Foundry
// model, default alias, and runtime API key, then a second alias for the same model with a content safety policy.
// The runtime API key is never an output.
targetScope = 'subscription'
@description('azd environment name. The resource group is rg-<environmentName>.')
@minLength(1)
@maxLength(60)
param environmentName string
@description('Region for every resource. Pick one where AI Gateway and the lab\'s Foundry models are available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
@metadata({ azd: { type: 'location' } })
param location string
@description('Threshold for Hate. azd reads it from CONTENT_SAFETY_HATE.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param hateSeverity string = 'Medium'
@description('Threshold for Self-harm. azd reads it from CONTENT_SAFETY_SELF_HARM.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param selfHarmSeverity string = 'Medium'
@description('Threshold for Sexual. azd reads it from CONTENT_SAFETY_SEXUAL.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param sexualSeverity string = 'Medium'
@description('Threshold for Violence. azd reads it from CONTENT_SAFETY_VIOLENCE.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param violenceSeverity string = 'Low'
var suffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }
resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
name: 'rg-${environmentName}'
location: location
tags: tags
}
// The quick start's template: a gateway, a Foundry model behind the default alias, and the app-first-call key.
module base '../../quickstart/infra/resources.bicep' = {
name: 'aigw-base'
scope: rg
params: {
location: location
tags: tags
gatewayName: 'aigw-${suffix}'
foundryName: 'aigw${suffix}'
}
}
module safeAlias 'safe-alias.bicep' = {
name: 'aigw-safe-alias'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
providerName: base.outputs.providerName
modelName: base.outputs.modelName
hateSeverity: hateSeverity
selfHarmSeverity: selfHarmSeverity
sexualSeverity: sexualSeverity
violenceSeverity: violenceSeverity
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = base.outputs.gatewayName
output AI_GATEWAY_ID string = base.outputs.gatewayId
output AI_GATEWAY_URL string = base.outputs.gatewayUrl
output AI_GATEWAY_PROVIDER string = base.outputs.providerName
output AI_GATEWAY_BACKEND_MODEL string = base.outputs.modelName
output AI_GATEWAY_MODEL string = safeAlias.outputs.aliasName
output FOUNDRY_ACCOUNT_NAME string = base.outputs.foundryNameinfra/safe-alias.bicep adds the alias. It only references the gateway, the provider, and the model, so you can
also deploy it on its own to a gateway you already have, with az deployment group create:
// Publishes an alias with a content safety policy for an existing AI Gateway model. main.bicep calls it after the
// quick start's template, and you can also deploy it on its own to a gateway you already have. The alias points at
// the same backend model as your default alias, but screens every prompt and response it serves, so you can test
// thresholds without changing what other callers get.
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways).')
param gatewayName string
@description('Name of the existing model provider in the gateway, for example foundry-models.')
param providerName string
@description('Name of the existing backend model registration under the provider.')
param modelName string
@description('Callable alias to create. Clients send this value in the request "model" field.')
param aliasName string = '${modelName}-safe'
// The lowest severity that gets blocked: Low (Strict), Medium (Balanced), High (Lenient), or None (Off).
@description('Threshold for the Hate category.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param hateSeverity string = 'Medium'
@description('Threshold for the Self-harm category.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param selfHarmSeverity string = 'Medium'
@description('Threshold for the Sexual category.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param sexualSeverity string = 'Medium'
@description('Threshold for the Violence category.')
@allowed([ 'Low', 'Medium', 'High', 'None' ])
param violenceSeverity string = 'Low'
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource workspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: gateway
name: 'default'
}
#disable-next-line BCP081
resource provider 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders@2026-11-01' existing = {
parent: workspace
name: providerName
}
#disable-next-line BCP081
resource model 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders/models@2026-11-01' existing = {
parent: provider
name: modelName
}
#disable-next-line BCP081
resource safeAlias 'Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01' = {
parent: workspace
name: aliasName
properties: {
aliasName: aliasName
backendModels: [
{ resourceId: model.id }
]
policies: [
{
type: 'contentSafety'
hateSeverity: hateSeverity
selfHarmSeverity: selfHarmSeverity
sexualSeverity: sexualSeverity
violenceSeverity: violenceSeverity
}
]
}
}
output aliasName string = safeAlias.name
output chatCompletionsUrl string = 'https://${gateway.properties.frontend.defaultHostname}/default/models/openai/v1/chat/completions'Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab08 in your current subscription, then provision
everything. It takes about two minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/08-content-safety &&
echo "📂 Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab08 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "📝 azd environment aigw-lab08 deploys to eastus2"
# Provision the gateway, the Foundry model, the key, and the screened alias
azd up &&
echo "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)"# Move into the lab's folder, which holds the azd project
Set-Location ~/aigateway/labs/08-content-safety
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab08 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "📝 azd environment aigw-lab08 deploys to eastus2" }
# Provision the gateway, the Foundry model, the key, and the screened alias
azd up
if ($?) { Write-Host "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)" }For another region, pick one where AI Gateway and the gpt-5-mini model are available, as in Find the available
regions.
Read the outputs and the key
Set the variables that Verify uses from azd's environment values, and read the key from the gateway, so that it never shows on screen.
# Read the template's outputs: the resource group, the gateway, its model provider, and the backend model
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export PROVIDER="$(azd env get-value AI_GATEWAY_PROVIDER)"
export MODEL="$(azd env get-value AI_GATEWAY_BACKEND_MODEL)"
# Read the gateway's runtime URL and the screened alias
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
export AI_GATEWAY_MODEL="$(azd env get-value AI_GATEWAY_MODEL)"
# Read the key from the gateway, so that it never lands in a file or a deployment log
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$(azd env get-value AI_GATEWAY_ID)/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
echo "🔖 Model alias: $AI_GATEWAY_MODEL"# Read the template's outputs: the resource group, the gateway, its model provider, and the backend model
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$PROVIDER = azd env get-value AI_GATEWAY_PROVIDER
$MODEL = azd env get-value AI_GATEWAY_BACKEND_MODEL
# Read the gateway's runtime URL, the screened alias, and the gateway's resource ID
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
$env:AI_GATEWAY_MODEL = azd env get-value AI_GATEWAY_MODEL
$GATEWAY_ID = azd env get-value AI_GATEWAY_ID
# Read the key from the gateway, so that it never lands in a file or a deployment log
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
Write-Host "🔖 Model alias: $env:AI_GATEWAY_MODEL"azd up ended with SUCCESS, and the last command printed 🔖 Model alias: gpt-5-mini-safe.
az aigateway model-alias show -g "$RG" --gateway-name "$GATEWAY" -n "$AI_GATEWAY_MODEL" --query properties.policies
returns one contentSafety entry with "violenceSeverity": "Low", "Medium" for the other three categories,
and "scope": "resource".
Change the thresholds
The parameters come from azd environment values, with the defaults in infra/main.parameters.json:
CONTENT_SAFETY_HATE, CONTENT_SAFETY_SELF_HARM, CONTENT_SAFETY_SEXUAL, and CONTENT_SAFETY_VIOLENCE. Change one
with azd env set and run azd provision: only the alias changes. Verify relaxes Violence this way.
What you need: only the one-time setup from Before you begin, plus Terraform 1.9 or later, as in
Deploy a lab with Terraform. This track doesn't use your gateway from
lab 02: terraform apply creates a new one, so it works on its own.
Review the configuration
Like the Bicep template, the configuration adds a new alias, <model-name>-safe, that targets the same backend
model and carries the content safety policy, rather than redeclaring a model that you imported in the portal.
terraform/main.tf creates the resource group rg-<environment_name> and calls the quick start's
resources module for the gateway, the Foundry model, its default alias, and the
app-first-call key:
# Lab 08 with Terraform: creates the resource group rg-<environment_name>, the quick start's gateway, Foundry model,
# default alias, and runtime API key, then a second alias for the same model with a content safety policy
# (safe-alias.tf). The runtime API key is never an output.
data "azapi_client_config" "current" {}
locals {
suffix = substr(sha1("${data.azapi_client_config.current.subscription_id}/${var.environment_name}/${var.location}"), 0, 6)
tags = { "environment-name" = var.environment_name }
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# The quick start's module: a gateway, a Foundry model behind the default alias, and the app-first-call key.
module "base" {
source = "../../quickstart/terraform/resources"
subscription_id = data.azapi_client_config.current.subscription_id
resource_group_name = azurerm_resource_group.rg.name
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
gateway_name = "aigw-${local.suffix}"
foundry_name = "aigw${local.suffix}"
}terraform/safe-alias.tf adds the alias with the azapi provider, which sends the AI Gateway API version,
2026-11-01, as is. terraform/variables.tf declares the four thresholds with the same defaults as the Bicep
template, and accepts only Low, Medium, High, or None:
# Publishes an alias with a content safety policy for the quick start's model. The alias points at the same backend
# model as the default alias, but screens every prompt and response it serves, so you can test thresholds without
# changing what other callers get.
resource "azapi_resource" "safe_alias" {
type = "Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01"
name = "${module.base.model_name}-safe"
parent_id = module.base.workspace_id
body = {
properties = {
aliasName = "${module.base.model_name}-safe"
backendModels = [
{ resourceId = module.base.model_id }
]
policies = [
{
type = "contentSafety"
hateSeverity = var.hate_severity
selfHarmSeverity = var.self_harm_severity
sexualSeverity = var.sexual_severity
violenceSeverity = var.violence_severity
}
]
}
}
schema_validation_enabled = false
}Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It takes about three minutes.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/08-content-safety/terraform &&
echo "📂 Terraform folder: $(pwd)"
# Deploy to the Azure CLI's current subscription
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)" &&
echo "📍 Subscription: $ARM_SUBSCRIPTION_ID"
# Download the providers, then plan and apply the gateway, the Foundry model, the key, and the screened alias
terraform init &&
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "🚀 Gateway deployed: $(terraform output -raw ai_gateway_url)"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/08-content-safety/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
# Deploy to the Azure CLI's current subscription
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
if ($?) { Write-Host "📍 Subscription: $env:ARM_SUBSCRIPTION_ID" }
# Download the providers, then plan and apply the gateway, the Foundry model, the key, and the screened alias
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "🚀 Gateway deployed: $(terraform output -raw ai_gateway_url)" }The configuration deploys to eastus2. For another region where AI Gateway and the gpt-5-mini model are
available, as in Find the available regions, run
export TF_VAR_location=<region> (PowerShell: $env:TF_VAR_location = "<region>") before terraform plan.
Read the outputs and the key
Set the variables that Verify uses from the Terraform outputs, and read the key from the gateway, so that it never shows on screen or lands in the Terraform state.
# Read the configuration's outputs: the resource group, the gateway, its model provider, and the backend model
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export PROVIDER="$(terraform output -raw ai_gateway_provider)"
export MODEL="$(terraform output -raw ai_gateway_backend_model)"
# Read the gateway's runtime URL and the screened alias
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
export AI_GATEWAY_MODEL="$(terraform output -raw ai_gateway_model)"
# Read the key from the gateway, so that it never lands in a file or the Terraform state
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$(terraform output -raw ai_gateway_id)/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
echo "🔖 Model alias: $AI_GATEWAY_MODEL"
# Move back to the lab's folder, which holds the scripts
cd .. && echo "📂 Lab folder: $(pwd)"# Read the configuration's outputs: the resource group, the gateway, its model provider, and the backend model
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$PROVIDER = terraform output -raw ai_gateway_provider
$MODEL = terraform output -raw ai_gateway_backend_model
# Read the gateway's runtime URL, the screened alias, and the gateway's resource ID
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
$env:AI_GATEWAY_MODEL = terraform output -raw ai_gateway_model
$GATEWAY_ID = terraform output -raw ai_gateway_id
# Read the key from the gateway, so that it never lands in a file or the Terraform state
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
Write-Host "🔖 Model alias: $env:AI_GATEWAY_MODEL"
# Move back to the lab's folder, which holds the scripts
Set-Location ..
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }terraform apply ended with Apply complete! Resources: 10 added, 0 changed, 0 destroyed., and the output
shows 🔖 Model alias: gpt-5-mini-safe.
az aigateway model-alias show -g "$RG" --gateway-name "$GATEWAY" -n "$AI_GATEWAY_MODEL" --query properties.policies
returns one contentSafety entry with "violenceSeverity": "Low", "Medium" for the other three categories,
and "scope": "resource".
Change the thresholds
The next sections run from the lab's folder, with -chdir=terraform for the terraform commands.
The thresholds are Terraform variables, with the defaults in terraform/variables.tf: hate_severity,
self_harm_severity, sexual_severity, and violence_severity. Pass one to terraform plan with -var and apply
the plan: only the alias changes. Verify relaxes Violence this way.
Verify
Test the policy with benign prompts only. You don't need harmful content to see how the gateway behaves, and you should never write it to test a filter.
Run the test prompts
From the lab folder, run the script for your shell. It sends two prompts: a neutral question, and a request for a short, non-graphic scene from a historical novel. It prints the status and the start of the response or the error for each one.
# Send a neutral prompt and a mild fiction prompt through the screened alias
echo "🚦 Expect 200 for the neutral prompt, and 200 or 400 for the fiction prompt:"
./infra/test-content-safety.sh "$AI_GATEWAY_MODEL"# Send a neutral prompt and a mild fiction prompt through the screened alias
Write-Host "🚦 Expect 200 for the neutral prompt, and 200 or 400 for the fiction prompt:"
./infra/test-content-safety.ps1 -Model $env:AI_GATEWAY_MODELOn GitHub, open test-content-safety.sh or test-content-safety.ps1.
Example output:
🚦 Expect 200 for the neutral prompt, and 200 or 400 for the fiction prompt:
Prompt Status Finish reason Response or error
neutral 200 stop Teams put an API gateway in front of AI models to centralize access co
fiction 200 stop The two armies massed on either side of the muddy approach, banners snThe neutral prompt returns 200. The fiction prompt can go either way, and your results will vary: Content
Safety rates both the prompt and the model's response, and a mild battle scene sits close to the Strict
Violence threshold. If it returns 400, the gateway blocked it and the error message says why. If it returns
200, the content was rated below the threshold.
The Foundry deployment's own filter can act too. A 400 that starts with "The response was filtered due to the
prompt triggering Azure OpenAI's content management policy", or a 200 with the finish reason
content_filter, comes from Foundry, not from the gateway. At the time of writing, AI Gateway resources save
the content safety policy but don't block calls with it yet, so only Foundry results show up, even at
Strict. Until the gateway enforces the policy, rely on the deployment's content filter, as described in
Check the Foundry content filter, and see
Troubleshooting.
If the fiction prompt passes, don't make it more graphic to force a block. The point of this test is to understand thresholds with safe input, not to probe the filter. Use Monitoring and real, representative traffic in a test environment to tune thresholds.
Relax one category
Set Violence back to Balanced (Medium) with the track you used, then run the script again. For
example, from the command line, set all four categories to Medium. The other three already are, so only
Violence changes, and the merge keeps every other policy on the model:
# Set all four categories to Medium (Balanced): only Violence changes, and the other policies stay
POLICIES="$(az aigateway model policy list -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" -o json |
jq -c '[.[] | select(.type != "contentSafety")]
+ [{"type":"contentSafety","hateSeverity":"Medium","violenceSeverity":"Medium","sexualSeverity":"Medium","selfHarmSeverity":"Medium"}]')"
# Write the merged array back: --policies replaces the whole array
az aigateway model update -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--policies "$POLICIES" --output none &&
echo "🔐 Content safety on $MODEL is Balanced (Medium) for all four categories"# Set all four categories to Medium (Balanced): only Violence changes, and the other policies stay
$current = az aigateway model policy list -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
-o json | ConvertFrom-Json
$policies = @($current | Where-Object { $_ -and $_.type -ne 'contentSafety' })
$policies += [pscustomobject]@{
type = 'contentSafety'; hateSeverity = 'Medium'; violenceSeverity = 'Medium'; sexualSeverity = 'Medium'; selfHarmSeverity = 'Medium'
}
# Write the merged array back from a file, which keeps the JSON quotes intact: --policies replaces the whole array
ConvertTo-Json -InputObject $policies -Depth 10 -Compress | Set-Content -Path policies.json
az aigateway model update -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
--policies '@policies.json' --output none
if ($?) { Write-Host "🔐 Content safety on $MODEL is Balanced (Medium) for all four categories" }
Remove-Item policies.jsonOn the Bicep + azd track, set the environment value and provision again instead:
# Relax Violence to Medium (Balanced) in the azd environment
azd env set CONTENT_SAFETY_VIOLENCE Medium &&
echo "📝 CONTENT_SAFETY_VIOLENCE is Medium"
# Provision again: only the screened alias changes
azd provision &&
echo "🔐 Content safety on $AI_GATEWAY_MODEL is Balanced (Medium) for all four categories"# Relax Violence to Medium (Balanced) in the azd environment
azd env set CONTENT_SAFETY_VIOLENCE Medium
if ($?) { Write-Host "📝 CONTENT_SAFETY_VIOLENCE is Medium" }
# Provision again: only the screened alias changes
azd provision
if ($?) { Write-Host "🔐 Content safety on $env:AI_GATEWAY_MODEL is Balanced (Medium) for all four categories" }On the Terraform track, in the lab folder, run
terraform -chdir=terraform plan -var violence_severity=Medium -out tfplan, then
terraform -chdir=terraform apply tfplan. The plan ends with Plan: 0 to add, 1 to change, 0 to destroy., for
azapi_resource.safe_alias.
A prompt that Strict blocked is more likely to pass at Balanced. Prompts that passed before still pass.
Check the Foundry content filter
Open ModelsBackend models and select your model. On its Overview tab, Content filter under
Model deployment names the Foundry deployment's own filter, for example Microsoft.DefaultV2. It's separate
from the gateway policy. When Foundry's filter acts instead of the gateway, the error or the finish_reason comes
from the backend, and it can mention content_filter.
Find blocked calls in Monitoring
If you configured Application Insights in Monitor usage, cost, and traces, open
Monitoring and look for 400 outcomes on your model. Review them before and after every threshold change.
The neutral prompt returned 200, you saw how the borderline prompt fared at Strict and at Balanced,
and you can tell a gateway block (400 from the content safety policy) from a Foundry content filter result.
Go further
- Screen tool traffic. Add a Content safety policy to the
learnMCP server from Federate MCP tools behind one endpoint. With REST, use the samecontentSafetyobject on.../workspaces/default/toolServers/learn. - Make it the default. Apply Balanced content safety to every model and MCP server, including future ones, in Set gateway-wide policy baselines.
- Tune per category. Start every category at Balanced, tighten the ones that matter most for your audience, and turn a category Off only with a documented exception.
Clean up
A Strict threshold can block legitimate traffic. Remove the model policy before you continue. The next lab sets a gateway-wide baseline instead.
Remove the policy
Select Policies. On the Content safety policy's row, select More actions (⋮) › Delete, then Delete again in Delete this policy?. The other policies on the model stay.
Remove the policy
# Read the model's policies and drop the content safety policy, so that the others stay
POLICIES="$(az aigateway model policy list -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" -o json |
jq -c '[.[] | select(.type != "contentSafety")]')"
# Write the remaining policies back: --policies replaces the whole array
az aigateway model update -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--policies "$POLICIES" --output none &&
echo "🚮 Content safety is removed from $MODEL"# Read the model's policies and drop the content safety policy, so that the others stay
$current = az aigateway model policy list -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
-o json | ConvertFrom-Json
$policies = @($current | Where-Object { $_ -and $_.type -ne 'contentSafety' })
# Write the remaining policies back from a file: --policies replaces the whole array
ConvertTo-Json -InputObject $policies -Depth 10 -Compress | Set-Content -Path policies.json
az aigateway model update -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
--policies '@policies.json' --output none
if ($?) { Write-Host "🚮 Content safety is removed from $MODEL" }
Remove-Item policies.jsonThis removes only the content safety policy and keeps every other policy on the model.
Remove the policy
# Read the policies and drop the content safety policy, so that the others stay
POLICIES="$(az rest --method get --url "$URL" | jq -c '[(.properties.policies // [])[] | select(.type != "contentSafety")]')"
# Send the remaining policies back: a PATCH replaces the whole policies array
az rest --method patch --url "$URL" --body "{\"properties\":{\"policies\":$POLICIES}}" --output none &&
echo "🚮 Content safety is removed from $MODEL"# Read the policies and drop the content safety policy, so that the others stay
$current = az rest --method get --url $URL | ConvertFrom-Json
$policies = @($current.properties.policies | Where-Object { $_ -and $_.type -ne 'contentSafety' })
# Send the remaining policies back from a file: a PATCH replaces the whole policies array
ConvertTo-Json -InputObject @{ properties = @{ policies = $policies } } -Depth 10 -Compress | Set-Content -Path patch.json
az rest --method patch --url $URL --body '@patch.json' --output none
if ($?) { Write-Host "🚮 Content safety is removed from $MODEL" }
Remove-Item patch.jsonDelete everything azd created
In the aigateway/labs/08-content-safety folder, delete the resource group with the gateway, the Foundry account,
and the screened alias. --purge also purges the soft-deleted Foundry account.
It takes a few minutes.
# Delete the resource group and purge the soft-deleted Foundry account, without prompts
azd down --purge --force &&
echo "🚮 Everything that azd up created is deleted"Delete everything Terraform created
In the aigateway/labs/08-content-safety folder, delete the resource group with the gateway, the Foundry
account, and the screened alias. The azurerm provider also purges the
soft-deleted Foundry account. It takes a few minutes.
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
terraform -chdir=terraform destroy -auto-approve &&
echo "🚮 Everything that terraform apply created is deleted"Keep the gateway, model, and key from lab 02: the next labs reuse them. azd down and terraform destroy don't
touch them, because the Bicep + azd and Terraform tracks created their own gateways.
Next steps
- Set gateway-wide policy baselines: make content safety the default for every model and MCP server.
- Control which tools agents can call: limit which tools agents can reach.
- Monitor usage, cost, and traces: find
400outcomes and the policy that caused them. - Docs: Policies in AI Gateway.