Route Transformer Advanced Policy

Related Documentation
Made by
Kong Inc.
Priority
780
Minimum Version
AI Gateway - 2.0

AI Model scope: The Route Transformer Advanced Policy applies to AI Agents and AI MCP Servers. For an AI Model, AI Gateway sends the request to the provider’s original host, port, and path. This applies when you attach the policy to an AI Consumer that calls the AI Model, or apply it globally.

The Route Transformer Advanced AI Policy changes the host, port, or path that AI Gateway uses when it sends a request to your AI Agents and AI MCP Servers. Use it when the upstream location depends on something in the request, such as a header that the client sets, and the client can’t build that location itself. You can set each value to a fixed string or build it from the request with templates.

When you set the path, the value replaces the whole upstream path, and AI Gateway keeps the query string. When you set host or port, AI Gateway sends the new host and port in the Host header.

Set config.escape_path to true when a template can produce characters that aren’t valid in a URL path, such as spaces. AI Gateway then URL-encodes those characters.

Templates

The Route Transformer Advanced Policy accepts values from the request in config.host, config.port, and config.path. The following table lists the supported sources:

Source

Template

Header
  • $(headers.{HEADER-NAME})
  • $(headers["{HEADER-NAME}"])
Query parameter
  • $(query_params.{QUERY-PARAM-NAME})
  • $(query_params["{QUERY-PARAM-NAME}"])
Captured URI group
  • $(uri_captures.{GROUP-NAME})
  • $(uri_captures["{GROUP-NAME}"])
Shared variable
  • $(shared.{VARIABLE-NAME})
  • $(shared["{VARIABLE-NAME}"])

Captured URI groups are the named groups in a regular expression route path in the config.route.paths of an AI Agent. Shared variables are values that another AI Policy stores in the shared request context, for example with a property node.

Templates use the request as it is when the policy runs. A header that the Request Transformer policy adds is available in a template, because Request Transformer runs first.

To use the text of a template literally, wrap it in quotes inside another template. For example, $('$(headers["x-test"])') renders as the text $(headers["x-test"]).

Advanced templates

AI Gateway evaluates the content of $(...) as a Lua expression, so you can use logical operators. For example, the following template uses a captured URI group, then a query parameter, and then a default value:

$(uri_captures["user-id"] or query_params["user"] or "unknown")

You can combine constant text with templates. For example, /orders/$(headers["Custom-Path"] or "default") adds a fixed prefix to a value from a header, and uses default when the request doesn’t include the header.

To run more logic, wrap a Lua function in an expression:

$((function() ... implementation here ... end)())

The following template uses the first three characters of a header value as the path. When the request doesn’t include the header, the template returns default:

/$((function()
    local value = headers["Custom-Path"]
    if not value then
      return "default"
    end
    return value:sub(1, 3)
  end)())

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.

Templates treat trailing whitespace and newlines as part of the value. Make sure that multi-line templates don’t end with extra whitespace or newlines, because AI Gateway adds them to the generated value.

Scopes

The Route Transformer Advanced Policy supports global scope and entity scope. Apply it globally to change the upstream destination of all AI Agent and AI MCP Server traffic on the data plane. Attach it to an AI Agent, an AI MCP Server, or an AI Consumer to change it for that entity only. A Policy attached to an AI Consumer applies after the client authenticates. For details about how scopes work, see AI Policy scopes.

Global scope: A global Route Transformer Advanced Policy changes the destination of every request that matches, including requests to entities that you didn’t plan to change. Add a condition to limit which requests the Policy changes.

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!