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 current preview target is v0.8.0-preview.1. Read its
release notes and
upgrade instructions
before evaluation. The download examples below select the stable v0.7.3;
preview assets require their explicit version tag and do not update latest.
For offline configuration inspection and explicit repairs without Admin, see configuration recovery.
Go callers can use the Admin HTTP client at github.com/agent-guide/agent-gateway/pkg/admin/client
(package client, conventionally imported as adminclient).
LLM routes expose registered ProviderModels and LogicalModels through explicit
model_targets. Removed Provider-only targets require offline conversion with
an explicit model allowlist.
Agent budgets are not enforced. Non-null policy.budget values are rejected;
explicitly remove existing budgets before loading the configuration.
Provider deletion requires detaching LLM routes and removing/rebinding its credentials. Its ProviderModels are cleaned up in the same SQLite transaction.
For unconfirmed online writes, inspect GET .../{id}/mutation and use
POST .../{id}/recover; see mutation recovery.
GET /v1/models returns only the selected route’s exposed model names, without upstream discovery or a required default model.
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.3/agent-gateway-first-run-v0.7.3.tar.gz
curl -LO https://github.com/agent-guide/agent-gateway/releases/download/v0.7.3/SHA256SUMSVerify the archive on Linux:
grep 'agent-gateway-first-run-v0.7.3.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.3.tar.gz
cd agent-gateway-first-run-v0.7.3
./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/HTTP API connectors and MCP publishing 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.
Both server modes publish validated route generations; request matching reads an in-memory table without loading configuration storage.
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. In the Go source, pkg/agent/execution
owns common execution contracts and shared controls; pkg/agent/runtimebackend
implements the ACP, builtin, and HTTP backends selected by Agent.runtime.type.
| 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 connector |
- 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: concrete and logical model exposure, 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 explicitly expose ProviderModels (concrete upstream bindings) and
independent LogicalModels (shared candidate selection and fallback) under
route-visible names. Each route uses only one target kind. ProviderModel routes
expose one Provider's real model names; LogicalModel routes support aliases and
cross-provider selection. Every model access resolves an explicitly registered model.
LLM route JSON uses match_policy and a target_policy of type: models;
unknown route fields and unsupported policy types are rejected on writes.
Chat streaming with stream_options.include_usage: true returns a final usage
chunk when the upstream supplies usage.
Manage models through /admin/llm/models/provider and /admin/llm/models/logical,
or Bundle providerModels and logicalModels. See the
model routing guide and
complete example.
LLM routes can be shared by multiple Agents and direct API clients. Builtin
model calls, including custom factory dependencies, retain the executing Agent
identity for usage. /admin/agents/{id}/usage includes builtin turn/resume
statistics alongside attributed LLM tokens and MCP calls; 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.
Responses function namespaces retain distinct tool identities, including same-name
functions in different groups. Responses-via-Chat flattens them with reversible
aliases. Native Responses preserves namespaces by default; native endpoint
providers (openai, grok, codex) accept
options.responses_tool_namespaces: "flatten" for endpoints requiring flat tools.
See namespace compatibility
for supported conversions and explicit rejection boundaries.
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 |
The shared Go Bundle schema, YAML codec, and local validation live in
pkg/gateway/bundle; apply/export execution lives in
pkg/distribution/ctlcmd.
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.
LLM request bodies default to 16 MiB. For larger histories or inline attachments,
set max_llm_request_body_bytes 67108864 inside the Caddy
agent_route_dispatcher block, or run agwd --max-llm-request-body-bytes 67108864
for a 64 MiB limit. Zero selects the default; negative values are rejected.
See request body limits.
- Documentation index
- Getting started
- Task-oriented guides
- API and configuration reference
- Current architecture
- Design decisions and contracts
- Release notes
- Contributor verification
v0.7.3 tightens configuration validation. Before replacing binaries, inspect existing routes and Agents for legacy direct-provider targets, non-null budgets, and ambiguous route matches using the offline recovery tool. Affected configurations require explicit repair and can otherwise prevent startup. Review the upgrade guide for backup, repair and rollback steps, including the external CLI-auth cutover for older stores.
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.
HTTP API tools can be configured without an upstream MCP server. See the
HTTP API connector guide and
connector runtime architecture. MCP ingress
request, cancellation and progress tracking lives in pkg/mcp/tracking; shared
Connector execution contracts live in pkg/connector/runtime. The parallel
pkg/connector/mcp and pkg/connector/httpapi packages own upstream execution;
Connector Manager owns shared admission and configuration changes. Builtin and
custom factory tools use the same generation-bound execution leases. Internal
MCP tool discovery includes every page; external MCP clients control pagination.
Connectors use an immutable id for references and an editable name for display;
changing the display name preserves Agent and route references.
Connector execution edits and deletion require removing Agent and MCP route references and waiting for active/queued work to finish. Display-only edits preserve sessions; disabling and credential revocation remain available. Bundle apply updates resources individually and can partially succeed; it does not provide cross-resource atomic publication or group recovery.