AI Custom Policies

Create an AI Custom Policy when you need behavior that the built-in AI Policies don’t provide. An AI Custom Policy registers your own plugin as a new AI Policy type.

An AI Custom Policy has two parts:

• A Lua schema that defines the configuration your policy accepts
• A Lua handler that implements the behavior, using the Plugin Development Kit (PDK)

Plugin development works the same way for AI Gateway and Kong Gateway, so you can reuse custom plugins you’ve already written.

Once registered, the AI Custom Policy’s name becomes a valid AI Policy type. You then attach it like any other AI Policy. Built-in policies each support a fixed set of scopes, but an AI Custom Policy has no scope restriction, so you can attach it at any scope, including to AI Consumers and AI Consumer Groups.

AI Custom Policies are managed through:

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

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

Each AI Custom Policy uses one of two modes, set by its type field:

• streaming: You upload both the schema and the handler. Konnect sends the handler to your data planes as part of their configuration.
• installed: You install the plugin on each data plane yourself and upload only its schema. Konnect doesn’t send any plugin code to data planes.

Streaming mode

Use streaming mode when you want Konnect to distribute your plugin, with no changes to data plane images or file systems.

Data planes must be started with KONG_CUSTOM_PLUGIN_STREAMING_ENABLED=on to accept streamed policies. The same limitations as streaming Kong Gateway plugins apply. For more information, see Streaming custom plugins.

Installed mode

Use installed mode for plugins that need more than a single schema and handler module, or that you already ship with your data planes.

First install the plugin on each data plane by following the installation guide. Then create the AI Custom Policy with the plugin’s schema.

Konnect applies the following rules when you create or update an AI Custom Policy:

You can’t delete an AI Custom Policy while any AI Policy uses it as its type. The request returns a 400 error until you delete or change those AI Policies.

To try the examples, export a sample schema and handler:

export LUA_SCHEMA="return{name='my-streaming-custom-policy',fields={{config={type='record',fields={}}}}}"
export LUA_HANDLER="return{PRIORITY=1000,VERSION='0.1.0',access=function(self,conf)kong.response.set_header('X-Custom-Policy','enabled')end}"

This handler adds an X-Custom-Policy: enabled header to responses for requests the policy runs on.

When you pass Lua through environment variables to the Konnect API, keep it on one line with no spaces or double quotes. Line breaks, spaces, and double quotes break the request body.

Create a streaming AI Custom Policy

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/custom-policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "my-streaming-custom-policy",
      "type": "streaming",
      "display_name": "Custom Policy - Streaming plugin",
      "schema": "'$LUA_SCHEMA'",
      "handler": "'$LUA_HANDLER'"
    }
    '

ai_gateway_custom_policies:
  - ref: my-streaming-custom-policy
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: my-streaming-custom-policy
    type: streaming
    display_name: Custom Policy - Streaming plugin
    schema: !env LUA_SCHEMA
    handler: !env LUA_HANDLER

Create an installed AI Custom Policy

Install the plugin on each data plane first. See Installed mode. The schema you upload must be the installed plugin’s schema.lua, so the name declared in it matches both the installed plugin and the AI Custom Policy’s name.

For a plugin named my-installed-custom-policy, set LUA_SCHEMA like this:

export LUA_SCHEMA="return{name='my-installed-custom-policy',fields={{config={type='record',fields={}}}}}"

This sample only works if a plugin named my-installed-custom-policy with this schema is installed on your data planes. In installed mode, Konnect doesn’t send any plugin code to data planes, so the AI Custom Policy only runs if the plugin is already installed.

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/custom-policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "my-installed-custom-policy",
      "type": "installed",
      "display_name": "Custom Policy - Installed plugin",
      "schema": "'$LUA_SCHEMA'"
    }
    '

ai_gateway_custom_policies:
  - ref: my-installed-custom-policy
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: my-installed-custom-policy
    type: installed
    display_name: Custom Policy - Installed plugin
    schema: !env LUA_SCHEMA

Use the AI Custom Policy in an AI Policy

Create an AI Policy with type set to the AI Custom Policy’s name. The following example applies the streaming AI Custom Policy globally:

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": "Custom header - Global",
      "name": "custom-header-global",
      "type": "my-streaming-custom-policy",
      "enabled": true,
      "global": true,
      "config": {}
    }
    '

ai_gateway_policies:
  - ref: custom-header-global
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Custom header - Global
    name: custom-header-global
    type: my-streaming-custom-policy
    enabled: true
    global: true
    config: {}

Update an AI Custom Policy

Updates replace the whole definition, so send every required field:

curl -X PUT "https://us.api.konghq.com/v1/ai-gateways/$AI_GATEWAY_ID/custom-policies/my-streaming-custom-policy" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "name": "my-streaming-custom-policy",
       "type": "streaming",
       "display_name": "Custom Policy - Streaming plugin (updated)",
       "schema": "'$LUA_SCHEMA'",
       "handler": "'$LUA_HANDLER'"
     }'

ai_gateway_custom_policies:
  - ref: my-streaming-custom-policy
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: my-streaming-custom-policy
    type: streaming
    display_name: Custom Policy - Streaming plugin (updated)
    schema: !env LUA_SCHEMA
    handler: !env LUA_HANDLER