HiveGate

Run your Agno agents as a production API.

HiveGate is an open-source FastAPI service built on Agno 3. You write the agent, and HiveGate gives it what production needs:

• per-user sessions
• OAuth tokens for Google and Microsoft
• human approval for risky tool calls
• multi-agent teams with a supervisor
• versioned prompts
• token usage and cost metering
• tracing

Website · Docs · Deploy guide · Discussions · Roadmap

uv tool install hivegate-ai   # or: pipx install hivegate-ai
mkdir my-agents && cd my-agents
hivegate init              # writes compose.yaml and a local .env; then set GOOGLE_API_KEY in .env
docker compose up -d       # Postgres + Qdrant, seeds demo agents
hivegate serve             # http://127.0.0.1:8000/docs

Install it as a tool rather than into a project's environment: the package's top-level modules have generic names (api, agents, db) that can clash with other libraries.

To upgrade, run uv tool upgrade hivegate-ai, then hivegate migrate. To work on HiveGate itself, see the Quickstart, which runs from a clone.

For container workers, install the extra you need: uv tool install "hivegate-ai[docker]" or "hivegate-ai[kubernetes]".

Or deploy the prebuilt image in one click:

HiveGate is not a request-routing API gateway like Kong. It runs AI agents and exposes them over a REST API.

Why HiveGate, and when you don't need it

Agno gives you the agent itself: model calls, tools, memory and teams. Its own AgentOS can also serve agents over HTTP, with sessions, human approval, RBAC and tracing. If your agents are defined in code and AgentOS covers what you need, use AgentOS.

HiveGate is for when your agents act for your users, in their own accounts, and are managed as data rather than code:

• Per-user OAuth tokens. Store each user's Google or Microsoft tokens once. HiveGate refreshes them, and the Gmail, Calendar, Contacts and Drive toolkits act as that user.
• Approval before risky actions. A tool call such as sending an email pauses the run until someone approves or denies it through the API.
• Agents, prompts and skills as data. Create and version them through the REST API, with no redeploy.
• Per-tenant knowledge. Documents are kept per tenant and per collection in Qdrant.
• Supervisor teams with container workers. Jobs run in Docker or Kubernetes, including Claude Code and managed-agent workers.
• A ready-to-deploy service. A prebuilt image with one-click deploys to Render, Railway and Koyeb, plus Kubernetes and cloud manifests.

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
• Usage & Cost Metering - Every model call recorded with its tokens and USD cost, queryable through the /usage API
• Prompt Caching - Claude models cache tools, the system prompt and the conversation, so repeat input bills at a fraction of the price
• Observability - Pluggable tracing and logging (OpenTelemetry, Sentry, OTLP)

Quickstart

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

1. Clone and configure

git clone https://github.com/hivegate-ai/hivegate
cd hivegate
cp .env.example .env

Edit .env before starting the server. The server reads it once at startup, so a key exported in another terminal won't reach it.

• Set at least one model provider key. The demo agents use Gemini by default, so set GOOGLE_API_KEY. OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, ZAI_API_KEY and DEEPSEEK_API_KEY also work.
• For local use, uncomment AUTH_DISABLED=true so you can call the API without creating an API key first. Never enable it on a deployment other people can reach.

The database settings in .env.example already match the Postgres that Docker Compose starts.

2. Start

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

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

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

3. Explore

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

# List demo agents (works without an API key because of AUTH_DISABLED=true)
curl http://localhost:8000/v2/agents

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

4. Chat with an agent

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
  }'

If the reply mentions an invalid API key, check the model key in .env and restart the server. To pick a different model, see Choosing a model.

5. Stop services

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

Project Structure

hivegate/
├── agents/                 # Model factory, model aliases, pricing
├── 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

Usage API (/usage/*): an API key with the usage:read scope, or the admin secret. A key whose only scope is usage:read is refused on /v2, so a usage dashboard's key can't call agents.

Development: Set AUTH_DISABLED=true to bypass authentication.

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:

Z.ai GLM models (glm-5.3, glm-5.3-flashx, glm-5.3-flash, glm-5.2) are pinned ids only - Z.ai documents no model-listing endpoint to resolve an alias against. DeepSeek has two: deepseek-flash (itself a moving name, now V4.1-Flash) and deepseek-v4-pro. OpenAI models run on the Responses API: GPT-6 calls tools on Chat Completions only with reasoning off.

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.

Claude models run with prompt caching on: the tools and system prompt are cached once per agent, and the growing conversation is cached between round trips. Cached input bills at 0.1x the input price (cache writes at 1.25x, 5-minute TTL).

Usage and cost

Every chat, commit, MCP and team run - streamed or not, including failed, refused and abandoned ones - writes a row to token_usage with its tokens (input, output, cache, reasoning), round trips, tool calls, duration and cost_usd. Recording runs off the event loop and never fails a call.

Costs come from the price table in agents/pricing.py (Anthropic, Gemini, OpenAI). A model with no known price is reported as unpriced, never guessed; /usage/summary counts those in unpriced_calls and partially_priced_calls. Add or correct a price without a redeploy:

PRICING_OVERRIDES='{"my-model": {"input": 5, "output": 25}}'   # USD per million tokens

curl -H "X-API-Key: agw_xxxxx" "http://localhost:8000/usage/summary?group_by=agent"

scripts/usage_from_runs.py builds a read-only per-agent cost report from Agno's stored runs.

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://xxx@sentry.io/xxx

Example: Cloud-native with OTLP

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

Contributors

HiveGate is built in the open, and these people have contributed to it:

• @cestercian — documented DEFAULT_CHAT_MODEL (#76), the project's first outside contribution
• @rathi-mohit — corrected the cors_origin_list documentation (#101)
• @shashank1027 — added a test that keeps .env.example in sync with ApiSettings (#103)

There are good first issues open now, each small and self-contained. Comment on one and it's yours.

Support

• Agno Documentation
• Report an Issue

License

MIT License - see LICENSE for details.