Agent Gateway
A FastAPI extension for building API-first AI agent services. Define agents, tools, and skills as markdown files, then serve them as a production-ready API with authentication, persistence, scheduling, notifications, and more.
Quick Start
pip install agents-gateway[all]
# Scaffold a new project
agents-gateway init myproject
cd myproject
# Start the server
agents-gateway serve
Your agent API is now running at http://localhost:8000 with interactive docs at /docs.
Define an Agent
Create a markdown file at workspace/agents/assistant/AGENT.md:
---
description: A helpful assistant that answers questions
skills:
- general-tools
memory:
enabled: true
---
You are a helpful assistant. Answer questions clearly and concisely.
That's it — the agent is now available via the API.
Add a Tool
File-based tool
Create workspace/tools/http-example/TOOL.md:
---
name: http-example
description: Make an HTTP GET request and return the response
parameters:
url:
type: string
description: The URL to fetch
required: true
---
Add a handler in workspace/tools/http-example/handler.py:
import httpx
async def handler(url: str) -> str:
async with httpx.AsyncClient() as client:
resp = await client.get(url)
return resp.text
Code-based tool
Register tools directly in Python:
from agent_gateway import Gateway
gw = Gateway(workspace="./workspace")
@gw.tool(agent="assistant")
def add_numbers(a: float, b: float) -> float:
"""Add two numbers together."""
return a + b
Use the API
# Invoke an agent (single-turn)
curl -X POST http://localhost:8000/v1/agents/assistant/invoke \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{"message": "What is 2 + 3?"}'
# Chat with an agent (multi-turn)
curl -X POST http://localhost:8000/v1/agents/assistant/chat \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{"message": "Hello!"}'
Features
- Markdown-defined agents — Define agents, tools, and skills as markdown files with YAML frontmatter
- Multi-LLM support — Use any model supported by LiteLLM (OpenAI, Gemini, Anthropic, Ollama, etc.)
- Built-in authentication — API key and OAuth2/JWT auth out of the box
- Persistence — SQLite or PostgreSQL storage for conversations, executions, and audit logs
- Dashboard — Built-in web dashboard for monitoring agents, executions, and conversations
- Scheduling — Cron-based agent scheduling via APScheduler
- Notifications — Slack and webhook notification backends with per-agent rules
- Async execution — Queue-based async processing with Redis or RabbitMQ
- Telemetry — OpenTelemetry instrumentation with console or OTLP export
- Structured output — Pydantic model or JSON Schema output validation
- Agent memory — Automatic memory extraction and recall across conversations
- Streaming — Server-sent events (SSE) for real-time chat responses
- Input/output schemas — JSON Schema validation for agent inputs and outputs
- CLI — Project scaffolding, agent listing, and dev server via
agents-gatewayCLI - Lifecycle hooks —
before_invoke,after_invoke,on_errorhooks for custom logic - Sub-app mounting — Mount into an existing FastAPI app with
gw.mount_to(app, path="/ai")— full feature parity
Sub-App Mounting
Mount the gateway into an existing FastAPI app with full feature parity — dashboard, auth, OAuth2, static assets, and all background subsystems work identically:
from fastapi import FastAPI
from agent_gateway import Gateway
app = FastAPI(title="My App")
gw = Gateway(workspace="./workspace")
gw.use_api_keys([{"name": "dev", "key": "secret", "scopes": ["*"]}])
gw.use_dashboard(auth_username="user", auth_password="pass",
admin_username="admin", admin_password="admin")
gw.mount_to(app, path="/ai")
# Your routes at /
# Gateway API at /ai/v1/...
# Dashboard at /ai/dashboard/
See the mounting guide for details.
Configuration
Configure your gateway with workspace/gateway.yaml:
server:
port: 8000
model:
default: "gemini/gemini-2.0-flash"
temperature: 0.1
memory:
enabled: true
Or configure programmatically:
from agent_gateway import Gateway
gw = Gateway(
workspace="./workspace",
title="My Agent Service",
)
# Fluent API for backends
gw.use_api_key_auth(api_key="your-key")
gw.use_sqlite("sqlite+aiosqlite:///data.db")
gw.use_slack_notifications(bot_token="xoxb-...", default_channel="#alerts")
Installation Extras
Install only what you need:
pip install agents-gateway[sqlite] # SQLite persistence
pip install agents-gateway[postgres] # PostgreSQL persistence
pip install agents-gateway[redis] # Redis queue backend
pip install agents-gateway[rabbitmq] # RabbitMQ queue backend
pip install agents-gateway[oauth2] # OAuth2/JWT authentication
pip install agents-gateway[slack] # Slack notifications
pip install agents-gateway[dashboard] # Web dashboard
pip install agents-gateway[otlp] # OTLP telemetry export
pip install agents-gateway[all] # Everything
Documentation
Full documentation is available at vince-nyanga.github.io/agents-gateway.
License
MIT
Metadata
Release files for agents-gateway 0.2.13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agents_gateway-0.2.13.tar.gz | 2.4 MB | Without provenance | Details for agents_gateway-0.2.13.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_gateway-0.2.13-py3-none-any.whl | Python 3 | none | any | Details for agents_gateway-0.2.13-py3-none-any.whl |
Total release size: 3.1 MB
Release files / agents_gateway-0.2.13.tar.gz
| Download URL | agents_gateway-0.2.13.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1af45535fdaaaf0aac1f5e20cd768d9da2ddec03b3a35ebdc4d34f298d305430
|
|
BLAKE2b-256 checksum How to use checksums |
f8420e851f6eea25697c5e3b7e3a9da8feebab21e1dccee53f2ab7eb02d70ba2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / agents_gateway-0.2.13-py3-none-any.whl
| Download URL | agents_gateway-0.2.13-py3-none-any.whl |
|---|---|
| Size | 723.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c49770fbe2a50e521520c62ea094d77cb84929fa56030081e12e2619242c6e8c
|
|
BLAKE2b-256 checksum How to use checksums |
a5099e8ff66b4f201a0bda214010d77fc9ade8c014812ebc264fdc58d130c0eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for agents-gateway 0.2.13
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.