Tool Gateway agentgateway Operator Reference

This reference covers agentgateway-specific implementation details of the Tool Gateway agentgateway Operator. For the ToolGateway, ToolGatewayClass, ToolRoute, and ToolServer CRD field tables, see ToolGateway and ToolGatewayClass Reference and ToolRoute Reference.

ToolGatewayClass controller name

The operator registers one ToolGatewayClass with the following controller name:

Item Value

ToolGatewayClass name

agentgateway

spec.controller

runtime.agentic-layer.ai/tool-gateway-agentgateway-controller

A ToolGateway resource with spec.toolGatewayClassName: agentgateway is claimed and reconciled by this operator.

Marking the ToolGatewayClass as default

The shipped agentgateway ToolGatewayClass is not marked as the cluster default. To claim ToolGateway resources that omit spec.toolGatewayClassName, add the toolgatewayclass.kubernetes.io/is-default-class: "true" annotation via a Kustomize overlay:

# kustomization.yaml
resources:
  - https://github.com/agentic-layer/tool-gateway-agentgateway/releases/latest/download/install.yaml
patches:
  - patch: |-
      apiVersion: runtime.agentic-layer.ai/v1alpha1
      kind: ToolGatewayClass
      metadata:
        name: agentgateway
        annotations:
          toolgatewayclass.kubernetes.io/is-default-class: "true"

Use this only when this operator is the single Tool Gateway implementation in the cluster.

Generated Gateway API resources

For each reconciled ToolGateway, the operator creates and owns the following Gateway API resources in the same namespace:

Resource Description

Gateway

A Gateway API Gateway with the same name as the ToolGateway. Configured with an HTTP listener on port 80 that accepts routes from all namespaces. The spec.infrastructure.parametersRef points at the operator-owned AgentgatewayParameters resource.

AgentgatewayParameters

Holds agentgateway-specific configuration generated from ToolGateway.spec.env and ToolGateway.spec.envFrom, including translated OTEL telemetry settings.

For each reconciled ToolRoute, the operator creates:

Resource Description

AgentgatewayBackend

Configures the MCP backend connection to the route’s upstream (a cluster ToolServer service or external URL).

HTTPRoute

