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

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
from vanna.integrations.local.agent_memory import DemoAgentMemory

# 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 with memory
agent = Agent(
    llm_service=AnthropicLlmService(
        model="claude-sonnet-4",
        api_key="sk-ant-..."  # Replace with your API key
    ),
    tool_registry=tools,
    user_resolver=CookieEmailUserResolver(),
    agent_memory=DemoAgentMemory(max_items=1000),
    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(),  # How to identify users
    agent_memory=DemoAgentMemory(),            # Tool usage learning
    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
)