CEL Cookbook for agentgateway

What CEL is and where it runs

CEL (Common Expression Language) is a small, fast, side-effect-free expression language designed by Google for policy evaluation. Agentgateway compiles CEL expressions from your CRD YAML once at config-load time and evaluates them per-request inside the Rust dataplane. Expressions run against a snapshot of the current request, response, identity context, and backend metadata. They never appear in request bodies and are always authored by an operator with CRD-write permissions.

CEL shows up in six surfaces across the agentgateway CRDs. This page covers all of them:

• Authorization rules (allow / deny / require against JWT claims, MCP tool names, source IPs, SPIFFE identities)
• Header and body transformations (request and response rewrite)
• Rate-limit descriptors (per-user, per-team, token-based cost)
• Logging, tracing, and metrics enrichment (custom log fields, trace attributes, Prometheus labels)
• MCP tool-level filtering
• LLM request/response transforms

The JWT payloads we'll use throughout

Two reference payloads. Every pattern in this page cites which one it matches against, so you can trace the claims in each expression back to these.

{
  "sub": "alice@example.com",
  "iss": "https://idp.example.com",
  "aud": ["agentgateway.example.com"],
  "groups": ["finance", "analysts"],
  "scope": "read mcp:tools",
  "department": "risk",
  "clearance": 3
}

{
  "sub": "agent-coach",
  "iss": "https://sts.internal.example.com",
  "aud": ["backend-mcp"],
  "scope": "read write admin",
  "act": {
    "sub": "agent-butler",
    "act": {
      "sub": "alice@example.com"
    }
  },
  "may_act": {
    "sub": "agent-butler"
  }
}

Variables available in CEL

The dataplane populates these namespaces before evaluating your expression. What's available depends on the route type and the phase (request vs response).

Custom functions reference

Agentgateway registers these functions on top of the standard CEL library. They're available in every CEL expression across all six surfaces.

Two call conventions show up. Functions documented as foo(x) are global, called with arguments. Functions shown as obj.foo(x) use receiver syntax: the value left of the dot is the target. merge, regexReplace, filterKeys, mapValues, and with all require a receiver. Calling them as a global (e.g. merge(a, b)) errors at runtime.

Authorization (Allow / Deny / Require)

OSS / ENT CEL field: traffic.authorization on AgentgatewayPolicy (and the enterprise wrapper). The shape is one action per policy: action: Allow | Deny | Require plus policy.matchExpressions[], where every expression in the list is AND-ed. For MCP, you can also attach authorization at the backend with backend.mcp.authorization, which runs per-tool: list_tools filters the listing, and call_tool rejects calls that don't match.

The semantics across multiple policies:

• Allow rules trigger deny-by-default. If any Allow policy matches, the request is allowed; if Allow policies exist and none match, the request is denied.
• Deny rules block on match. A Deny expression that fails to evaluate (for example, a missing JWT claim) is treated as not matching, which is risky — prefer Require when the check is critical.
• Require rules are conjunctive across merged policies: every Require policy must match.
• With no rules at all, traffic is allowed by default.

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: rbac-finance
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: mcp-route
  traffic:
    authorization:
      action: Allow
      policy:
        matchExpressions:
        - 'jwt.groups.exists(g, g == "finance")'

traffic:
  authorization:
    action: Allow
    policy:
      matchExpressions:
      - 'jwt.scope.contains("read")'
      - 'mcp.tool.name in ["get_profile", "list_accounts", "search_tools"]'

backend:
  mcp:
    authorization:
      action: Allow
      policy:
        matchExpressions:
        - 'jwt.sub == "alice@example.com" && mcp.tool.name == "get_me"'

traffic:
  authorization:
    action: Allow
    policy:
      matchExpressions:
      - 'jwt.groups.exists(g, g == "analysts")'
      - 'jwt.scope.contains("mcp:tools")'
      - 'mcp.tool.name in ["get_user_financial_profile", "analyze_portfolio"]'

traffic:
  authorization:
    action: Allow
    policy:
      matchExpressions:
      - 'jwt.act.sub == "agent-butler" && jwt.act.act.sub == "alice@example.com"'

traffic:
  authorization:
    action: Allow
    policy:
      matchExpressions:
      - 'cidr("10.0.0.0/8").containsIP(source.address)'

