For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Routes

Configure routes on listeners for agentgateway.

RoutesRouteA rule that matches incoming requests and forwards them to backends. Routes can match on path, hostname, headers, query parameters, and HTTP methods. are the entry points for traffic to your agentgateway. They are configured on listeners and are used to route traffic to backendsBackendA destination service that receives traffic from agentgateway. Backends can be static hosts, MCP servers, LLM providers, or other services..

Types of routes

You can configure two types of routes: HTTP routes (routes) and TCP routes (tcpRoutes).

HTTP routes

HTTP or HTTPS listeners use routes to configure HTTP routes. HTTP routes support all HTTP features such as path, header, method, or query matchingMatchingThe process of determining which route should handle an incoming request based on criteria such as path, hostname, headers, query parameters, or HTTP methods., and HTTP-specific filters and policiesPolicyA configuration that manipulates, secures, or observes traffic as it flows through agentgateway. Policies can be attached at the listener, route, or backend level..

Example configuration:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 8080
  listeners:
  - name: http-proxy
    protocol: HTTP
    routes:
    - name: http-backend
      hostnames:
      - "example.com"
      matches:
      - path:
          type: PathPrefix
          value: /
      backends:
      - host: http.example.com:8080
        weight: 1

HTTP routes support various matching options for incoming requests. For more information, see the Request matching guide.

TCP routes

TCP listeners use tcpRoutes instead of routes. TCP routes have a simpler structure than HTTP routes.

Keep in mind that TCP routes do not support HTTP features such as path, header, method, or query matching, and HTTP-specific filters and policies.

Example configuration:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 5432
  listeners:
  - name: postgres-proxy
    protocol: TCP
    tcpRoutes:
    - name: postgres-backend
      backends:
      - host: postgres.example.com:5432
        weight: 1

For more information, see TCP route matching.

Route configuration

Routes are configured within the routes or tcpRoutes section of a listener. The following fields are available for route configuration:

Backend configuration

Routes send traffic to backends, which can be configured with the following fields:

For more advanced backend configurations, such as MCP servers and LLM providers, see the Backends documentation.

Example configuration with policies

The following example shows a route with CORS policy configuration:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
          - "*"
          allowHeaders:
          - mcp-protocol-version
          - content-type
          - cache-control
          exposeHeaders:
          - "Mcp-Session-Id"
      backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

Next steps

After you configure routes, you might want to apply policies to them or learn more about traffic management options.