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
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/SHA256SUMSVerify 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.shA 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.
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.
| 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.
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.
| 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 |
- 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.
LLM routes can be shared by multiple Agents and direct API clients. Builtin model calls retain the executing Agent identity for usage; direct LLM calls without that identity are counted only at route level. Agent entry routes and VirtualKey authorization remain independent. Admin deletion rejects LLM and MCP routes still referenced by an Agent. The check and deletion are serialized with Agent writes, which validate resource route existence and kind.
Provider implementations and protocol fidelity vary by upstream. Check the provider guide, provider option reference, and evaluated capability matrix before choosing a production path.
- 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.
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 buildThe 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 index
- Getting started
- Task-oriented guides
- API and configuration reference
- Current architecture
- Design decisions and contracts
- Release notes
- Contributor verification
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.
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.
Authenticated common HTTP Agent sessions are bound to the VirtualKey, route and runtime definition that created them. A session ID alone grants no continuation access; unknown ownership after restart requires a new conversation.
ACP threads, explicit session continuation, transcripts and pending permission decisions are isolated by authenticated VirtualKey/route/runtime. Session listing retains native pagination and metadata, filtered to proven client ownership. Restart or bounded ownership-cache eviction requires a new client conversation.