traffic:
  authorization:
    action: Deny
    policy:
      matchExpressions:
      - 'mcp.tool.name == "delete_account" && (!has(jwt.scope) || !jwt.scope.contains("admin"))'

traffic:
  authorization:
    action: Require
    policy:
      matchExpressions:
      - 'jwt.iss == "https://idp.example.com"'

Transformation (request + response rewrite)

ENT CEL fields under traffic.transformation on EnterpriseAgentgatewayPolicy: .request.set[].value, .request.add[].value, .request.body, .request.remove[], .response.set[].value, .response.add[].value, .response.body, .response.remove[]. The value on set/add entries is a CEL expression. remove is a plain header-name list (not CEL).

transformation:
  request:
    set:
    - name: x-user-id
      value: jwt.sub

transformation:
  request:
    add:
    - name: x-request-id
      value: uuid()

transformation:
  response:
    remove:
    - x-internal-trace
    - x-debug-info

transformation:
  request:
    body: 'json(request.body).merge({"caller_department": jwt.department}).toJson()'

transformation:
  request:
    set:
    - name: x-user-hash
      value: 'sha256.encode(request.headers["x-user-email"])'

Rate limiting

ENT CEL fields: traffic.localRateLimit.descriptors[].value and traffic.remoteRateLimit.descriptors[].cost on EnterpriseAgentgatewayPolicy. The value expression produces the descriptor key that the rate-limit server counts against. The cost expression (used with token-based rate limiting) computes how many tokens this request should consume.

localRateLimit:
  descriptors:
  - key: user
    value: jwt.sub

localRateLimit:
  descriptors:
  - key: team
    value: jwt.groups[0]

remoteRateLimit:
  descriptors:
  - key: team
    value: jwt.groups[0]
    cost: 'llm.totalTokens'

Observability (logging, tracing, metrics)

OSS / ENT These live on spec.frontend on AgentgatewayPolicy (or the enterprise wrapper) and only attach to Gateway targets:

• frontend.accessLog.filter (CEL bool — emit log only if true)
• frontend.accessLog.attributes.add[].{name, expression} (CEL string)
• frontend.tracing.randomSampling (CEL float 0 to 1, or bool — evaluated head-of-stream, so response-phase fields are not available)
• frontend.tracing.clientSampling (same shape; controls re-sampling of already-traced requests)
• frontend.tracing.attributes.add[].{name, expression} (CEL string)
• frontend.metrics.attributes.add[].{name, expression} (CEL string)

frontend:
  accessLog:
    filter: 'response.code >= 500'

frontend:
  tracing:
    attributes:
      add:
      - name: user.id
        expression: 'jwt.sub'
      - name: user.department
        expression: 'default(jwt.department, "unknown")'

frontend:
  metrics:
    attributes:
      add:
      - name: department
        expression: 'default(jwt.department, "none")'

frontend:
  tracing:
    randomSampling: '0.1'

# Branch on request-phase fields:
frontend:
  tracing:
    randomSampling: 'request.path.startsWith("/admin/") ? 1.0 : 0.1'

LLM request transformations

OSS / ENT CEL fields under spec.backend.ai on AgentgatewayPolicy (and the enterprise wrapper). The policy attaches to an AgentgatewayBackend of type ai:

• backend.ai.transformations[].{field, expression} — set a top-level field on the LLM request body to the CEL result. Higher priority than defaults or overrides when the same field is set in more than one place.
• backend.ai.defaults[].{field, value} — supply a default for an absent field (literal JSON, not CEL).
• backend.ai.overrides[].{field, value} — force a field value, overriding caller input (literal JSON, not CEL).
• backend.ai.prompt (separate from CEL) — prepend or append static system-prompt content. Not a CEL hook.

For PII redaction and response-side guardrails, agentgateway has a separate backend.ai.promptGuard mechanism (not CEL). There is no general-purpose CEL hook for rewriting the LLM response body in stream today; for that, use Prompt Guard or ExtProc.

# EnterpriseAgentgatewayPolicy targeting an AI backend
# spec.backend.ai.transformations[].{field, expression}
backend:
  ai:
    transformations:
    - field: temperature
      expression: 'jwt.groups.exists(g, g == "research") ? 0.9 : 0.2'

backend:
  ai:
    transformations:
    - field: metadata
      expression: '{"team": jwt.groups[0], "user": jwt.sub}'

Best-practices checklist