Route By Header Policy

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

The Route By Header AI Policy sends a request to a different host when the request headers match a rule you define. Use it when requests for the same AI Agent or AI MCP Server must be served by different hosts, depending on a header value that the client sends, such as a region or an environment.

How does the Route By Header Policy work?

The Route By Header Policy evaluates the rules in config.rules. Each rule has a condition and an upstream_name. The condition is a map of header names to header values. The upstream_name is the host that receives the request when the condition matches. If the hostname can’t be resolved, AI Gateway returns a 503 response with the message name resolution failed.

AI Gateway evaluates the rules in the order you list them and applies the first rule that matches. A rule matches when the request includes every header in the condition with the exact value. Header names are case-insensitive, and header values are case-sensitive.

When a rule matches, AI Gateway replaces the host of the request with the upstream_name and sends the request to that host. The request keeps its original path and method. When no rule matches, AI Gateway sends the request to the URL configured on the AI Agent or AI MCP Server.

Scopes

Apply the Route By Header Policy globally to evaluate the rules for all AI Agent and AI MCP Server requests, or attach it to an AI Agent, an AI MCP Server, or an AI Consumer to evaluate the rules for that entity only. A global policy sends every request that includes a matching header, so choose header names and values that only your intended clients send. An AI Consumer’s rules apply after the client authenticates. For details about how scopes work, see AI Policy scopes.

Limitations

  • For AI Model traffic, AI Gateway sends requests to the AI Model’s own provider, regardless of the request headers.
  • The upstream_name is a hostname, not the name of an entity in AI Gateway. AI Gateway resolves the hostname through DNS from the data plane.

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!