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

Routes

Match HTTP and TCP traffic on a gateway and forward it to backends.

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 attach to gateways 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 gateways 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
gateways:
  http-proxy:
    port: 8080
    protocol: HTTP
routes:
- name: http-backend
  gateways: [http-proxy]
  hostnames:
  - "example.com"
  matches:
  - path:
      pathPrefix: /
  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 gateways 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
gateways:
  postgres-proxy:
    port: 5432
    protocol: TCP
tcpRoutes:
- name: postgres-backend
  gateways: [postgres-proxy]
  backends:
  - host: postgres.example.com:5432
    weight: 1

For more information, see TCP route matching.

Route configuration

Routes are configured in the top-level routes or tcpRoutes section. 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
gateways:
  default:
    port: 3000
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.