Routes traffic from the referenced ToolGateway’s `Gateway to the AgentgatewayBackend at the path /<toolroute-namespace>/<toolroute-name>/mcp.

AgentgatewayPolicy (optional)

Created only when spec.toolFilter is set. Carries MCP authorization CEL rules translated from the glob allow/deny patterns and is attached to the route’s HTTPRoute.

ToolGateway status URL

When the operator successfully reconciles a ToolGateway, it sets:

ToolGateway.status.url = http://<name>.<namespace>.svc.cluster.local

This is the cluster-local base URL for the agentgateway instance. Individual tool routes are reachable at <status.url>/<route-namespace>/<route-name>/mcp. The ToolRoute.status.url field is populated by the operator with this per-route URL once the route is accepted.

OTEL environment variables

The operator automatically translates standard OpenTelemetry environment variables from ToolGateway.spec.env to agentgateway’s rawConfig.config.tracing section. These variables are not passed as environment variables to the agentgateway container.

Variable Effect

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP exporter endpoint URL.

OTEL_EXPORTER_OTLP_PROTOCOL

Protocol to use: http/protobuf, grpc, or http/json.

OTEL_EXPORTER_OTLP_HEADERS

Headers to send with telemetry data (e.g. api-key=secret123).

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

Per-signal override for the traces endpoint.

OTEL_EXPORTER_OTLP_TRACES_PROTOCOL

Per-signal override for the traces protocol.

OTEL_EXPORTER_OTLP_TRACES_HEADERS

Per-signal override for the traces headers.
Currently only tracing is supported. Metrics and logs configuration is not yet implemented.

For the full agentgateway configuration schema, see the agentgateway config schema.

Tool filtering: glob to CEL translation

When ToolRoute.spec.toolFilter is set, the operator translates the glob allow/deny patterns into CEL rules written to AgentgatewayPolicy.spec.backend.mcp.authorization.policy.matchExpressions.

Semantics

Condition Behaviour

toolFilter is nil

All tools pass through unfiltered; no AgentgatewayPolicy is created.

Only allow is set

Only tools matching an allow pattern are exposed.

Only deny is set

All tools are exposed except those matching a deny pattern.

Both allow and deny are set

Deny wins on conflict — a tool matching any deny pattern is always blocked, even if it also matches an allow pattern. The generated CEL expression is (<allow-predicates>) && !(<deny-predicates>).

Pattern syntax

Glob patterns use standard syntax: * matches any run of characters; ? matches exactly one character. Plain names (no wildcard characters) compile to a CEL equality check; patterns with wildcards compile to a mcp.tool.name.matches(regex) call against an anchored regular expression.

Pattern Generated CEL predicate

get_issue

mcp.tool.name == "get_issue"

get_*

mcp.tool.name.matches("^get_.*$")

delete

mcp.tool.name.matches("^.*delete.*$")

list_?

mcp.tool.name.matches("^list_.$")

Guardrails

The operator can attach guardrails to a ToolGateway to filter sensitive content (PII, harmful content) from tool traffic. Guardrails are expressed with the gateway-agnostic Guard and GuardrailProvider CRDs documented in Guardrails Reference; this section covers the agentgateway-specific behaviour.

For each Guard referenced from ToolGateway.spec.guardrails, the operator automatically creates a dedicated guardrail-adapter workload (Deployment + ConfigMap + Service) pre-configured from the Guard and its GuardrailProvider. No manual adapter deployment is required. The gateway’s AgentgatewayPolicy extProc.backendRef is wired at the adapter’s service automatically.

Prerequisites

  1. The operator must be started with --guardrail-adapter-image=<image>:<tag>. See Enable Guardrails in the install guide.

  2. A GuardrailProvider backing service (e.g. Presidio) must be reachable from the cluster.

Example: PII detection with Presidio

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: GuardrailProvider
metadata:
  name: presidio-analyzer
  namespace: default
spec:
  type: presidio-api
  presidio:
    baseUrl: http://presidio-analyzer.default.svc:8080
---
apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: Guard
metadata:
  name: pii-guard
  namespace: default
spec:
  mode:
    - pre_call
    - post_call
  description: "Detects and masks PII in tool traffic"
  providerRef:
    name: presidio-analyzer
  presidio:
    language: "en"
    scoreThresholds:
      ALL: "0.5"
      PERSON: "0.8"
      EMAIL_ADDRESS: "0.7"
    entityActions:
      PERSON: "MASK"
      EMAIL_ADDRESS: "MASK"
      CREDIT_CARD: "BLOCK"
      PHONE_NUMBER: "MASK"
---
apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolGateway
metadata:
  name: my-tool-gateway
  namespace: default
spec:
  toolGatewayClassName: agentgateway
  guardrails:
    - name: pii-guard

The operator creates pii-guard-adapter (Deployment + ConfigMap + Service) in the Guard’s namespace and wires the ToolGateway’s `AgentgatewayPolicy extProc.backendRef at it.

A complete sample (Presidio + Guard + ToolGateway + ToolServer + ToolRoute) is available at https://github.com/agentic-layer/tool-gateway-agentgateway/tree/main/config/samples/guardrails. Apply it with kubectl apply -k config/samples/guardrails.

Limitations

  • Single Guard per ToolGateway: agentgateway currently supports only one ext_proc slot per target. If you reference multiple guards, the operator sets a GuardrailsUnsupported status condition on the ToolGateway.

  • Provider type: Only presidio-api providers are supported today. Guards backed by openai-moderation-api or bedrock-api providers report Ready=False with reason UnsupportedProviderType.

Status conditions

Resource Condition Reason Meaning

Guard

Ready=False

AdapterNotConfigured

Operator was started without --guardrail-adapter-image.

Guard

Ready=False

ProviderNotFound

providerRef does not resolve.

Guard

Ready=False

UnsupportedProviderType

Only presidio-api is supported today.

Guard

Ready=False

InvalidConfig

Validation failed (missing endpoint, empty modes, …​).

ToolGateway

Ready=False

GuardNotFound

A referenced Guard does not exist.

ToolGateway

Ready=False

GuardNotReady

A referenced Guard exists but its Ready condition is False.

ToolGateway

Ready=False

GuardrailsUnsupported

More than one Guard was referenced.

Related