AI Policies

Create an AI Policy when you want to add governance, security, transformation, or observability to AI Gateway traffic. For example:

• Redact sensitive data with AI PII Sanitizer
• Manage request volume with AI Rate Limiting Advanced
• Validate prompts with AI Prompt Guard or other guardrail AI Policies
• Track requests and responses for observability with logging AI Policies

If none of the available AI Policy types fit your use case, you can register a custom AI Policy type. See AI Custom Policies.

To control access and verify identity, assign an AI Auth Strategy instead of an AI Policy.

For the complete set of available policy types and configurations, see the AI Policies hub.

AI Policies are managed through:

• Konnect UI
• AI Gateway API: /v1/ai-gateways/{aiGatewayId}/policies
• kongctl

For configuration examples and step-by-step setup instructions, see Set up a global AI Policy.

AI Gateway processes each request in the following order:

1. The AI Auth Strategy authenticates the caller. AI Policies don’t perform authentication.
2. AI Gateway identifies the AI Consumer and its AI Consumer Groups.
3. AI Gateway selects the AI Model, AI Agent, or AI MCP Server.
4. AI Gateway collects the AI Policies that apply to the request, based on scope, and resolves any scope conflicts.
5. AI Gateway runs the AI Policies in priority order.
6. Before each AI Policy runs, AI Gateway evaluates its condition and skips the AI Policy if the condition doesn’t match.

The following diagram shows where AI Policies fit in the request pipeline:

 
sequenceDiagram
    actor Client
    participant AIGW as AI Gateway
    participant Auth as AI Auth Strategy
    participant Policy as AI Policy
    participant Entity as AI Model, AI Agent,
or AI MCP Server

    Client->>AIGW: Request
    AIGW->>Auth: Authenticate the caller
    Auth-->>AIGW: AI Consumer and AI Consumer Groups
    AIGW->>AIGW: Select the entity
    AIGW->>AIGW: Collect AI Policies by scope
and resolve conflicts
    loop Each AI Policy, in priority order
        AIGW->>AIGW: Evaluate the condition
        alt No condition, or the condition matches
            AIGW->>Policy: Run
            Policy-->>AIGW: Result
        else The condition doesn't match
            AIGW->>AIGW: Skip the AI Policy
        end
    end
    AIGW->>Entity: Proxy the request
    Entity-->>AIGW: Response
    AIGW-->>Client: Response
  

AI Policies scoped to an AI Consumer or AI Consumer Group apply only to authenticated requests, because authentication runs first. An AI Policy runs at most once per request.

An AI Policy applies wherever you attach it. An AI Policy with global: true applies to all AI Gateway traffic on the data plane. An AI Policy without it applies only to the entities that reference it.

The available scopes are:

• Global: Set global: true to apply the AI Policy to all AI Gateway traffic on the data plane. Non-AI traffic on the same data plane isn’t affected.

• Entity-scoped: Reference the AI Policy from the policies array on an AI Model, AI Agent, AI MCP Server, AI Consumer, or AI Consumer Group entity. The AI Policy applies at that entity’s scope.

To apply an identical configuration in multiple places, create an entity-scoped AI Policy and reference it in each entity’s configuration.

Not every AI Policy type supports every scope. For example, an ACL AI Policy doesn’t support AI Consumer or AI Consumer Group scopes. AI Gateway rejects the request with an error when you attach an AI Policy at a scope its type doesn’t support.

Scope precedence

Scope precedence determines which AI Policy runs when AI Policies of the same type apply to a request at more than one scope. Only the most specific AI Policy runs. From most to least specific scope, the order is:

1. AI Consumer
2. AI Consumer Group
3. AI Model, AI Agent, or AI MCP Server
4. Global

For example, if a global AI Rate Limiting Advanced Policy and one scoped to an AI Model both apply to a request, only the Model-scoped AI Policy runs. Requests to other Models still use the global AI Policy.

Precedence for AI Consumer Groups

An AI Consumer can belong to several AI Consumer Groups, and more than one of those groups can have an AI Policy of the same type. In that case, only one of those AI Policies runs. AI Gateway sorts the AI Consumer’s groups by name and uses the AI Policy from the first group in that order that has one. For example, if an AI Consumer is in the groups alpha and beta, and both have an AI Prompt Guard Policy, only the AI Policy on alpha runs. The order in which you add the AI Consumer to the groups doesn’t change the result.

