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

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. 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 package directory, update a gateway dependency with:

pip-compile --generate-hashes --no-emit-options --allow-unsafe --upgrade-package <name>==<ver> --output-file requirements-dev.txt requirements-dev.in

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

License

MIT

Metadata

Release files for ai-agent-gateway 0.19.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-agent-gateway 0.19.0
File	Size	Uploaded
ai_agent_gateway-0.19.0.tar.gz	2.4 MB	Sep 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ai-agent-gateway 0.19.0
File	Interpreter	ABI	Platform	Reset
ai_agent_gateway-0.19.0-py3-none-any.whl 2.1 MB Sep 16, 2026	Python 3	none	any	Details

Total release size: 4.5 MB

Release files / ai_agent_gateway-0.19.0.tar.gz

Download URL	ai_agent_gateway-0.19.0.tar.gz
Size	2.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`fdfce4cd6e3810b4b08fb3142794b0d12bfe3831c0fddc338473ea0813a30050`
BLAKE2b-256 checksum How to use checksums	`c2e26ce577b97f24e4cd922e4985d957ed445a87b0be7a989d340e0483bd870b`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.2`

Release files / ai_agent_gateway-0.19.0-py3-none-any.whl

Download URL	ai_agent_gateway-0.19.0-py3-none-any.whl
Size	2.1 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`d98f11a9b95f24af126136a2131af66d74fac32ab481c541e9951d85fd15e029`
BLAKE2b-256 checksum How to use checksums	`91e65b7dd2cef75b5ae23ada8076cd0f14b5087b7e91787edb188535676cd003`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.2`