Templating language

Agentgateway transformation templates are written in Common Expression Language (CEL). CEL is a fast, portable, and safely executable language that goes beyond declarative configurations. With CEL, you can develop more complex expressions in a readable, developer-friendly syntax and use them to extract and transform values from requests and responses.

You can apply CEL transformations to routes for LLM providers, MCP servers, inference services, agents, and HTTP services.

Where can CEL be used?

Transformations can modify the headers and body of a request or response. Each transformation is expressed as static values, built-in CEL functions, or context variables to extract and inject information.

AgentgatewayPolicy structure for transformations:

traffic:
  transformation:
    request:
      set:
      add: 
      remove:
      body:
      metadata:
    response: 
      set:
      add: 
      remove:
      body:
      metadata:

Header transformations

Use header transformations to add, overwrite, or remove headers on a request before it reaches the upstream, or on a response before it reaches the client. Three operations are supported:

• set: Creates a header or overwrites it if it already exists.
• add: Adds a value to a header without removing existing values. If the header already exists, the header is not overwritten. Instead, another header with the same key is added and set to the value of your transformation.
• remove: Strips a header entirely.

Each set or add entry takes a name and a value. The value is a CEL expression that can be a static string, a call to a built-in function, or a reference to a context variable such as request.headers["x-foo"], jwt.sub, or llm.requestModel.

You might use these transformations for injecting routing hints, auth context, or tracing metadata that the upstream expects but the client does not send.

Request header example to build a forwarded URI from context variables:

traffic:
  transformation:
    request:
      set:
      - name: x-forwarded-uri
        value: 'request.scheme + "://" + request.host + request.path'

For more information, see Create redirect URLs.

Response header example to encode a header value with a CEL function, set a dynamic status code with a conditional expression, and remove a header:

traffic:
  transformation:
    response:
      set:
      - name: x-user-id-encoded
        value: 'base64.encode(request.headers["x-user-id"])'
      - name: ":status"
        value: 'request.uri.contains("foo=bar") ? 401 : 403'
      remove:
      - access-control-allow-credentials

For more information, see Inject response headers.

Body transformations

Use body transformations to replace the entire body of a request or response with a new value. The body field takes a single CEL expression that must evaluate to a string. You can build the new body from static values, CEL functions such as json() and toJson(), or context variables such as request.body or response.body.

Response body example to construct a JSON response body from request context variables:

traffic:
  transformation:
    response:
      body: '"{\"path\": \"" + request.path + "\", \"method\": \"" + request.method + "\"}"'

For more information, see Inject response bodies.

Request body example to strip internal fields and merge in defaults before forwarding:

traffic:
  transformation:
    request:
      body: 'toJson(json(request.body).filterKeys(k, !k.startsWith("x_")).merge({"model": "gpt-4o", "max_tokens": 2048}))'

For more information, see Filter and merge request body fields.

Pre-compute values with metadata

Use the metadata field to evaluate a CEL expression once and make the result available as metadata.<name> in the set, add, and body fields of the same transformation. metadata keys are evaluated before any other fields in the transformation, so they can be referenced anywhere in the same block.

This field is useful when the same complex expression would otherwise be repeated. For example, if you parse a JSON body field to inject it as a header and also use it in a condition, writing it twice creates noise and a maintenance risk. With metadata, you write it once.

traffic:
  transformation:
    response:
      metadata:
        parsedModel: 'string(json(response.body).model)'
      set:
      - name: x-actual-model
        value: metadata.parsedModel
      - name: x-model-changed
        value: 'metadata.parsedModel != string(json(request.body).model) ? "true" : "false"'

metadata values are only available within the same transformation block. They are not accessible in access log or tracing CEL expressions.

For a full example, see Inject LLM model headers.

CEL syntax quick reference

Use these patterns to build expressions for header values, body content, and conditional logic in your transformation policies.

YAML quoting: When a CEL expression is a string literal or starts with a quote, wrap it in single quotes in YAML so the inner double quotes are preserved:

Context variables

Context variables give CEL expressions access to information about the current request, response, and connection. They are populated automatically by agentgateway at runtime so you do not need to declare or configure them. Use them to read values such as headers, path, method, JWT claims, or LLM model names and inject them into headers, bodies, or conditions.

Variables are only populated when they are relevant to the current request. For example, jwt is only present when a JWT has been validated, and llm is only present when the route is backed by an LLM provider. Referencing an absent variable in a CEL expression produces an error. Use default(expression, fallback) to avoid this error.

Not all variables are available in every policy type. The table below lists which variables are available depending on where the CEL expression is evaluated.

Built-in functions

Built-in functions extend CEL with capabilities that go beyond simple variable access and arithmetic. Use them to parse and serialize data, encode values, generate identifiers, and manipulate strings and maps. For example, json() parses a raw request body string into a map so you can access individual fields, base64.encode() encodes a header value for safe transmission, and default() provides a fallback when a variable might not be present.

The output of one function can be passed as the input of another. For example, string(json(request.body).model) parses the body, extracts the model field, and converts the result to a string in a single expression.

Function examples

These functions are used in the documentation examples in this section.

Transformation phases

Transformations in spec.traffic support a phase field that controls when the policy is evaluated in the request lifecycle. If phase is omitted, PostRouting is used.

Example:

spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
  traffic:
    phase: PreRouting
    transformation:
      request:
        set:
        - name: x-phase
          value: '"pre-routing"'

Next steps

To learn more about how to use CEL, refer to the following resources:

• CEL reference
• cel.dev tutorial