Policies

Policies Policy A configuration that manipulates, secures, or observes traffic as it flows through agentgateway. Policies can be attached at the listener, route, or backend level. are a powerful feature of agentgateway that allow you to manipulate traffic as it flows through your gateway. Policies can be used to manipulate traffic, configurable observability, enforce rich security rules, and more.

Attachment points

You can attach policies at the listener Listener An entry point for incoming traffic into agentgateway. Listeners are configured on ports and support HTTP, HTTPS, TCP, and TLS protocols. , route Route A rule that matches incoming requests and forwards them to backends. Routes can match on path, hostname, headers, query parameters, and HTTP methods. , or backend Backend A destination service that receives traffic from agentgateway. Backends can be static hosts, MCP servers, LLM providers, or other services. level to provide fine-grained control over traffic.

Policies that are attached at multiple levels are applied at all levels.

Policy processing order

Agentgateway processes each request through four phases in the following order. You cannot change the phase order, but you can control which filters run in each phase by configuring the appropriate policy sections.

  graph LR
    frontend

    subgraph frontend ["Phase 1: Frontend"]
        fe_fields["tcp · tls · http<br/>accessLog · tracing"]
    end

    frontend --> prerouting

    subgraph prerouting ["Phase 2: PreRouting traffic"]
        pr["Auth (JWT, basic, API key)<br/>ExtAuth<br/>ExtProc<br/>Transformation"]
    end

    prerouting -->|route selection| postrouting

    subgraph postrouting ["Phase 3: PostRouting traffic"]
        po["CORS<br/>Auth (JWT, basic, API key)<br/>ExtAuth<br/>Rate limiting<br/>ExtProc<br/>Transformation<br/>CSRF<br/>Headers<br/>Host rewrite<br/>Direct response"]
    end

    postrouting --> backend

    subgraph backend ["Phase 4: Backend"]
        be_fields["tls · tcp · http · tunnel<br/>auth · transformation<br/>health · ai · mcp"]
    end

1. Frontend policies: Control how the gateway accepts incoming connections, including TLS settings, TCP configuration, and access logging. Frontend policies apply at the gateway level before any routing decisions.
2. PreRouting traffic policies: Run before route selection. Only a subset of traffic filters is available in the PreRouting phase. See PreRouting filters.
3. PostRouting traffic policies: Run after route selection. PostRouting is the default phase for traffic policies and supports all traffic filters.
4. Backend policies: Run when the gateway connects to the destination backend, including backend TLS, authentication, and health checking.

Within each phase, agentgateway merges all applicable policies with a shallow field-level merge. If two policies configure different fields, both apply. For example, if one policy sets transformation and another sets extAuth, both filters run. If two policies configure the same field, the higher-precedence policy takes effect. For details, see merge precedence.

Traffic filter execution order

Within the traffic phase (both PreRouting and PostRouting), filters execute in a fixed order. You cannot change this order.

PreRouting filters

The PreRouting phase supports only the following filters, in order of execution:

1. jwtAuthentication
2. basicAuthentication
3. apiKeyAuthentication
4. extAuth
5. extProc
6. transformation

To run a filter in the PreRouting phase, set phase: PreRouting on the traffic policy. PreRouting policies can only target a Gateway or ListenerSet.

Adjusting execution order with phases

You can use the PreRouting phase to run certain filters earlier in the request lifecycle. For example, to run external processing before rate limiting, configure an extProc policy with the PreRouting phase, and a separate rateLimit policy with the default PostRouting phase. External processing then runs during PreRouting (before route selection), and rate limiting runs during PostRouting (after route selection).

Example policy configuration

Review the following example configuration that uses one of each policy type.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  # Listener level policy
  # Enforces that incoming requests have a valid 




  API key
  
    API Key
    A secret token used to authenticate API requests. Agentgateway can validate API keys and attach metadata to authenticated requests.
    
  




  - policies:
      apiKey:
        mode: strict
        keys:
        - key: sk-testkey-1
          metadata:
            user: test
            role: admin
    routes:
    # Route level policy
    # Adds a header (based on a 




  CEL
  
    CEL (Common Expression Language)
    A simple expression language used throughout agentgateway to enable flexible configuration. CEL expressions can access request context, JWT claims, and other variables to make dynamic decisions.
    
  



 expression) with the authenticated user (based on the API key)
    - policies:
        transformations:
          request:
            set:
              x-authenticated-user: apiKey.user
      backends:
      - host: localhost:8080
        # Backend level policy
        # Adds an Authorization header to outgoing requests
        policies:
          backendAuth:
            key: my-authorization-header

More policy configuration guides

For more information about available policies, review the following guides: