ai-agent-gateway
Deploy an AI agent as an HTTP/SSE service without rebuilding session, tool, approval, and execution infrastructure around the model loop. Requires Python 3.10 or newer.
Ownership
This package owns the generic FastAPI chat surface, sessions and JWTs, SSE event stream, provider/run loop, tool dispatch, approvals, code execution, skills, sub-agents, autonomous execution, and heartbeat support.
It does not own an embedding product's profiles, prompts, channel policy,
domain tools, research data, or business schemas. Applications supply those
through create_gateway_app() or the higher-level create_agent() inputs.
The wheel imports without an application checkout. Product integrations bind
policy and identity callbacks plus optional batch/operator-schedule backends in
GatewayServerConfig; schema-backed artifact tools and routes belong to the
embedding application. server_policy is process-scoped: configure it before
building runtimes and use one product policy per gateway process.
Main entrypoints
| Source | Primary symbol | Use it for |
|---|---|---|
agent_gateway/easy.py |
create_agent() |
A small server from a prompt, tools, skills, and provider configuration |
agent_gateway/server.py |
create_gateway_app() |
Product-owned runtime factories, auth, policy, and lifecycle integration |
agent_gateway/gateway_server.py |
run_gateway_server() / main() |
Privileged single-worker TCP launcher, claim-signing fd adoption, and startup-failure logging |
agent_gateway/autonomous.py |
run_autonomous() / run_autonomous_sync() |
A prebound headless one-shot with no HTTP server |
agent_gateway/heartbeat.py |
HeartbeatLoop |
Repeated prebound autonomous work with quiet windows and backoff |
agent_gateway/cli.py |
main() (agent init / agent run) |
Scaffold and run a package project |
agent_gateway/gateway_address.py |
gateway_base_url() |
The origin of the gateway a process talks to: the one reader of GATEWAY_BASE_URL and the one place its default is spelled |
run_gateway_server() is the serving entry on both local supported launches, not
only the privileged host one: the immutable runtime's serving child calls it
directly, so claim-signing adoption, uvicorn.Config/Server construction and
the launch-failure journal have one owner.
The package does not infer a new model or credential inside autonomous
execution. The application resolves and passes the exact bound capability,
session, billing mode, and skill limits before calling run_autonomous().
Quick start
Install a provider extra and set its credential:
pip install "ai-agent-gateway[anthropic]"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export USER_DATA_DIR="$PWD/.agent-data"
mkdir -p "$USER_DATA_DIR/gateway"
chmod 700 "$USER_DATA_DIR" "$USER_DATA_DIR/gateway"
Create and run a project:
agent init my-agent
cd my-agent
agent run
Or create a FastAPI app directly:
from agent_gateway import create_agent
app = create_agent(
"You are a concise research assistant.",
skills_dir="skills",
)
Serve the module with uvicorn agent:app. The default is the stable
session.driver entry in the configured model registry; applications can pass
another eligible stable model_key.
For OpenAI, install ai-agent-gateway[openai] and set OPENAI_API_KEY.
Managed provider login flows are available through agent auth login anthropic, agent auth login codex, and agent auth login xai. Use agent auth status <provider> for all built-ins. agent auth login anthropic is this
gateway's own Claude OAuth login: run it once per Claude account to enroll
interchangeable siblings, then agent auth list anthropic (masked) and agent auth remove anthropic <identity> manage them. Gateway token-store logout
applies to Anthropic and XAI; Codex credentials are managed by the Codex CLI,
and OpenAI uses OPENAI_API_KEY.
The complete session-token, chat request, and SSE walkthrough is in the quickstart.
Request shape
HTTP client
-> create_agent() or create_gateway_app()
-> ChatRuntime
-> AgentRunner.run() (provider stream and model/tool loop)
-> ToolDispatcher.dispatch()
|-- local Python handler
|-- MCP stdio server
|-- approval policy
|-- code execution
`-- run_agent sub-agent
-> EventLog -> SSE response
Headless calls use the same runner, tools, skills, and provider abstractions,
but return RunOutput instead of exposing an HTTP/SSE session.
Develop and verify
From the repository root, update a gateway dependency with the constrained
target (the dev lock is compiled --constraint api/requirements.txt so the two
locks cannot disagree; docs/reference/python-environments-and-packaging.md):
make gateway-deps-update PKG=<name> # then: make gateway-deps-install
For coupled targets, use multiple space-separated --upgrade-package <name>==<ver>
flags. In the monorepo checkout, the shortcut is
make gateway-deps-update PKG='<name>==<ver>' (PKG accepts a space-separated list).
From the package root, run:
pytest tests
The suite and its gateway_test_support/ fixtures are package-local; no embedding
application checkout or product configuration is required. Product integration
scenarios belong in the embedding application's tests, not this package suite.
Use the focused test for the boundary you change. Runnable examples live under
examples/; the production-style assembly example is
examples/07-full-production/, and the
headless fixture is examples/09-autonomous/.
Documentation
- Quickstart
- Architecture
- HTTP and SSE API
- Python API reference
- MCP server configuration
- Framework comparison
- Contributing
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for ai-agent-gateway 0.21.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ai_agent_gateway-0.21.1.tar.gz | 2.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ai_agent_gateway-0.21.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.6 MB
Release files / ai_agent_gateway-0.21.1.tar.gz
| Download URL | ai_agent_gateway-0.21.1.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eb24cc01ba2c7cc01050067e9d9d0b6751f02ff55e956388c4c51225cecfd07d
|
|
BLAKE2b-256 checksum How to use checksums |
4e5163c4563d26339bea27ba79efe3d959eaeb2987bf1e11bedc3cd610bc8654
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
Release files / ai_agent_gateway-0.21.1-py3-none-any.whl
| Download URL | ai_agent_gateway-0.21.1-py3-none-any.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f609482f317e0fe0a0aafa4accabf32dc8004015eb8c978f9d8baee5188a85ac
|
|
BLAKE2b-256 checksum How to use checksums |
abb1b4c8a423966bba675dda8f2ac8a6e5512c217ddf94a39e405cbf0f781101
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.15
|
