Route delegation

Verified : Code examples on this page have been automatically tested and verified.

Delegate routing decisions to route groups for independent team management.

Delegate routing decisions from a parent route to a set of child routes defined in a route group. Route delegation lets you break up large routing configurations into smaller, independently managed pieces.

About

As your gateway manages traffic for more routes, managing all routing rules in a single configuration becomes difficult. Route delegation lets you split routing configurations so that different teams can own their routes independently.

In standalone mode, route delegation uses route groups. A parent route references a route group as its backend, and the route group contains child routes that handle more specific paths within the parent’s prefix.

Element	Description
Parent route	A route defined on a listener. Instead of routing directly to a backend, it references a `routeGroup` in its `backends` list. The parent must use a `pathPrefix` matcher.
Route group	Defined at the top level under `routeGroups`. Contains a `name` and a list of child `routes`.
Child route	A route inside a route group. Uses the same matching logic as regular routes (path, headers, query parameters). The child’s path must fall within the parent’s prefix to be reachable.

Example request flow

Request: /anything/team1/foo
         |
         v
   Parent Route (matches /anything/team1)
         |
         | delegates to routeGroup: team1-routes
         v
   Route Group "team1-routes"
         |
         | selects best matching child route
         v
   Child Route "child-foo" (matches /anything/team1/foo)
         |
         v
   Backend: team1-foo.example.com:8080

More details

Review more details about how route delegation works in standalone mode.

Area	Description
Parent path matcher	A parent route that delegates to a route group must use a `pathPrefix` matcher.
Child path scope	Child routes must match a path that falls within the parent’s prefix. For example, if the parent matches `/api`, a child must match a path starting with `/api`.
Cyclic delegation	Agentgateway does not allow cyclic delegation. If route group A delegates to B, and B delegates back to A, agentgateway detects the cycle at runtime and returns a `500` response. See Error responses.
Missing route group	If a route references a `routeGroup` that does not exist, agentgateway returns a `404` response for that route, the same as a path with no match. See Error responses.

Before you begin

Install the agentgateway binary.

Basic delegation

Delegate traffic from a parent route to a route group with two child routes.

In this example, a parent route matches the /anything/team1 prefix and delegates to a route group called team1-routes. The route group contains two child routes: child-foo matches /anything/team1/foo and child-bar matches /anything/team1/bar.

Create the configuration file.

cat > config.yaml <<'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    protocol: HTTP
routes:
- name: parent-team1
  matches:
  - path:
      pathPrefix: /anything/team1
  backends:
  - routeGroup: team1-routes

routeGroups:
- name: team1-routes
  routes:
  - name: child-foo
    matches:
    - path:
        pathPrefix: /anything/team1/foo
    backends:
    - host: team1-foo.example.com:8080
  - name: child-bar
    matches:
    - path:
        pathPrefix: /anything/team1/bar
    backends:
    - host: team1-bar.example.com:8080
EOF

Run the gateway.
```
agentgateway -f config.yaml
```

Test the routes.

# Matches parent -> delegates to team1-routes -> matches child-foo
curl -i 127.0.0.1:3000/anything/team1/foo

# Matches parent -> delegates to team1-routes -> matches child-bar
curl -i 127.0.0.1:3000/anything/team1/bar

# Matches parent prefix, but no child route matches -> 404
curl -i 127.0.0.1:3000/anything/team1/other

# Does not match parent prefix -> 404
curl -i 127.0.0.1:3000/other

Header and query matching

Parent routes can include header and query parameter matchers that control which requests are delegated. Child routes can independently define their own matchers. A request must satisfy both the parent’s and the child’s matchers to reach a backend.

In this example, a parent route matches /anything/team1 only when the x-team header and env query parameter are present. The route group has two child routes:

child-foo adds its own header matcher (x-role) beyond what the parent requires. A request must include both the parent’s and child’s matchers to reach the backend.
child-bar matches on path only, with no additional header or query parameter matchers. Any request that the parent delegates is routed if the path matches.

Create the configuration file.

cat > config.yaml <<'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    protocol: HTTP
routes:
- name: parent-team1
  matches:
  - path:
      pathPrefix: /anything/team1
    headers:
    - name: x-team
      value:
        exact: team1
    query:
    - name: env
      value:
        exact: prod
  backends:
  - routeGroup: team1-routes

routeGroups:
- name: team1-routes
  routes:
  - name: child-foo
    matches:
    - path:
        pathPrefix: /anything/team1/foo
      headers:
      - name: x-role
        value:
          exact: admin
    backends:
    - host: team1-foo.example.com:8080
  - name: child-bar
    matches:
    - path:
        pathPrefix: /anything/team1/bar
    backends:
    - host: team1-bar.example.com:8080
EOF

Run the gateway.
```
agentgateway -f config.yaml
```

Test the routes.

# child-foo: parent matchers + child's x-role header -> routed to child-foo
curl -i "127.0.0.1:3000/anything/team1/foo?env=prod" \
  -H "x-team: team1" -H "x-role: admin"

# child-foo: parent matchers only, missing child's x-role -> 404
curl -i "127.0.0.1:3000/anything/team1/foo?env=prod" \
  -H "x-team: team1"

# child-bar: parent matchers, child matches on path only -> routed to child-bar
curl -i "127.0.0.1:3000/anything/team1/bar?env=prod" \
  -H "x-team: team1"

