Routes

Match incoming requests and apply traffic policies before forwarding to a backend.

Routes live inside listeners and define how agentgateway matches and handles incoming HTTP requests. Each route specifies optional matching criteria, an optional set of policies, and the backends to forward matching traffic to.

Fields

routes[].name · string

A human-readable name for this route. Used in logs, traces, and metrics. Recommended for configurations with multiple routes.

routes[].namespace · string

The namespace this route belongs to. Used when agentgateway is managed by a control plane. Can be omitted for local file-based configurations.

routes[].ruleName · string

An internal rule identifier, used by the XDS control plane. For local configurations, omit this field.

routes[].hostnames · string[]

Additional hostname constraints for this route. Requests must match both the parent listener’s hostname and the route’s hostname. Accepts wildcards, e.g. "*.example.com".

When omitted, the route matches any hostname accepted by the listener.

routes[].matches · array

An array of match criteria. A request must satisfy all conditions within a single match object. If multiple match objects are listed, a request matching any one of them qualifies.

When matches is omitted entirely, the route matches all requests.

Show match fields

matches[].method · string

Match on the HTTP method. Example: GET, POST, DELETE.

matches[].path · object

Match on the request path. Exactly one of exact, pathPrefix, or regex must be set.

Show path match types

matches[].path.exact · string

The request path must exactly equal this value.

matches[].path.pathPrefix · string

The request path must begin with this prefix.

matches[].path.regex · string

The request path must match this regular expression.

matches[].headers · array

A list of HTTP header match conditions. All listed headers must be present and match.

Show header match fields

matches[].headers[].name · string · required

The header name to match (case-insensitive).

matches[].headers[].value.exact · string

The header value must exactly equal this string.

matches[].headers[].value.regex · string

The header value must match this regular expression.

matches[].query · array

A list of URL query parameter match conditions. All listed parameters must be present and match.

Show query match fields

matches[].query[].name · string · required

The query parameter name.

matches[].query[].value.exact · string

The query parameter value must exactly equal this string.

matches[].query[].value.regex · string

The query parameter value must match this regular expression.

routes[].policies · object

Traffic policies applied to requests and responses that match this route. All policies are optional.

See Policies below for the full list.

routes[].backends · array

The backends to forward matched traffic to. See Backends for the full type reference.

Route priority and matching order

Routes are evaluated in the order they appear in the configuration. The first route whose match conditions are satisfied handles the request — subsequent routes are not evaluated.

Routes without a matches block match every request. Place them last to act as a catch-all fallback.

routes:
  # Most specific — matched first
  - name: exact-path
    matches:
      - path:
          exact: /api/v2/status
    backends:
      - host: status-service:8080

  # Less specific — path prefix
  - name: api-prefix
    matches:
      - path:
          pathPrefix: /api
    backends:
      - host: api-service:8080

  # Catch-all — matched last
  - name: default
    backends:
      - host: default-service:8080

Matching examples

Match by path prefix, method, query parameter, and header

This example is from the HTTP example config. It matches GET /match?param=hello requests with an x-header matching a numeric pattern.

http/config.yaml

- name: match-example
  matches:
    - path:
        pathPrefix: /match
      method: GET
      query:
        - name: param
          value:
            exact: hello
      headers:
        - name: x-header
          value:
            regex: "test-[0-9]"
  backends:
    - host: 127.0.0.1:8080

Test with:

curl '127.0.0.1:3000/match?param=hello' -H "x-header: test-0"

Multiple match objects (OR logic)

A request matching either condition is accepted.

- name: multi-match
  matches:
    - path:
        exact: /health
    - path:
        exact: /ready
  backends:
    - host: probe-service:8080

Wildcard hostname on route

- name: wildcard-host
  hostnames:
    - "*.internal.example.com"
  backends:
    - host: internal-service:8080

Catch-all with no match conditions

- name: default
  backends:
    - host: fallback-service:8080

Policies

Policies are applied to all requests matching this route. Multiple policies can be combined.

requestHeaderModifier — modify request headers

Add, set, or remove HTTP headers before the request reaches the backend.

policies:
  requestHeaderModifier:
    add:
      x-request-id: "auto"
    set:
      x-forwarded-for: "client"
    remove:
      - x-illegal-header

• add — append a header (preserves existing values).
• set — overwrite a header.
• remove — delete a header.

responseHeaderModifier — modify response headers

Add, set, or remove HTTP headers on the response.

