/microsoft-foundry

Attach a Guardrail

After creating a guardrail (via portal or REST API), attach it to one of three targets:

• Hosted Agent — agent.yaml policies block
• Model Deployment — REST API or request-time header
• Toolbox — policies.rai_config.rai_policy_name in toolbox definition

Hosted Agent

A guardrail assigned to an agent fully overrides the underlying model deployment's guardrail. If no guardrail is assigned, the agent inherits the model deployment's guardrail.

Add a policies block to agent.yaml with the guardrail's full ARM resource ID:

policies:
  - type: rai_policy
    rai_policy_name: /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/raiPolicies/<policy-name>

See the 16-content-safety-guardrail sample for a complete working example.

rai_policy_name must be the full ARM resource ID, not just the policy name. This differs from the toolbox and model deployment paths which use just the name.

Model Deployment

Assign via REST API

SUBSCRIPTION_ID=$(az account show --query id -o tsv)
RESOURCE_GROUP="<your-resource-group>"
ACCOUNT_NAME="<your-ai-services-account>"
DEPLOYMENT_NAME="<your-model-deployment>"

az rest --method PATCH \
  --url "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.CognitiveServices/accounts/${ACCOUNT_NAME}/deployments/${DEPLOYMENT_NAME}?api-version=2024-10-01" \
  --body '{"properties": {"raiPolicyName": "my-custom-guardrail"}}'

raiPolicyName is the guardrail name (not the full ARM resource ID). It must match a guardrail that exists on the AI Services account.

Request-Time Override

Override the deployment-level guardrail per request using the x-policy-id header:

ENDPOINT="https://<your-resource-name>.openai.azure.com"
DEPLOYMENT_NAME="<your-model-deployment>"
API_KEY="<your-api-key>"

curl --request POST \
  --url "${ENDPOINT}/openai/deployments/${DEPLOYMENT_NAME}/chat/completions?api-version=2024-10-21" \
  --header "Content-Type: application/json" \
  --header "api-key: ${API_KEY}" \
  --header "x-policy-id: my-custom-guardrail" \
  --data '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'

Request-time override is not available for image input scenarios.

Toolbox

Add policies.rai_config.rai_policy_name to the toolbox definition file, then create the toolbox with azd ai toolbox create.

description: My toolbox
connections:
  - name: my-mcp-server
tools:
  - type: web_search
    name: web
policies:
  rai_config:
    rai_policy_name: my-custom-guardrail

rai_policy_name must match a guardrail that exists on the AI Services account. Use Microsoft.Default, Microsoft.DefaultV2, or a custom name created via portal or API.

azd ai toolbox create my-toolbox --from-file ./toolbox.yaml

There is no command to change the guardrail on an existing toolbox version. To update, delete and recreate the toolbox.

References

• Guardrails overview — create guardrails, default policies, intervention points
• API create — create guardrails via REST API
• Guardrails overview (Microsoft Learn)
• How to configure guardrails (Microsoft Learn)