# child-bar: missing parent matchers, not delegated -> 404
curl -i 127.0.0.1:3000/anything/team1/bar

The backend hosts in these examples are placeholders, so a request that is routed to a child returns 503 instead of a response from the backend. The 404 responses are the ones that show a request was not delegated.

Multi-level delegation

Child routes inside a route group can delegate to other route groups, creating a multi-level delegation hierarchy. Agentgateway detects cycles at runtime and returns an error if a delegation chain loops back to a previously visited route group.

In this example, a parent route delegates /api to a route group. One child handles /api/users directly, while another child delegates /api/orders to a second route group with more specific routes.

Create the configuration file.

cat > config.yaml <<'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    protocol: HTTP
routes:
- name: parent-api
  matches:
  - path:
      pathPrefix: /api
  backends:
  - routeGroup: api-routes

routeGroups:
- name: api-routes
  routes:
  - name: child-users
    matches:
    - path:
        pathPrefix: /api/users
    backends:
    - host: users-service.example.com:8080
  - name: child-orders
    matches:
    - path:
        pathPrefix: /api/orders
    backends:
    - routeGroup: orders-routes
- name: orders-routes
  routes:
  - name: grandchild-list
    matches:
    - path:
        pathPrefix: /api/orders/list
    backends:
    - host: orders-list.example.com:8080
  - name: grandchild-detail
    matches:
    - path:
        pathPrefix: /api/orders/detail
    backends:
    - host: orders-detail.example.com:8080
EOF

Run the gateway.
```
agentgateway -f config.yaml
```

Test the routes.

# Parent -> api-routes -> child-users (direct backend)
curl -i 127.0.0.1:3000/api/users

# Parent -> api-routes -> child-orders -> orders-routes -> grandchild-list
curl -i 127.0.0.1:3000/api/orders/list

# Parent -> api-routes -> child-orders -> orders-routes -> grandchild-detail
curl -i 127.0.0.1:3000/api/orders/detail

# Matches child-orders prefix, but no grandchild matches -> 404
curl -i 127.0.0.1:3000/api/orders/other

Policy inheritance

Policies defined on a parent route are inherited by child routes in the delegation chain. If a child route defines the same type of policy, the child’s policy takes precedence.

In this example, a parent route sets a requestHeaderModifier policy that adds an x-parent header to all requests. One child route inherits this policy, while the other overrides it with its own requestHeaderModifier that adds a different header instead.

Create the configuration file.

cat > config.yaml <<'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    protocol: HTTP
routes:
- name: parent-team1
  matches:
  - path:
      pathPrefix: /anything/team1
  policies:
    requestHeaderModifier:
      add:
        x-parent: from-parent
  backends:
  - routeGroup: team1-routes

routeGroups:
- name: team1-routes
  routes:
  - name: child-inherits
    matches:
    - path:
        pathPrefix: /anything/team1/foo
    backends:
    - host: team1-foo.example.com:8080
  - name: child-overrides
    matches:
    - path:
        pathPrefix: /anything/team1/bar
    policies:
      requestHeaderModifier:
        add:
          x-child: from-child
    backends:
    - host: team1-bar.example.com:8080
EOF

Run the gateway.
```
agentgateway -f config.yaml
```

Test the routes.

# child-inherits: receives x-parent header from parent policy
curl -i 127.0.0.1:3000/anything/team1/foo

# child-overrides: receives x-child header; parent's requestHeaderModifier is overridden
curl -i 127.0.0.1:3000/anything/team1/bar

Error responses

Two invalid delegation configurations produce specific error responses, rather than being rejected at validation time.

Cyclic delegation

Agentgateway does not allow cyclic delegation. If route group A delegates to B, and B delegates back to A, agentgateway detects the cycle at runtime and returns a 500 response. The cycle is not caught by --validate-only, because static validation does not follow routeGroup references.

Create the configuration file.

cat > config-cycle.yaml <<'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    protocol: HTTP
routes:
- name: parent-a
  matches:
  - path:
      pathPrefix: /a
  backends:
  - routeGroup: group-a

routeGroups:
- name: group-a
  routes:
  - name: to-b
    matches:
    - path:
        pathPrefix: /a
    backends:
    - routeGroup: group-b
- name: group-b
  routes:
  - name: to-a
    matches:
    - path:
        pathPrefix: /a
    backends:
    - routeGroup: group-a
EOF

Run the gateway.
```
agentgateway -f config-cycle.yaml
```

Test the route.

# group-a -> group-b -> group-a is a cycle -> 500
curl -i 127.0.0.1:3000/a

Missing route group

If a route references a routeGroup that does not exist, agentgateway returns a 404 response for that route, the same as a path with no match.

Create the configuration file.

cat > config-missing-group.yaml <<'EOF'
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
    protocol: HTTP
routes:
- name: parent-missing
  matches:
  - path:
      pathPrefix: /missing
  backends:
  - routeGroup: does-not-exist
EOF

Run the gateway.

agentgateway -f config-missing-group.yaml

Test the route.

# does-not-exist is not a defined routeGroup -> 404
curl -i 127.0.0.1:3000/missing

Direct Response External processing (ExtProc)

Was this page helpful?

Route delegation

About

Example request flow

More details

Before you begin

Basic delegation

Header and query matching

Multi-level delegation

Policy inheritance

Error responses

Cyclic delegation

Missing route group

What could be improved?