Routes

Documentation

Configuration

Routes

Routes are the entry points for traffic to your agentgateway. They are configured on listeners and are used to route traffic to backends.

You can use the built-in agentgateway UI or a configuration file to create, update, and delete routes.

Types of routes

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

HTTP routes

HTTP or TLS listeners use routes to configure HTTP routes. HTTP routes support all HTTP features such as path, header, method, or query matching, and HTTP-specific filters and policies.

Example configuration:

binds:
- port: 8080
  listeners:
  - name: http-proxy
    protocol: HTTP
    routes:
    - name: http-backend
      backends:
      - host: http.example.com:8080
        weight: 1

For more information, continue to the Create routes section.

TCP routes

TCP listeners use tcpRoutes instead of routes. TCP routes have a simpler structure than other 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:

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.

Before you begin

Create routes

Set up a route on your listener.

Start your agentgateway.
```
agentgateway 
```
Open the agentgateway route UI.
Click Add Route and configure a route such as follows:
- Name: An optional name for the route.
- Rule Name: An optional name for the matching rules of the route.
- Target Listener: Select the listener that you previously created. The Route Type is automatically determined based on the listener protocol.
- Hostnames: Add the hostnames that the route serves traffic on.
- Path Match Type: Select the type of path matching that you want to use, such as Path Prefix, and then configure its details. For more options, see the Request matching guide.
- Headers: Optional header configuration, such as the authorization header.
- HTTP Methods: Optional HTTP methods to allow, such as GET, POST, PUT.
- Query Parameters: Optional query parameters to allow, such as version=v1.
- Click Add HTTP Route to continue.

Download a configuration file that contains your route configuration.

curl -L https://raw.githubusercontent.com/agentgateway/agentgateway/refs/heads/main/examples/basic/config.yaml -o config.yaml

Review the configuration file. The example sets up an HTTP listener on port 3000 that matches on all hosts. For more options, see the Request matching guide.

cat config.yaml

config.yaml

binds:
- port: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
            - "*"
          allowHeaders:
            - mcp-protocol-version
            - content-type
            - cache-control
      backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

Run the agentgateway.
```
agentgateway -f config.yaml
```
Open the agentgateway listener UI and verify that your route is added successfully.

Delete routes

Remove agentgateway routes by using the UI or deleting the configuration file.

Remove agentgateway routes with the UI.

Run the agentgateway from which you want to remove a route.
```
agentgateway -f config.yaml
```
Open the agentgateway route UI and find the route that you want to remove.
Click the trash icon to remove the route.

Update the configuration file to remove the route.

Remove the route from your configuration file.
Apply the updated configuration file to your agentgateway.
```
agentgateway -f config.yaml
```

Next steps

After you create routes, you might want to apply policies to them.

Request matching Traffic management Resiliency Security

Backends Traffic management