AI AWS Guardrails Policy

The AI AWS Guardrails Policy enforces introspection on both inbound requests and outbound responses handled by the AI Model entity. It integrates with the AWS Bedrock Guardrails service to apply compliance and safety policies at the AI Gateway level. This ensures all data exchanged between clients and upstream LLMs adheres to the configured security standards.

Before using the AI AWS Guardrails Policy, you must define your guardrail policies in AWS. You can do this through:

• The AWS Console
• The CreateGuardrail API

The AI AWS Guardrails Policy includes a configurable response_buffer_size parameter. This setting controls how many tokens from the upstream LLM response are buffered during streaming before being sent to the AWS Guardrails service for inspection. For example, setting response_buffer_size to 50 means the AI AWS Guardrails Policy will collect 50 tokens from the upstream model before sending them to AWS Guardrails for evaluation. Guardrail evaluation runs in chunks as tokens stream in.

A smaller buffer size allows faster policy evaluation and quicker response rejection but may increase the number of guardrail calls. Larger sizes reduce API calls but may delay policy enforcement.

For response and request inspection, the Policy by default guards input only. You can change this behavior with the guarding_mode field, which supports INPUT, OUTPUT, or BOTH. To control which parts of the conversation are sent for content evaluation, use the text_source field. Set it to concatenate_user_content to inspect only user input, or concatenate_all_content to include the full exchange, including system and assistant messages.

The AI AWS Guardrails 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.

In none mode, the error message is the blocked message that you configured for the guardrail in AWS. The following response is the body for a request blocked in none mode:

{
  "error": {
    "message": "Blocked by AWS guardrail (input)"
  }
}

In verbose mode, reason is the same blocked message, and detail is the list of assessments that AWS Bedrock Guardrails returned for the content. The assessments depend on which filters in your AWS guardrail matched. For example, a request that contains a word from a custom word filter returns the following response:

{
  "error": {
    "type": "guardrail_rejected",
    "plugin": "ai-aws-guardrails",
    "reason": "Blocked by AWS guardrail (input)",
    "code": "GUARDRAIL_BLOCKED",
    "detail": [
      {
        "appliedGuardrailDetails": {
          "guardrailId": "dlk3bhgw5pms",
          "guardrailVersion": "DRAFT",
          "guardrailArn": "arn:aws:bedrock:us-east-1:123456789012:guardrail/dlk3bhgw5pms",
          "guardrailOrigin": ["REQUEST"],
          "guardrailOwnership": "SELF"
        },
        "wordPolicy": {
          "customWords": [
            {
              "match": "bananaphone",
              "action": "BLOCKED",
              "detected": true
            }
          ]
        }
      }
    ]
  }
}

In verbose mode, the detail field includes the guardrail ARN, which contains your AWS account ID, along with the matched content. Only use verbose mode for clients that you trust with this information.

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 AWS Guardrails - Verbose Rejection",
      "name": "ai-aws-guardrails",
      "type": "ai-aws-guardrails",
      "config": {
        "aws_region": "us-east-1",
        "guardrails_id": "'$GUARDRAILS_ID'",
        "guardrails_version": "DRAFT",
        "aws_access_key_id": "'$AWS_ACCESS_KEY_ID'",
        "aws_secret_access_key": "'$AWS_SECRET_ACCESS_KEY'",
        "rejection_mode": "verbose"
      }
    }
    '

ai_gateway_policies:
  - ref: ai-aws-guardrails
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: AI AWS Guardrails - Verbose Rejection
    name: ai-aws-guardrails
    type: ai-aws-guardrails
    config:
      aws_region: us-east-1
      guardrails_id: !env GUARDRAILS_ID
      guardrails_version: DRAFT
      aws_access_key_id: !env AWS_ACCESS_KEY_ID
      aws_secret_access_key: !env AWS_SECRET_ACCESS_KEY
      rejection_mode: verbose

To run the AI AWS Guardrails 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.

This Policy works with all of the AI Model entity’s model.capabilities settings.

The AI AWS Guardrails Policy supports AWS Identity and Access Management (IAM) roles. This allows the AWS Bedrock Guardrails service to be accessed using role assumption instead of static credentials.

To use AWS IAM roles with the Policy, set the config.aws_assume_role_arn, and config.aws_role_session_name.

Note: These fields can be used with or without static AWS credentials (config.aws_access_key_id and config.aws_secret_access_key).

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

The AI AWS Guardrails 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.aws-guardrails.input_faulty_prompt and ai.proxy.aws-guardrails.output_faulty_response in each log entry.

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.