> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# Routes

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

Routes live inside [listeners](/reference/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](/reference/backends) to forward matching traffic to.

## Fields

<ParamField path="routes[].name" type="string">
  A human-readable name for this route. Used in logs, traces, and metrics. Recommended for configurations with multiple routes.
</ParamField>

<ParamField path="routes[].namespace" type="string">
  The namespace this route belongs to. Used when agentgateway is managed by a control plane. Can be omitted for local file-based configurations.
</ParamField>

<ParamField path="routes[].ruleName" type="string">
  An internal rule identifier, used by the XDS control plane. For local configurations, omit this field.
</ParamField>

<ParamField path="routes[].hostnames" type="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.
</ParamField>

<ParamField path="routes[].matches" type="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.

  <Expandable title="match fields">
    <ParamField path="matches[].method" type="string">
      Match on the HTTP method. Example: `GET`, `POST`, `DELETE`.
    </ParamField>

    <ParamField path="matches[].path" type="object">
      Match on the request path. Exactly one of `exact`, `pathPrefix`, or `regex` must be set.

      <Expandable title="path match types">
        <ParamField path="matches[].path.exact" type="string">
          The request path must exactly equal this value.
        </ParamField>

        <ParamField path="matches[].path.pathPrefix" type="string">
          The request path must begin with this prefix.
        </ParamField>

        <ParamField path="matches[].path.regex" type="string">
          The request path must match this regular expression.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="matches[].headers" type="array">
      A list of HTTP header match conditions. All listed headers must be present and match.

      <Expandable title="header match fields">
        <ParamField path="matches[].headers[].name" type="string" required>
          The header name to match (case-insensitive).
        </ParamField>

        <ParamField path="matches[].headers[].value.exact" type="string">
          The header value must exactly equal this string.
        </ParamField>

        <ParamField path="matches[].headers[].value.regex" type="string">
          The header value must match this regular expression.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="matches[].query" type="array">
      A list of URL query parameter match conditions. All listed parameters must be present and match.

      <Expandable title="query match fields">
        <ParamField path="matches[].query[].name" type="string" required>
          The query parameter name.
        </ParamField>

        <ParamField path="matches[].query[].value.exact" type="string">
          The query parameter value must exactly equal this string.
        </ParamField>

        <ParamField path="matches[].query[].value.regex" type="string">
          The query parameter value must match this regular expression.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="routes[].policies" type="object">
  Traffic policies applied to requests and responses that match this route. All policies are optional.

  See [Policies](#policies) below for the full list.
</ParamField>

<ParamField path="routes[].backends" type="array">
  The backends to forward matched traffic to. See [Backends](/reference/backends) for the full type reference.
</ParamField>

## 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.

```yaml theme={null}
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.

```yaml http/config.yaml theme={null}
- 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:

```bash theme={null}
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.

```yaml theme={null}
- name: multi-match
  matches:
    - path:
        exact: /health
    - path:
        exact: /ready
  backends:
    - host: probe-service:8080
```

### Wildcard hostname on route

```yaml theme={null}
- name: wildcard-host
  hostnames:
    - "*.internal.example.com"
  backends:
    - host: internal-service:8080
```

### Catch-all with no match conditions

```yaml theme={null}
- name: default
  backends:
    - host: fallback-service:8080
```

## Policies

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

<AccordionGroup>
  <Accordion title="requestHeaderModifier — modify request headers">
    Add, set, or remove HTTP headers before the request reaches the backend.

    ```yaml theme={null}
    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.
  </Accordion>

  <Accordion title="responseHeaderModifier — modify response headers">
    Add, set, or remove HTTP headers on the response.

    ```yaml theme={null}
    policies:
      responseHeaderModifier:
        set:
          x-powered-by: agentgateway
    ```
  </Accordion>

  <Accordion title="cors — CORS preflight handling">
    Handle CORS preflight requests and append CORS headers to applicable responses.

    ```yaml theme={null}
    policies:
      cors:
        allowOrigins:
          - "*"
        allowHeaders:
          - content-type
          - mcp-protocol-version
        exposeHeaders:
          - Mcp-Session-Id
        allowMethods:
          - GET
          - POST
        allowCredentials: true
        maxAge: 86400s
    ```
  </Accordion>

  <Accordion title="urlRewrite — rewrite URL path or authority">
    Modify the request URL path or `Host` header before forwarding to the backend.

    ```yaml theme={null}
    policies:
      urlRewrite:
        path:
          full: "/new-path"        # Replace entire path
          # prefix: "/v2"          # Replace matched prefix
        authority:
          full: "custom-host-header"
    ```
  </Accordion>

  <Accordion title="requestRedirect — respond with a redirect">
    Return a redirect response directly from the gateway without contacting the backend.

    ```yaml theme={null}
    policies:
      requestRedirect:
        scheme: https
        authority:
          host: new.example.com
        status: 301
    ```
  </Accordion>

  <Accordion title="directResponse — return a static response">
    Return a static response body and status code without contacting any backend.

    ```yaml theme={null}
    policies:
      directResponse:
        status: 200
        body: "hello!"
    ```
  </Accordion>

  <Accordion title="requestMirror — mirror traffic to a second backend">
    Duplicate a percentage of incoming requests to a mirror backend. The mirror response is discarded.

    ```yaml theme={null}
    policies:
      requestMirror:
        backend:
          host: 127.0.0.1:8081
        percentage: 0.5    # 50%
    ```
  </Accordion>

  <Accordion title="localRateLimit — token-bucket rate limiting">
    Limit incoming requests using a local in-process token bucket. State is not shared across gateway replicas.

    ```yaml theme={null}
    policies:
      localRateLimit:
        - maxTokens: 10
          tokensPerFill: 1
          fillInterval: 1s
    ```
  </Accordion>

  <Accordion title="authorization — CEL-based HTTP access control">
    Evaluate CEL expressions against request attributes to allow or deny access.

    ```yaml theme={null}
    policies:
      authorization:
        rules:
          - |
            cidr("127.0.0.1/8").containsIP(source.address)
    ```
  </Accordion>

  <Accordion title="mcpAuthentication — JWT authentication for MCP clients">
    Validate JWT tokens presented by MCP clients. Supports Auth0, Keycloak, and generic JWKS sources.

    ```yaml theme={null}
    policies:
      mcpAuthentication:
        issuer: https://auth.example.com
        audiences:
          - my-mcp-gateway
        jwks:
          url: https://auth.example.com/.well-known/jwks.json
    ```
  </Accordion>

  <Accordion title="mcpAuthorization — authorization rules for MCP access">
    Apply CEL-based authorization rules specifically to MCP traffic.

    ```yaml theme={null}
    policies:
      mcpAuthorization:
        rules:
        - 'mcp.tool.name == "echo"'
        - 'jwt.sub == "admin" && mcp.tool.name == "add"'
    ```
  </Accordion>

  <Accordion title="a2a — mark route as A2A traffic">
    Enable A2A protocol processing and telemetry for this route. Required when using A2A backends.

    ```yaml theme={null}
    policies:
      a2a: {}
    ```
  </Accordion>

  <Accordion title="backendTLS — send TLS to the backend">
    Configure the TLS connection agentgateway establishes with the upstream backend.

    ```yaml theme={null}
    policies:
      backendTLS:
        cert: /etc/certs/client.crt
        key: /etc/certs/client.key
        root: /etc/certs/ca.crt
        hostname: backend.internal
    ```

    See [Policies: TLS](/reference/policies/tls) for the full field reference.
  </Accordion>

  <Accordion title="backendAuth — authenticate to the backend">
    Attach credentials when connecting to upstream services. Supports passthrough, static API keys, GCP, AWS, and Azure.

    ```yaml theme={null}
    policies:
      backendAuth:
        key: "Bearer secret-api-key"
    ```

    See [Backends](/reference/backends) for all `backendAuth` variants.
  </Accordion>

  <Accordion title="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.

    ```yaml theme={null}
    policies:
      jwtAuth:
        issuer: agentgateway.dev
        audiences:
        - test.agentgateway.dev
        jwks:
          file: ./manifests/jwt/pub-key
    ```

    See [Policies: Authentication](/reference/policies/authentication) for full reference.
  </Accordion>

  <Accordion title="extAuthz — external authorization service">
    Delegate authorization decisions to an external service via HTTP or gRPC.

    ```yaml theme={null}
    policies:
      extAuthz:
        host: localhost:4180
        protocol:
          http:
            path: '"/oauth2/auth"'
        includeRequestHeaders:
        - cookie
    ```
  </Accordion>

  <Accordion title="timeout — request and backend timeouts">
    Timeout requests that exceed the configured duration.

    ```yaml theme={null}
    policies:
      timeout:
        requestTimeout: 30s
        backendRequestTimeout: 25s
    ```
  </Accordion>

  <Accordion title="retry — automatic request retries">
    Retry failed requests automatically. From the HTTP example source:

    ```yaml theme={null}
    policies:
      retry:
        attempts: 2
        codes:
        - 429
    ```
  </Accordion>

  <Accordion title="ai — LLM traffic policies">
    Mark this route as LLM traffic and enable AI-specific features such as prompt guards and prompt enrichment.

    ```yaml theme={null}
    policies:
      ai:
        promptGuard:
          request:
          - regex:
              action: reject
              rules:
              - builtin: email
    ```

    See [Policies: AI Prompt Guard](/reference/policies/ai-prompt-guard) for details.
  </Accordion>
</AccordionGroup>