Overview

Manage agentgateway through a configuration file. Supported file formats are JSON and YAML.

Configuration sections

Agentgateway configuration has a few top level sections:

config configures top level settings. These options are the only ones that are not dynamically configured.
binds provides the entry point to routing configuration using the traditional listeners, routes, and backends model. For a simplified configuration, use the llm or mcp top-level fields instead.
llm provides a simplified, model-centric configuration for routing requests to LLM providers. For more information, see LLM configuration modes.
mcp provides a simplified configuration for connecting to MCP servers without requiring the full binds routing structure.
services and workloads can be used for very advanced cases where backends need to be represented as complex objects rather than simple URLs. However, it is recommended to use agentgateway on Kubernetes for these purposes.

Example configuration file

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - 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"]

Update configuration

To update configuration, you can write to the configuration file or use the agentgateway UI.

Write to the file: Most changes that you make to the file are automatically picked up by agentgateway, with the exception of the top-level config section.
UI: The agentgateway UI overwrites the contents of the configuration file. Note that any comments that you add to the file are wiped out! You can open the agentgateway UI on port 15000.

Run your configuration

To run agentgateway, install the agentgateway binary and pass the file with the -f option, such as the following example command.

agentgateway -f config.yaml

Configuration overview

Agentgateway’s core configuration is made up of listenersListenerAn entry point for incoming traffic into agentgateway. Listeners are configured on ports and support HTTP, HTTPS, TCP, and TLS protocols., routesRouteA rule that matches incoming requests and forwards them to backends. Routes can match on path, hostname, headers, query parameters, and HTTP methods., and backendsBackendA destination service that receives traffic from agentgateway. Backends can be static hosts, MCP servers, LLM providers, or other services..

Listeners are the main entry point for incoming traffic. For a simple setup, you might have just a single listener. More complex setups might have multiple listeners to serve different ports or domains.
Routes define how incoming traffic is matched and forwarded to backends.
Backends are the targets that receive traffic from agentgateway. Backends can be simple URLs or more complex backends, like an MCP server or LLM providerProviderA service that provides LLM capabilities, such as OpenAI, Anthropic, or Azure. Agentgateway supports multiple LLM providers and can route to different providers based on configuration..

A minimal configuration that accepts HTTP traffic on port 3000 and forwards it to a backend running on localhost:8000 looks like the following example.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - host: localhost:8000

Was this page helpful?