Agents Gateway

📖 Docs & landing page: agentsgateway.dev

A production-ready API gateway for serving AI agents. Built with FastAPI and Agno 2.5.16+.

Features

• Agent Management - Create, configure, and manage AI agents via REST API
• Team Orchestration - Compose agents into teams for multi-agent workflows
• Supervisor Platform - Supervisor/worker execution with job queues, approval flows, and containerized runners (Docker & Kubernetes)
• Skills & Evaluations - Reusable skill definitions and a built-in evaluation framework for agent quality
• Knowledge Base - Store and index documents for agent retrieval (Qdrant)
• Prompts Service - Versioned prompt templates with pluggable storage (PostgreSQL, LangSmith)
• Token Management - Secure OAuth token storage with auto-refresh
• Toolkits - Pre-built integrations for Calendar, Email, Contacts, Drive (Google & Microsoft), plus Claude Code and managed-agent providers
• Observability - Pluggable tracing and logging (OpenTelemetry, Sentry, OTLP)

Quickstart

Prerequisites: Docker Desktop installed and running, Python 3.11+.

1. Clone and start

git clone <repository-url>
cd agents-gateway

# Start PostgreSQL + Qdrant (seeds demo agents automatically)
docker compose up -d

# Set up Python environment
./scripts/dev_setup.sh && source .venv/bin/activate

# Start the API server
./scripts/start_server.sh

2. Explore

# API docs (interactive)
open http://localhost:8000/docs

# List demo agents (no API key needed with AUTH_DISABLED=true)
curl http://localhost:8000/v2/agents

# Get a specific agent
curl http://localhost:8000/v2/agents/demo-assistant

3. Chat with an agent

Set at least one model provider API key, then chat:

export GOOGLE_API_KEY="your-google-api-key"       # Gemini (default)
# export OPENAI_API_KEY="your-openai-api-key"     # OpenAI (GPT)
# export ANTHROPIC_API_KEY="your-anthropic-api-key"  # Anthropic (Claude)

curl -X POST http://localhost:8000/v2/agents/demo-assistant/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What can you help me with?",
    "user_id": "user1",
    "session_id": "session1",
    "timezone": "UTC",
    "locale": "en",
    "stream": false
  }'

Choosing a model

A chat request may name a model; otherwise the gateway uses DEFAULT_CHAT_MODEL
(env), else gemini-3-flash-preview. Besides pinned ids (claude-sonnet-4-6,
gpt-5.4, ...), model accepts a latest-of-a-tier alias that follows the vendor's
newest model in that tier without a code change, and never moves to a pricier tier:

The gateway resolves an alias by listing the vendor's models through its SDK and
taking the newest one in the tier (agents/model_resolver.py), caches the answer
for a day, and falls back to a known model for the tier if the vendor can't be
asked. The resolution is logged (Model alias anthropic:sonnet-latest -> ...).
For example, DEFAULT_CHAT_MODEL=anthropic:sonnet-latest.

4. Stop services

docker compose down        # Keep data
docker compose down -v     # Reset everything

Project Structure

agents-gateway/
├── api/                    # FastAPI application
│   ├── routes/v2/          # V2 API endpoints (agents, teams, knowledge, tokens,
│   │                       #   prompts, skills, approvals, engines, targets)
│   ├── services/           # Shared services (auth, logging, knowledge)
│   └── observability/      # Tracing and logging providers
├── supervisor/             # Supervisor/worker orchestration
│   ├── queue/              # Job queue (producer, consumer, CRUD)
│   ├── pack/               # Agent pack loader/exporter
│   └── plugins/            # Plugin generator
├── remote_agent/           # Containerized worker runner (Docker & K8s runtimes)
├── prompts/                # Prompts service (parser, service, storage backends)
├── toolkits/               # Agno agent toolkits (Calendar, Email, Contacts,
│                           #   Drive, Claude Code, managed agents)
├── workspace_suite/        # Vendor-agnostic workspace integrations (Google, Microsoft)
├── evals/                  # Agent evaluation framework
├── db/                     # Database models and migrations
├── deploy/                 # Deployment manifests (aws, azure, gcp, generic)
└── scripts/                # Development and deployment scripts

API Overview

All endpoints are documented at /docs. Key endpoints:

Authentication

V2 API (/v2/*): API key via X-API-Key header

curl -H "X-API-Key: agw_xxxxx" http://localhost:8000/v2/agents

Admin API (/admin/*): Admin secret via X-Admin-Secret header

curl -H "X-Admin-Secret: your-secret" http://localhost:8000/admin/api-keys

Development: Set AUTH_DISABLED=true to bypass authentication.

Toolkits

The toolkits/ package provides Agno agent toolkits for external service integrations:

All toolkits support:

• Confirmation-based workflow (user reviews before execution)
• OAuth token management with auto-refresh
• Graceful authentication fallback

See toolkits/README.md for detailed documentation.

Development

Setup

# Install uv (package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
./scripts/dev_setup.sh
source .venv/bin/activate

Code Quality

# Run validation (format, lint, type check)
./scripts/run_validate.sh

# Run tests
pytest tests/v2/

Dependencies

# Edit pyproject.toml, then regenerate requirements.txt
./scripts/generate_requirements.sh

# Upgrade all dependencies
./scripts/generate_requirements.sh upgrade

Deployment

One-Click Deploy

Cloud Platforms

Platform-specific deployment manifests and guides live under deploy/:

Environment Variables

* At least one LLM API key is required.

See the Observability section for tracing/logging configuration.

Database Schema

Setup

# Run migrations (auto-runs on first docker compose up)
psql -h $DB_HOST -U $DB_USER -d $DB_DATABASE -f db/migrations/setup.sql

Observability

Pluggable tracing and logging using OpenTelemetry:

Example: Production with Sentry

OTEL_TRACING_BACKEND=sentry
SENTRY_DSN=https://[email protected]/xxx

Example: Cloud-native with OTLP

OTEL_TRACING_BACKEND=otlp
OTEL_LOGGING_BACKEND=otlp
OTEL_OTLP_ENDPOINT=http://collector:4317

Support

• Agno Documentation
• Report an Issue

License

MIT License - see LICENSE for details.