AI Azure Content Safety Policy

The AI Azure Content Safety Policy allows administrators to enforce introspection with the Azure AI Content Safety service for all requests and responses handled by the AI Model entity. This Policy enables configurable thresholds for the different moderation categories and you can specify an array set of pre-configured blocklist IDs from your Azure Content Safety instance.

You can observe and report on audit failures using the AI logging Policies.

The AI Azure Content Safety Policy can be applied to:

• Input data (requests)
• Output data (responses)
• Both input and output data

Here’s how it works if you apply it to both requests and responses:

1. The AI Azure Content Safety Policy intercepts the request and sends the request body to the Azure AI Content Safety service.
   • The Azure AI Content Safety service analyzes the request against configured moderation categories and allows or blocks the request.
2. If allowed, the request is forwarded upstream with the AI Model entity.
3. On the way back, the Policy intercepts the response and sends the response body to the Azure AI Content Safety service.
   • The Azure AI Content Safety service analyzes the response against configured moderation categories and allows or blocks the response.
4. If allowed, the response is forwarded to the client.

The AI Azure Content Safety Policy responds to a blocked request or response according to its rejection mode.

Use config.rejection_mode to control how AI Gateway responds to a blocked request:

Use none or stealth for clients outside your organization, so responses don’t reveal how your guardrails are configured. Use verbose in development or for trusted internal clients, to see why a request was blocked.

Verbose response

In verbose mode, the response always has the status code 403 and the error code GUARDRAIL_BLOCKED. Clients can check the error.code field to tell a guardrail rejection apart from other errors:

• type: Always guardrail_rejected.
• plugin: The type of the Policy that blocked the request.
• reason: Why the request was blocked.
• code: Always GUARDRAIL_BLOCKED.
• detail: Additional context about the match. This field is only present when the Policy has details to report.

For example, a request that breaches a category threshold returns the following response in verbose mode. The detail.categories field lists each breached category with its detected severity and the configured threshold:

{
  "error": {
    "type": "guardrail_rejected",
    "plugin": "ai-azure-content-safety",
    "reason": "breached category [Violence] at level 2",
    "code": "GUARDRAIL_BLOCKED",
    "detail": {
      "categories": [
        {
          "category": "Violence",
          "severity": 4,
          "threshold": 2
        }
      ],
      "blocklists": {}
    }
  }
}

To return this response, set config.rejection_mode to verbose:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "AI Azure Content Safety - Verbose Rejection",
      "name": "ai-azure-content-safety",
      "type": "ai-azure-content-safety",
      "config": {
        "content_safety_url": "https://my-acs-instance.cognitiveservices.azure.com/contentsafety/text:analyze",
        "content_safety_key": "'$AZURE_CONTENT_SAFETY_KEY'",
        "categories": [
          {
            "name": "Violence",
            "rejection_level": 2
          }
        ],
        "rejection_mode": "verbose"
      }
    }
    '

ai_gateway_policies:
  - ref: ai-azure-content-safety
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: AI Azure Content Safety - Verbose Rejection
    name: ai-azure-content-safety
    type: ai-azure-content-safety
    config:
      content_safety_url: https://my-acs-instance.cognitiveservices.azure.com/contentsafety/text:analyze
      content_safety_key: !env AZURE_CONTENT_SAFETY_KEY
      categories:
      - name: Violence
        rejection_level: 2
      rejection_mode: verbose

To run the AI Azure Content Safety Policy without blocking, set config.continue_on_detection to true. When a request matches, the Policy lets the request continue to the LLM. The caller receives the LLM’s normal response, so config.rejection_mode has no effect while this setting is enabled.

Detections are still recorded in the AI Gateway logs. The ai.proxy.guardrail_triggered object is populated with the Policy that matched and the direction of the match. To include the matched content, also set config.log_blocked_content to true. For the full list of fields, see the AI Gateway audit log reference.

This is useful when you roll out new rules: run them in detection-only mode, review the logs for false positives, then set continue_on_detection back to false to enforce them.

config.ssl_verify is enabled by default. The AI Azure Content Safety Policy verifies the TLS certificate when connecting to the Azure Content Safety service. To disable this, set ssl_verify: false.

The AI Azure Content Safety Policy emits structured log data for every inspected request and response. For the full list of log fields, see the AI Gateway audit log reference.

To log the raw content of blocked requests and responses, enable config.log_blocked_content. When enabled, the blocked prompt or response body appears under ai.proxy.azure-content-safety.input_faulty_prompt and ai.proxy.azure-content-safety.output_faulty_response in the log entry.

This Policy works with all of the AI Model entity’s model.capabilities settings, and is able to compose an Azure Content Safety text check by compiling all chat history, or just the 'user' content.

Set config.proxy on this entity to route its outbound requests through an HTTP forward proxy. Use this in network-isolated deployments where AI Gateway cannot open direct connections to LLM providers or auxiliary services.

The proxy record is identical for AI Model, AI MCP Server, and supported AI Policy entities. Existing capabilities such as load balancing, health checking, streaming, WebSocket, and HTTP/2 continue to work when the proxy is active.

For the full field reference, traffic flow, and limitations, see Forward proxy support.