README
¶
Agent Gateway
Run and govern Codex, OpenCode, A2A agents, LLMs, and MCP tools through one self-hosted gateway.
Agent Gateway lets teams expose compatible existing agents as authenticated internal APIs and gives their model and tool traffic the same control point for routing, credentials, limits, configuration, and telemetry. Run Codex or OpenCode through ACP, connect remote A2A Protocol 1.0 agents, host configuration-defined builtin agents, and expose OpenAI-, Anthropic-, Claude Code-, and MCP-compatible endpoints.
agent-gateway is the Apache-2.0 gateway engine behind
AgentGuide. It governs agents from the outside; it
is not an Agent framework or a durable workflow engine.
Website · Documentation · Install · Evaluated capabilities · Releases · Support
Try it without a provider key
The shortest supported evaluation path needs Docker Engine with Compose v2,
curl, and tar. It downloads a checksummed Compose project, starts the
gateway and a deterministic development fixture, applies a Bundle, and sends
governed Agent requests. It needs no repository checkout, local Go toolchain,
or LLM provider credential.
curl -LO https://github.com/agent-guide/agent-gateway/releases/download/v0.7.2/agent-gateway-first-run-v0.7.2.tar.gz
curl -LO https://github.com/agent-guide/agent-gateway/releases/download/v0.7.2/SHA256SUMS
Verify the archive on Linux:
grep 'agent-gateway-first-run-v0.7.2.tar.gz' SHA256SUMS | sha256sum -c -
On macOS, use shasum -a 256 -c - instead of sha256sum -c -. Then start
the project and run the smoke test:
tar -xzf agent-gateway-first-run-v0.7.2.tar.gz
cd agent-gateway-first-run-v0.7.2
./setup.sh
./run-smoke.sh
A successful run ends with:
Common Agent turn, native A2A ingress, VirtualKey enforcement, interaction persistence, and request metrics passed.
This proves:
- rejection of an Agent turn without its VirtualKey;
- a protected common Agent turn over SSE;
- public native A2A Card discovery and governed JSON-RPC ingress;
- persisted interaction lookup; and
- an incremented Prometheus request counter.
Run ./start-observability.sh to add the evaluation-only Prometheus, Tempo,
OpenTelemetry Collector, and Grafana profile. The fixture and anonymous local
Grafana access are for evaluation, not production. See the
first-run guide for prerequisites, reset
commands, and exact boundaries.
Why Agent Gateway
Teams can usually start one Agent. The harder operational problem is giving many users and Agents a shared boundary without losing identity, policy, or evidence as traffic crosses Agent, model, and tool protocols.
| Need | Gateway boundary |
|---|---|
| Expose existing Agents as internal services | Unified AgentRoutes, VirtualKey authentication, streaming turns, cancellation, permissions, sessions, and transcripts where the runtime supports them |
| Govern model and tool access | OpenAI-, Anthropic-, and Claude Code-compatible LLM routes plus managed MCP services and routes |
| Connect remote Agents | Common-turn translation and governed native A2A Protocol 1.0 JSON-RPC ingress |
| Operate one configuration surface | SQLite-backed Admin API, declarative Bundle validate/apply/export, and idempotent updates |
| Inspect what happened | Persisted interactions, per-protocol metrics, Prometheus counters, and optional OpenTelemetry traces |
| Keep the control point private | Self-hosted Caddy-based or standalone runtime with operator-owned storage and deployment authentication |
This focus is intentionally narrower than a general Agent SDK or a hosted AI platform. Agent Gateway supplies the runtime boundary; your applications, Agents, providers, MCP servers, and any durable business workflow engine remain separate systems.
Agent integration paths
| Path | Use it for | What you bring |
|---|---|---|
| ACP | Drive Codex or OpenCode as a protected internal Agent API | An external ACP adapter, workspace, and its upstream authentication |
| HTTP/A2A | Connect an Agent implemented in any stack | A remote A2A Protocol 1.0 Agent Card and service |
| Builtin | Materialize configuration-defined Agents in process | A gateway LLM route, optional managed MCP tools, and a supported eino ADK topology |
Claude Code uses the gateway differently: it is a client of the dedicated cc
Anthropic Messages ingress profile, not an ACP Agent runtime. That profile can
route Claude Code traffic to compatible domestic or international model
providers.
Architecture
The gateway exposes two directions of traffic:
- Agent Control API (Agent / ACP / HTTP / A2A) — consumers launch and drive Agents through protected routes.
- Resource Access API (LLM / MCP) — applications and Agents reach models and tools through governed routes.
A request can enter through an AgentRoute, execute through the selected ACP, builtin, or HTTP runtime, and call back through LLM or MCP routes. VirtualKeys, routing, configuration, and telemetry apply at the relevant boundaries. See the architecture overview for the runtime flow and dependency boundaries.
Choose your starting point
| Goal | Start here | Additional requirement |
|---|---|---|
| Verify a governed Agent request | Provider-key-free first run | Docker Compose only |
| Evaluate Codex or OpenCode | Coding Agent evaluation | External ACP adapter, workspace, and upstream authentication |
| Connect a remote A2A Agent | HTTP Agent quick start | An A2A Protocol 1.0 service, or the local fixture |
| Route OpenAI, Anthropic, or Claude Code traffic | LLM quick start | A compatible provider and credential |
| Govern MCP tools | MCP quick start | A Streamable HTTP or stdio MCP service |
What ships
- Agent runtimes: native ACP pooling and lifecycle management, an in-process eino ADK host for builtin Agents, and HTTP/A2A translation and native ingress.
- Resource gateways: direct-provider or logical-model LLM routing, MCP discovery and execution, credentials, VirtualKeys, and per-domain admission limits.
- Operations: SQLite persistence, Admin APIs, declarative Bundles, durable usage events, interaction views, Prometheus metrics, and optional OTLP export.
- Ingress profiles: OpenAI-compatible, Anthropic Messages, the separate
Claude Code-compatible
ccprofile, MCP, common Agent turns, and A2A Protocol 1.0 JSON-RPC. - Distribution modes:
agwfor the Caddy-based runtime,agwdfor the standalone daemon, andagwctlfor management and validation.
Provider implementations and protocol fidelity vary by upstream. Check the provider guide, provider option reference, and evaluated capability matrix before choosing a production path.
Current boundaries
- The Community limiter is process-local; a production distributed limiter and multi-node HA coordination are not included.
- Memory, durable workflows, schedules, durable human Tasks, enterprise IAM/SSO, organization roles, cost budgets, and a durable compliance audit ledger are not implemented.
- Interactive Agent tool permission decisions are implemented, but they are not a general human-task workflow system.
- ACP execution requires a separately supplied Codex or OpenCode adapter, workspace, and upstream authentication.
- OAuth refresh requires the separately installed
agw-authcommand or a compatible external refresher. - Operational events and traces provide telemetry; they are not a compliance record.
The evaluated capability matrix separates implemented, externally dependent, and roadmap behavior. Roadmap capabilities are not presented as shipped features.
Install and operate
Published release archives support Linux and macOS on amd64 and arm64. The release installation guide covers checksums, container images, runtime identity, persistence, and shutdown behavior.
To build all three binaries from source:
make build
The binaries have separate roles:
| Binary | Role |
|---|---|
agw |
Caddy-based gateway runtime; retains standard Caddy commands such as run, reload, validate, and hash-password |
agwd |
Standalone gateway daemon backed by the shared config store |
agwctl |
Management CLI for Bundle validation/apply/export and Admin operations |
Use the Bundle guide for dynamic configuration,
the Caddyfile reference for the Caddy
runtime, and the runtime modes reference to
choose between agw and agwd.
Documentation
- Documentation index
- Getting started
- Task-oriented guides
- API and configuration reference
- Current architecture
- Design decisions and contracts
- Release notes
- Contributor verification
Upgrading
v0.7.2 adds no protocol or persisted-resource migration beyond v0.7.0. Stores that have not completed the external CLI-auth cutover documented since v0.5.0 need a one-time credential migration and a separately installed refresh command. Do not start an upgrade until you have reviewed the applicable upgrade guide and rollback preparation.
Community and license
Use GitHub Issues for reproducible defects, provider compatibility reports, feature proposals, and documentation gaps. Do not include credentials, private prompts, or private configuration. Report suspected vulnerabilities through the private process in SECURITY.md.
Contributions are welcome; start with CONTRIBUTING.md. Agent Gateway is licensed under Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
caddy
|
|
|
cmd
|
|
|
agw
command
|
|
|
agwctl
command
|
|
|
agwd
command
|
|
|
examples
|
|
|
a2a-agent
command
Command a2a-agent runs the development-only A2A Protocol 1.0 service used by the HTTP Agent quick start and release smoke tests.
|
Command a2a-agent runs the development-only A2A Protocol 1.0 service used by the HTTP Agent quick start and release smoke tests. |
|
internal
|
|
|
distributionmetrics
Package distributionmetrics adapts public entry values to internal usage wiring.
|
Package distributionmetrics adapts public entry values to internal usage wiring. |
|
distributionruntime
Package distributionruntime carries the process-scoped Caddy assembly.
|
Package distributionruntime carries the process-scoped Caddy assembly. |
|
extensionstore
Package extensionstore adapts the existing generic ConfigStore, keeping its implementation types out of the protected extension lifecycle contract.
|
Package extensionstore adapts the existing generic ConfigStore, keeping its implementation types out of the protected extension lifecycle contract. |
|
observability/einotap
Package einotap bridges eino component callbacks into the gateway's usage observability.
|
Package einotap bridges eino component callbacks into the gateway's usage observability. |
|
observability/otelexport
Package otelexport implements the pipeline.OTelExporter seam: it converts gateway usage events into OpenTelemetry spans and ships them to an OTLP collector.
|
Package otelexport implements the pipeline.OTelExporter seam: it converts gateway usage events into OpenTelemetry spans and ships them to an OTLP collector. |
|
pkg
|
|
|
a2a/card
Package card fetches and classifies A2A v1.0 Agent Cards without applying gateway credential policy.
|
Package card fetches and classifies A2A v1.0 Agent Cards without applying gateway credential policy. |
|
a2a/client
Package client wraps the official A2A client with the gateway's fixed JSON-RPC-only transport policy.
|
Package client wraps the official A2A client with the gateway's fixed JSON-RPC-only transport policy. |
|
a2a/jsonrpc
Package jsonrpc defines the A2A v1.0 JSON-RPC wire constants and validation shared by the gateway-owned HTTP guards.
|
Package jsonrpc defines the A2A v1.0 JSON-RPC wire constants and validation shared by the gateway-owned HTTP guards. |
|
a2a/proxy
Package proxy implements the HTTP-terminated, non-translating A2A Path A pipe.
|
Package proxy implements the HTTP-terminated, non-translating A2A Path A pipe. |
|
acp/host
Package host owns the gateway-managed ACP process lifecycle, pooled instances, sessions, permissions, transcripts, and native turn execution.
|
Package host owns the gateway-managed ACP process lifecycle, pooled instances, sessions, permissions, transcripts, and native turn execution. |
|
acp/host/acpupdate
Package acpupdate parses ACP session/update notifications into a small set of neutral events the runtime driver forwards to the gateway north side.
|
Package acpupdate parses ACP session/update notifications into a small set of neutral events the runtime driver forwards to the gateway north side. |
|
acp/hostconfig
Package hostconfig defines the ACP process configuration shared by Agent definitions, runtime adapters, and native agent implementations.
|
Package hostconfig defines the ACP process configuration shared by Agent definitions, runtime adapters, and native agent implementations. |
|
agent
Package agent is the external control-plane layer that composes the gateway's LLM, MCP, ACP, and metrics surfaces around an operator-facing agent identity.
|
Package agent is the external control-plane layer that composes the gateway's LLM, MCP, ACP, and metrics surfaces around an operator-facing agent identity. |
|
agent/builtin
Package builtin is the generic ADK host for builtin-runtime agents: the gateway ships this one host compiled into agw/agwd, and a builtin agent is a persisted definition (agent.BuiltinRuntime) that the host materializes into an eino ADK object graph on demand.
|
Package builtin is the generic ADK host for builtin-runtime agents: the gateway ships this one host compiled into agw/agwd, and a builtin agent is a persisted definition (agent.BuiltinRuntime) that the host materializes into an eino ADK object graph on demand. |
|
agent/runtime
Package runtime defines the runtime-neutral execution boundary for operator-facing Agents.
|
Package runtime defines the runtime-neutral execution boundary for operator-facing Agents. |
|
agent/runtime/runtimetest
Package runtimetest provides reusable fake runtime backends for dispatcher and Admin contract tests.
|
Package runtimetest provides reusable fake runtime backends for dispatcher and Admin contract tests. |
|
attribution
Package attribution transports bounded trusted identity and runtime correlation.
|
Package attribution transports bounded trusted identity and runtime correlation. |
|
dispatcher/llmapi/anthropic
Package anthropic provides the standard Anthropic Messages HTTP profile.
|
Package anthropic provides the standard Anthropic Messages HTTP profile. |
|
dispatcher/llmapi/cc
Package cc provides the Claude Code CLI LLM API profile.
|
Package cc provides the Claude Code CLI LLM API profile. |
|
distribution
Package distribution supplies public value options for reusable binary entries.
|
Package distribution supplies public value options for reusable binary entries. |
|
distribution/caddycmd
Package caddycmd adapts the upstream Caddy process entry.
|
Package caddycmd adapts the upstream Caddy process entry. |
|
distribution/contracttest
Package contracttest exercises independently built distribution binaries.
|
Package contracttest exercises independently built distribution binaries. |
|
distribution/ctlcmd
Package ctlcmd constructs management CLI commands without import-time process side effects.
|
Package ctlcmd constructs management CLI commands without import-time process side effects. |
|
distribution/daemoncmd
Package daemoncmd constructs standalone daemon commands.
|
Package daemoncmd constructs standalone daemon commands. |
|
event
Package event defines sanitized v1 DTOs and bounded sink transport.
|
Package event defines sanitized v1 DTOs and bounded sink transport. |
|
extension
Package extension implements an explicit, immutable linked registry and reference-preserving module configuration.
|
Package extension implements an explicit, immutable linked registry and reference-preserving module configuration. |
|
extension/contracttest
Package contracttest supplies reusable candidate extension contract suites.
|
Package contracttest supplies reusable candidate extension contract suites. |
|
gateway/agentroute
Package agentroute defines the unified Agent ingress route model described by docs/design/agents-control-plane.md.
|
Package agentroute defines the unified Agent ingress route model described by docs/design/agents-control-plane.md. |
|
gateway/virtualkey/limiter
Package limiter owns the designated protected VirtualKey admission SPI.
|
Package limiter owns the designated protected VirtualKey admission SPI. |
|
gateway/virtualkey/limiter/contracttest
Package contracttest provides reusable protected limiter conformance suites.
|
Package contracttest provides reusable protected limiter conformance suites. |
|
llm/provider/anthropic
Package anthropic implements the Anthropic provider (Claude models).
|
Package anthropic implements the Anthropic provider (Claude models). |
|
llm/provider/anthropicbase
Package anthropicbase provides shared Anthropic Messages API wire helpers.
|
Package anthropicbase provides shared Anthropic Messages API wire helpers. |
|
llm/provider/deepseek
Package deepseek implements the DeepSeek provider.
|
Package deepseek implements the DeepSeek provider. |
|
llm/provider/einomodel
Package einomodel presents a gateway provider as an eino model.ToolCallingChatModel, so eino agents, ADK runners, and compose graphs can consume gateway-routed models directly.
|
Package einomodel presents a gateway provider as an eino model.ToolCallingChatModel, so eino agents, ADK runners, and compose graphs can consume gateway-routed models directly. |
|
llm/provider/gemini
Package gemini implements the Google Gemini provider.
|
Package gemini implements the Google Gemini provider. |
|
llm/provider/grok
Package grok implements the xAI Grok provider (OpenAI-compatible API) on top of the eino-ext openai component.
|
Package grok implements the xAI Grok provider (OpenAI-compatible API) on top of the eino-ext openai component. |
|
llm/provider/ollama
Package ollama implements the Ollama provider (local deployment, OpenAI-compatible).
|
Package ollama implements the Ollama provider (local deployment, OpenAI-compatible). |
|
llm/provider/openai
Package openai implements the OpenAI provider.
|
Package openai implements the OpenAI provider. |
|
llm/provider/openaibase
Package openaibase provides shared OpenAI-compatible wire types still used for model listing and embeddings.
|
Package openaibase provides shared OpenAI-compatible wire types still used for model listing and embeddings. |
|
llm/provider/openrouter
Package openrouter implements the OpenRouter provider (OpenAI-compatible API).
|
Package openrouter implements the OpenRouter provider (OpenAI-compatible API). |
|
llm/provider/qwen
Package qwen implements the Alibaba Qwen provider (DashScope OpenAI-compatible mode) on top of the eino-ext qwen component.
|
Package qwen implements the Alibaba Qwen provider (DashScope OpenAI-compatible mode) on top of the eino-ext qwen component. |
|
llm/provider/zhipu
Package zhipu implements the Zhipu BigModel provider.
|
Package zhipu implements the Zhipu BigModel provider. |
|
mcp/einotool
Package einotool adapts gateway-managed MCP services (pkg/mcp/service) to eino tools, so gateway-governed MCP tools are directly consumable by in-process eino agents and graphs without an HTTP loopback.
|
Package einotool adapts gateway-managed MCP services (pkg/mcp/service) to eino tools, so gateway-governed MCP tools are directly consumable by in-process eino agents and graphs without an HTTP loopback. |
|
scripts
|
|
|
migrate-unified-agent-runtime-go
command
|
|
|
standalone
|
|