Define a ToolRoute

This guide shows you how to create a ToolRoute resource that exposes a tool server through a ToolGateway, and how to reference it from an Agent.

Prerequisites

  • Agent Runtime Operator installed — see Install the Agent Runtime Operator.

  • A ToolGateway available in the cluster (provided by a tool-gateway operator implementation).

Define a ToolRoute against a cluster ToolServer

Use spec.upstream.toolServerRef to expose a ToolServer that is already running in the cluster:

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolRoute
metadata:
  name: context7-route
  namespace: tools
spec:
  toolGatewayRef:
    name: tool-gateway
  upstream:
    toolServerRef:
      name: context7-toolserver
kubectl apply -f context7-route.yaml

The gateway implementation operator reconciles the route and populates status.url once the route is ready.

Define a ToolRoute against an external URL

Use spec.upstream.external.url to expose an MCP server that runs outside the cluster:

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolRoute
metadata:
  name: github-external-route
  namespace: tools
spec:
  toolGatewayRef:
    name: tool-gateway
  upstream:
    external:
      url: https://github-mcp.example.com/mcp
kubectl apply -f github-external-route.yaml

Apply tool filters

Add spec.toolFilter to restrict which tools the route exposes. allow defines the candidate set; deny is applied after allow and wins on conflict. Both fields accept glob patterns (* matches any run of characters, ? matches exactly one).

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolRoute
metadata:
  name: github-readonly
  namespace: tools
spec:
  toolGatewayRef:
    name: tool-gateway
  upstream:
    toolServerRef:
      name: github-mcp
  toolFilter:
    allow: [search_issues, "get_*", "list_*"]
    deny:  ["*delete*", force_push]

When allow is omitted or empty, all tools from the upstream are candidates.

Reference a ToolRoute from an Agent

Once the route is ready, reference it from an Agent via spec.tools[].upstream.toolRouteRef. The agent framework receives the gateway URL from status.url at reconcile time.

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: Agent
metadata:
  name: coding-assistant
spec:
  framework: google-adk
  tools:
    - name: context7_tools
      upstream:
        toolRouteRef:
          name: context7-route
          namespace: tools
  protocols:
    - type: A2A
  replicas: 1
  env:
    - name: GEMINI_API_KEY
      value: "your-gemini-api-key-here"
kubectl apply -f coding-assistant.yaml

Verify

# Check that the route was accepted and its URL is populated
kubectl get toolroute context7-route -n tools

# Confirm the agent is running
kubectl get agent coding-assistant
kubectl get deployment coding-assistant

The route is ready when status.url is non-empty and the Ready condition is True.

Related