AI Gateway doesn’t guarantee this order, and it can change in a future release.

Attach at most one AI Policy of a given type to the same entity. For details, see the FAQ.

Every AI Policy type has a fixed priority that determines execution order when more than one AI Policy applies to a request. You can’t configure or override an AI Policy’s priority.

When AI Policies of different types apply to the same request, the AI Policy with the higher priority runs first. When AI Policies of the same type apply at different scopes, see Scope precedence.

Custom AI Policies run at the priority set by the plugin’s author, so they don’t appear in the following table.

The following table lists the priority of every built-in AI Policy type, from highest to lowest.

An AI Policy has a condition field that determines whether the AI Policy runs for a given request. Write the condition as a CEL (Common Expression Language) expression. When a request comes in, AI Gateway evaluates the condition. If it matches, the AI Policy runs. If it doesn’t match, the AI Policy is skipped for that request.

For example, to run an AI Policy only when the request includes the header x-tier: premium:

condition: 'http.headers.x_tier == "premium"'

In the expression, write header names with underscores in place of hyphens, so x-tier becomes x_tier. AI Gateway validates the expression when you save the AI Policy and rejects an invalid one.

For the condition http.headers.x_tier == "premium":

• A request with the header x-tier: premium matches, so the AI Policy runs.
• A request with x-tier: free, any other value, or no x-tier header doesn’t match. AI Gateway skips the AI Policy and processes the request without applying the AI Policy.

An AI Policy takes its protocols from the entity it’s attached to. An AI Policy scoped to an AI Model, AI Agent, or AI MCP Server runs on the protocols of that entity’s Route. A global AI Policy runs only on HTTP and HTTPS traffic.

On a WebSocket route, an AI Policy scoped to an AI Model runs only if its type supports the ws and wss protocols. Otherwise, AI Gateway skips the AI Policy for that route.

An AI Policy specifies a type (like AI Sanitizer or AI Rate Limiting Advanced) and a config block that configures that behavior. AI Gateway applies the AI Policy at the scope you choose: globally across all traffic, or scoped to the entities where it is referenced.

The following example creates a global AI PII Sanitizer Policy that runs for every AI Gateway Route. It anonymizes high-risk PII categories (email, phone, SSN, and credit cards) along with custom patterns for sensitive tokens like AWS API keys and GitHub tokens.

This AI Policy connects to an AI PII Anonymizer service at host/port (sanitizer-service.internal:8080 in this example) to perform the actual sanitization. Substitute the address of your own running instance. See AI PII Anonymizer service for image access and setup instructions.

Without a reachable service at that address, requests through this AI Policy will fail.

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": "PII Sanitizer - Global",
      "name": "pii-sanitizer-global",
      "type": "ai-sanitizer",
      "enabled": true,
      "global": true,
      "config": {
        "anonymize": [
          "email",
          "phone",
          "ssn",
          "creditcard",
          "custom"
        ],
        "custom_patterns": [
          {
            "name": "aws_api_key",
            "regex": "AKIA[0-9A-Z]{16}",
            "score": 0.95
          },
          {
            "name": "github_token",
            "regex": "ghp_[A-Za-z0-9]{36}",
            "score": 0.9
          }
        ],
        "host": "sanitizer-service.internal",
        "port": 8080,
        "redact_type": "placeholder",
        "stop_on_error": true,
        "recover_redacted": false
      }
    }
    '

ai_gateway_policies:
  - ref: pii-sanitizer-global
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: PII Sanitizer - Global
    name: pii-sanitizer-global
    type: ai-sanitizer
    enabled: true
    global: true
    config:
      anonymize:
      - email
      - phone
      - ssn
      - creditcard
      - custom
      custom_patterns:
      - name: aws_api_key
        regex: AKIA[0-9A-Z]{16}
        score: 0.95
      - name: github_token
        regex: ghp_[A-Za-z0-9]{36}
        score: 0.9
      host: sanitizer-service.internal
      port: 8080
      redact_type: placeholder
      stop_on_error: true
      recover_redacted: false