5-Minute Quickstart

Build and run your first Vanna agent with a web UI in 5 minutes.

Prerequisites

Python 3.8 or higher
Anthropic API key (get one here)

Step 1: Install Vanna

pip install 'vanna[flask,anthropic] @ git+https://github.com/vanna-ai/vanna.git@v2'

Step 2: Download Sample Database

curl -o Chinook.sqlite https://vanna.ai/Chinook.sqlite

Step 3: Create Your Agent

Create app.py:

from vanna import Agent, AgentConfig
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.core.registry import ToolRegistry
from vanna.core.user import CookieEmailUserResolver
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner

# 1. Configure tools with permissions
tools = ToolRegistry()
tools.register_local_tool(
    RunSqlTool(sql_runner=SqliteRunner(database_path="./Chinook.sqlite")),
    access_groups=['users']
)

# 2. Create agent
agent = Agent(
    llm_service=AnthropicLlmService(
        model="claude-sonnet-4",
        api_key="sk-ant-..."  # Replace with your API key
    ),
    tool_registry=tools,
    user_resolver=CookieEmailUserResolver(),
    config=AgentConfig()
)

# 3. Run server with web UI
server = VannaFastAPIServer(agent)
server.run()

Step 4: Run the Server

export ANTHROPIC_API_KEY=sk-ant-...
python app.py

Output:

Your app is running at:
http://localhost:8000

Step 5: Use the Web Interface

Open http://localhost:8000 in your browser
Log in with any email (e.g., demo@example.com)
Ask questions about the database:
- “What tables are in this database?”
- “Show me the top 10 customers by total spending”
- “How many tracks are there?”

The agent generates SQL, executes it, and shows results in the web UI!

🎉 You’re done! You now have a working SQL agent.

What Just Happened?

1. Tool Configuration

tools.register_local_tool(
    RunSqlTool(...),
    access_groups=['users']  # Who can use this tool
)

You registered a SQL query tool that users in the ‘users’ group can access.

2. Agent Configuration

agent = Agent(
    llm_service=AnthropicLlmService(...),  # The AI brain
    tool_registry=tools,                     # Available capabilities
    user_resolver=CookieEmailUserResolver(), # Authentication
    config=AgentConfig()                     # Settings
)

The agent knows how to use Claude to decide when to query the database.

3. Web Server

server = VannaFastAPIServer(agent)
server.run()

FastAPI server with built-in web UI for chatting with your agent.

Customize for Your Database

PostgreSQL

from vanna.integrations.postgres import PostgresRunner

tools.register_local_tool(
    RunSqlTool(sql_runner=PostgresRunner(
        host="localhost",
        database="mydb",
        user="postgres",
        password="..."
    )),
    access_groups=['analysts']
)

MySQL

from vanna.integrations.mysql import MySQLRunner

tools.register_local_tool(
    RunSqlTool(sql_runner=MySQLRunner(
        host="localhost",
        database="mydb",
        user="root",
        password="..."
    )),
    access_groups=['analysts']
)

Add More Capabilities

Visualization

from vanna.tools import VisualizeDataTool

tools.register_local_tool(
    VisualizeDataTool(),
    access_groups=['users']
)

Now users can ask: “Show me a chart of sales by month”

Data Export

from vanna.tools import ExportDataTool

tools.register_local_tool(
    ExportDataTool(),
    access_groups=['analysts']  # Restrict to certain users
)