Exit Transformer Policy

The Exit Transformer AI Policy customizes the responses that AI Gateway generates itself. You write one or more Lua functions that receive the response status, body, and headers, and return the values that AI Gateway sends to the client. Use it to change a message or status code, add headers, or reshape the structure of an error response so that it matches the format your clients expect.

The Exit Transformer Policy only affects responses that AI Gateway generates, such as an authentication error or a response from the Request Termination Policy. It doesn’t change responses that come from an upstream LLM provider, an AI Agent, or an upstream MCP server.

Anyone who can create or edit an Exit Transformer Policy can run Lua code on your data plane, within the limits of the sandbox.

Function syntax

Define the transformation in config.functions. Each entry is a string of Lua code that returns a function accepting status, body, and headers as parameters. The return values become the response AI Gateway sends to the client:

return function(status, body, headers)
  return status, body, headers
end

AI Gateway passes the responses it generates for matched requests through the functions. AI Gateway rejects a function that isn’t valid Lua when you create the Policy, and the error includes the line and column of the syntax error.

The status argument is always present, but body and headers can be nil. Check that they exist before you change them, and create them if they don’t.

Customize the response body and headers

The following example adds a prefix to the message of each response that AI Gateway generates for a matched request, and adds an X-Exit-Transformed header:

Handle unmatched routes

By default, the Policy transforms responses that AI Gateway generates after it matches a request to an entity. To also transform responses for requests that match no route, enable config.handle_unknown.

Caution: The handle_unknown parameter only works on a globally configured Policy. If you attach the Policy to an entity, such as an AI Model, AI Gateway doesn’t transform responses for unmatched routes.

The following example replaces the default 404 response with a custom message:

Scopes

Apply the Exit Transformer Policy globally to transform responses across all AI Gateway traffic, or attach it to an AI Model, AI Agent, AI MCP Server, AI Consumer, or AI Consumer Group to transform responses for that entity only. For details about how scopes work, see AI Policy scopes.

Authentication runs before an entity-scoped Policy. If you attach the Exit Transformer Policy to an AI Model that uses an AI Auth Strategy, the Policy doesn’t transform the authentication error that AI Gateway returns for a request without valid credentials. To transform authentication errors, apply the Policy globally.

Sandboxing

The Lua functions that you define in config.functions run in a sandboxed environment. The untrusted_lua data plane setting controls the sandbox, and its default value is strict. If a function needs a module or function that the strict sandbox restricts, set untrusted_lua to a less restrictive value, such as lax or on, in the data plane’s kong.conf file.

Sandboxing imposes several limitations on how custom Lua code can be executed, for heightened security. The Lua (or LuaJIT) language itself is not limited, only the available environment and the set of usable modules are restricted.

The limitations can be adjusted with the untrusted_lua=off|strict|lax|sandbox|on setting.

See the sandboxing reference for more information.

Looking for on-prem configuration? Convert the kongctl configuration to a decK yaml file and use deck file ai2kong. See Configure Kong AI Gateway on-prem for more information.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!