HiveGate

📖 Docs & landing page: hivegate.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 hivegate

# 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)
# export XAI_API_KEY="your-xai-api-key"              # xAI (Grok)
# export ZAI_API_KEY="your-zai-api-key"              # Z.ai (GLM)
# export DEEPSEEK_API_KEY="your-deepseek-api-key"    # DeepSeek

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:

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.

4. Stop services

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

Project Structure

hivegate/
├── 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.