policies:
  responseHeaderModifier:
    set:
      x-powered-by: agentgateway

cors — CORS preflight handling

Handle CORS preflight requests and append CORS headers to applicable responses.

policies:
  cors:
    allowOrigins:
      - "*"
    allowHeaders:
      - content-type
      - mcp-protocol-version
    exposeHeaders:
      - Mcp-Session-Id
    allowMethods:
      - GET
      - POST
    allowCredentials: true
    maxAge: 86400s

urlRewrite — rewrite URL path or authority

Modify the request URL path or Host header before forwarding to the backend.

policies:
  urlRewrite:
    path:
      full: "/new-path"        # Replace entire path
      # prefix: "/v2"          # Replace matched prefix
    authority:
      full: "custom-host-header"

requestRedirect — respond with a redirect

Return a redirect response directly from the gateway without contacting the backend.

policies:
  requestRedirect:
    scheme: https
    authority:
      host: new.example.com
    status: 301

directResponse — return a static response

Return a static response body and status code without contacting any backend.

policies:
  directResponse:
    status: 200
    body: "hello!"

requestMirror — mirror traffic to a second backend

Duplicate a percentage of incoming requests to a mirror backend. The mirror response is discarded.

policies:
  requestMirror:
    backend:
      host: 127.0.0.1:8081
    percentage: 0.5    # 50%

localRateLimit — token-bucket rate limiting

Limit incoming requests using a local in-process token bucket. State is not shared across gateway replicas.

policies:
  localRateLimit:
    - maxTokens: 10
      tokensPerFill: 1
      fillInterval: 1s

authorization — CEL-based HTTP access control

Evaluate CEL expressions against request attributes to allow or deny access.

policies:
  authorization:
    rules:
      - |
        cidr("127.0.0.1/8").containsIP(source.address)

mcpAuthentication — JWT authentication for MCP clients

Validate JWT tokens presented by MCP clients. Supports Auth0, Keycloak, and generic JWKS sources.

policies:
  mcpAuthentication:
    issuer: https://auth.example.com
    audiences:
      - my-mcp-gateway
    jwks:
      url: https://auth.example.com/.well-known/jwks.json

mcpAuthorization — authorization rules for MCP access

Apply CEL-based authorization rules specifically to MCP traffic.

policies:
  mcpAuthorization:
    rules:
    - 'mcp.tool.name == "echo"'
    - 'jwt.sub == "admin" && mcp.tool.name == "add"'

a2a — mark route as A2A traffic

Enable A2A protocol processing and telemetry for this route. Required when using A2A backends.

policies:
  a2a: {}

backendTLS — send TLS to the backend

Configure the TLS connection agentgateway establishes with the upstream backend.

policies:
  backendTLS:
    cert: /etc/certs/client.crt
    key: /etc/certs/client.key
    root: /etc/certs/ca.crt
    hostname: backend.internal

See Policies: TLS for the full field reference.

backendAuth — authenticate to the backend

Attach credentials when connecting to upstream services. Supports passthrough, static API keys, GCP, AWS, and Azure.

policies:
  backendAuth:
    key: "Bearer secret-api-key"

See Backends for all backendAuth variants.

jwtAuth — JWT authentication for any route

Validate JWT tokens for any HTTP route (not limited to MCP). Makes JWT claims available as jwt.<claim> in CEL expressions.

policies:
  jwtAuth:
    issuer: agentgateway.dev
    audiences:
    - test.agentgateway.dev
    jwks:
      file: ./manifests/jwt/pub-key

See Policies: Authentication for full reference.

extAuthz — external authorization service

Delegate authorization decisions to an external service via HTTP or gRPC.

policies:
  extAuthz:
    host: localhost:4180
    protocol:
      http:
        path: '"/oauth2/auth"'
    includeRequestHeaders:
    - cookie

timeout — request and backend timeouts

Timeout requests that exceed the configured duration.

policies:
  timeout:
    requestTimeout: 30s
    backendRequestTimeout: 25s

retry — automatic request retries

Retry failed requests automatically. From the HTTP example source:

policies:
  retry:
    attempts: 2
    codes:
    - 429

ai — LLM traffic policies

Mark this route as LLM traffic and enable AI-specific features such as prompt guards and prompt enrichment.

policies:
  ai:
    promptGuard:
      request:
      - regex:
          action: reject
          rules:
          - builtin: email

See Policies: AI Prompt Guard for details.