Deploying with Flask

Vanna 2.0 supports deployment with Flask for teams already using Flask-based infrastructure.

Quick Start

from vanna import Agent, ToolRegistry
from vanna.servers.flask import VannaFlaskServer
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.integrations.postgres import PostgresRunner
from vanna.tools import RunSqlTool

# Create components
llm_service = AnthropicLlmService(api_key="...")
sql_runner = PostgresRunner(connection_string="...")

# Create tool registry and register tools
registry = ToolRegistry()
registry.register_local_tool(RunSqlTool(sql_runner), access_groups=[])

# Create your agent
agent = Agent(
    llm_service=llm_service,
    tool_registry=registry,
    user_resolver=MyUserResolver(),
    agent_memory=MyAgentMemory()  # Required parameter
)

# Create Flask server
server = VannaFlaskServer(agent)

# Run the server
server.run(host="0.0.0.0", port=5000)

Server Configuration

Configure the Flask server with custom settings:

config = {
    "flask": {
        "debug": False,
        "threaded": True
    },
    "cors": {
        "enabled": True,
        "origins": ["https://myapp.com"],
        "supports_credentials": True
    }
}

server = VannaFlaskServer(agent, config=config)

Adding to an Existing Flask App

If you already have a Flask application, you can add Vanna chat endpoints to it:

from flask import Flask
from vanna import Agent
from vanna.servers.base import ChatHandler
from vanna.servers.flask.routes import register_chat_routes

# Your existing Flask app with your own routes
app = Flask(__name__)

# ... your existing routes here ...
# @app.route('/api/users')
# @app.route('/api/orders')
# etc.

# Add Vanna chat endpoints to your existing app
agent = Agent(
    llm_service=llm,
    tool_registry=registry,
    user_resolver=user_resolver,
    agent_memory=agent_memory
)

chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler, config={
    "dev_mode": False,
    "cdn_url": "https://img.vanna.ai/vanna-components.js"
})

# Now your app has BOTH:
# - Your existing routes: /api/users, /api/orders, etc.
# - Vanna routes: /, /api/vanna/v2/chat_sse, /api/vanna/v2/chat_poll

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

This registers the following Vanna endpoints on your existing app:

• GET / - Web UI (optional, can be disabled by not registering)
• POST /api/vanna/v2/chat_sse - Server-Sent Events streaming
• POST /api/vanna/v2/chat_poll - HTTP polling

Note: The basic Flask integration doesn’t include WebSocket support. Use Flask-SocketIO if you need WebSocket endpoints.

Creating the WSGI Application

For deployment with Gunicorn or other WSGI servers:

# app.py
from vanna import Agent
from vanna.servers.flask import VannaFlaskServer

agent = Agent(...)
server = VannaFlaskServer(agent)
app = server.create_app()

# Run with: gunicorn app:app -b 0.0.0.0:5000

API Endpoints

The Flask server provides these endpoints:

Chat Endpoints

• GET / - Web UI interface
• POST /api/vanna/v2/chat_sse - Server-Sent Events streaming endpoint
• POST /api/vanna/v2/chat_poll - HTTP polling endpoint
• GET /api/vanna/v2/chat_websocket - WebSocket placeholder (returns 501, use Flask-SocketIO for WebSocket support)

Health Check

• GET /health - Server health status

Example Chat Request (SSE)

import requests
import json

response = requests.post(
    "http://localhost:5000/api/vanna/v2/chat_sse",
    json={
        "message": "Show me sales by region",
        "conversation_id": "conv_123",
        "metadata": {}
    },
    headers={
        "Authorization": "Bearer your-jwt-token"
    },
    stream=True
)

# Process SSE stream
for line in response.iter_lines():
    if line:
        if line.startswith(b"data: "):
            data = line[6:].decode('utf-8')
            if data != "[DONE]":
                chunk = json.loads(data)
                print(chunk)

Example Chat Request (Polling)

import requests

response = requests.post(
    "http://localhost:5000/api/vanna/v2/chat_poll",
    json={
        "message": "Show me sales by region",
        "conversation_id": "conv_123",
        "metadata": {}
    },
    headers={
        "Authorization": "Bearer your-jwt-token"
    }
)

print(response.json())

Production Deployment

Using Gunicorn

pip install gunicorn
gunicorn app:app 
  --workers 4 
  --bind 0.0.0.0:5000 
  --timeout 120

Using uWSGI

pip install uwsgi
uwsgi --http 0.0.0.0:5000 
  --wsgi-file app.py 
  --callable app 
  --processes 4 
  --threads 2

With Nginx

upstream vanna {
    server 127.0.0.1:5000;
    server 127.0.0.1:5001;
    server 127.0.0.1:5002;
}

server {
    listen 80;
    server_name vanna.example.com;

    location / {
        proxy_pass http://vanna;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Docker Deployment

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY app.py .

CMD ["gunicorn", "app:app", "-b", "0.0.0.0:5000", "--workers", "4"]

docker build -t vanna-flask .
docker run -p 5000:5000 vanna-flask

Integrating with Existing Flask Apps (Advanced)

You can mount Vanna under a custom path prefix in an existing Flask application:

from flask import Flask
from vanna import Agent
from vanna.servers.flask import VannaFlaskServer

# Your existing Flask app with your own routes
app = Flask(__name__)

# ... your existing routes here ...
# @app.route('/')
# @app.route('/api/data')
# etc.

# Create Vanna agent
agent = Agent(
    llm_service=llm_service,
    tool_registry=registry,
    user_resolver=user_resolver,
    agent_memory=agent_memory
)

# Register Vanna routes under /vanna prefix
vanna_server = VannaFlaskServer(agent)
vanna_app = vanna_server.create_app()

# Mount Vanna routes
from werkzeug.middleware.dispatcher import DispatcherMiddleware

app.wsgi_app = DispatcherMiddleware(app.wsgi_app, {
    '/vanna': vanna_app.wsgi_app
})

# Now Vanna endpoints are at:
# - /vanna/ (Web UI)
# - /vanna/api/vanna/v2/chat_sse
# - /vanna/api/vanna/v2/chat_poll
# - /vanna/health

Session Management

Configure Flask sessions for authentication:

from flask import Flask
from vanna.servers.flask import VannaFlaskServer

server = VannaFlaskServer(agent)
app = server.create_app()

# Configure sessions
app.config['SECRET_KEY'] = 'your-secret-key'
app.config['SESSION_TYPE'] = 'filesystem'  # or 'redis', 'memcached'

from flask_session import Session
Session(app)

See Also

• Deploying with FastAPI
• Authentication & Permissions
• Observability