Python SDK Reference

Complete reference for the Vanna 2.0 Python SDK.

Installation

pip install vanna

Optional Dependencies

# Database integrations
pip install vanna[postgres]
pip install vanna[mysql]
pip install vanna[snowflake]
pip install vanna[bigquery]
pip install vanna[duckdb]

# LLM providers
pip install vanna[anthropic]
pip install vanna[openai]

# All integrations
pip install vanna[all]

Core Classes

Agent

The main orchestrator for your AI agent.

from vanna import Agent

agent = Agent(
    llm_service: LlmService,
    tool_registry: ToolRegistry,
    user_resolver: UserResolver,
    agent_memory: AgentMemory,
    conversation_store: Optional[ConversationStore] = None,
    config: AgentConfig = AgentConfig(),
    system_prompt_builder: SystemPromptBuilder = DefaultSystemPromptBuilder(),
    lifecycle_hooks: List[LifecycleHook] = [],
    llm_middlewares: List[LlmMiddleware] = [],
    workflow_handler: Optional[WorkflowHandler] = None,
    error_recovery_strategy: Optional[ErrorRecoveryStrategy] = None,
    context_enrichers: List[ToolContextEnricher] = [],
    llm_context_enhancer: Optional[LlmContextEnhancer] = None,
    conversation_filters: List[ConversationFilter] = [],
    observability_provider: Optional[ObservabilityProvider] = None,
    audit_logger: Optional[AuditLogger] = None
)

Methods:

# Send a message to the agent
async def send_message(
    request_context: RequestContext,
    message: str,
    *,
    conversation_id: Optional[str] = None
) -> AsyncGenerator[UiComponent, None]

# Get available tools for a user
async def get_available_tools(user: User) -> List[ToolSchema]

Tool

Base class for creating tools.

from vanna.core.tool import Tool, ToolContext, ToolResult
from pydantic import BaseModel, Field
from typing import Type, List

# Define the arguments schema using Pydantic
class MyToolArgs(BaseModel):
    text: str = Field(description="The text to process")
    count: int = Field(default=1, description="Number of times to repeat")

# Implement the tool
class MyTool(Tool[MyToolArgs]):
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return "A tool that processes text"

    @property
    def access_groups(self) -> List[str]:
        return []  # Empty = all users can access

    def get_args_schema(self) -> Type[MyToolArgs]:
        return MyToolArgs

    async def execute(
        self,
        context: ToolContext,
        args: MyToolArgs
    ) -> ToolResult:
        # Tool implementation
        result = args.text * args.count

        return ToolResult(
            success=True,
            result_for_llm=f"Processed: {result}",
            ui_component=None,  # Optional UI component
            metadata={"length": len(result)}
        )

Registering Tools:

from vanna import ToolRegistry

# Create registry
registry = ToolRegistry()

# Register a tool (accessible to all users)
registry.register_local_tool(MyTool(), access_groups=[])

# Register a tool with access restrictions
registry.register_local_tool(MyTool(), access_groups=["admin"])

User

Represents an authenticated user.

from vanna.core.user import User

user = User(
    id: str,
    username: str,
    email: Optional[str] = None,
    permissions: List[str] = [],
    group_memberships: List[str] = [],
    metadata: Dict[str, Any] = {}
)

LLM Integrations

Anthropic

from vanna.integrations.anthropic import AnthropicLlmService

llm = AnthropicLlmService(
    api_key="sk-ant-...",  # Optional, defaults to ANTHROPIC_API_KEY env var
    model="claude-sonnet-4-5"  # Optional, defaults to "claude-sonnet-4-5"
)

OpenAI

from vanna.integrations.openai import OpenAILlmService

llm = OpenAILlmService(
    api_key="sk-...",  # Optional, defaults to OPENAI_API_KEY env var
    model="gpt-5",  # Optional
    organization="org-..."  # Optional
)

Database Integrations

PostgreSQL

from vanna.integrations.postgres import PostgresRunner

sql_runner = PostgresRunner(
    connection_string="postgresql://user:pass@host:5432/db"
)

# Or using individual parameters
sql_runner = PostgresRunner(
    host="localhost",
    port=5432,
    database="mydb",
    user="user",
    password="pass"
)

MySQL

from vanna.integrations.mysql import MySQLRunner

sql_runner = MySQLRunner(
    host="localhost",
    database="mydb",
    user="user",
    password="pass",
    port=3306
)

SQLite

from vanna.integrations.sqlite import SqliteRunner

sql_runner = SqliteRunner(
    database_path="./data.db"
)

Snowflake

from vanna.integrations.snowflake import SnowflakeRunner

sql_runner = SnowflakeRunner(
    account="account",
    username="user",
    password="pass",
    database="db",
    warehouse="warehouse",
    role="role"
)

BigQuery

from vanna.integrations.bigquery import BigQueryRunner

sql_runner = BigQueryRunner(
    project_id="project",
    cred_file_path="./credentials.json"
)

DuckDB

from vanna.integrations.duckdb import DuckDBRunner

# File-based database
sql_runner = DuckDBRunner(
    database_path="./data.duckdb"
)

# In-memory database
sql_runner = DuckDBRunner(
    database_path=":memory:"
)

Memory Backends

Chroma (Local)

from vanna.integrations.chromadb import ChromaAgentMemory

memory = ChromaAgentMemory(
    persist_directory="./chroma_memory",
    collection_name="tool_memories"
)

In-Memory (Demo)

from vanna.integrations.local.agent_memory import DemoAgentMemory

memory = DemoAgentMemory()

Built-in Tools

RunSqlTool

from vanna.tools import RunSqlTool

tool = RunSqlTool(
    sql_runner=sql_runner,
    file_system=file_system,
    custom_tool_name=None,
    custom_tool_description=None
)

VisualizeDataTool

from vanna.tools import VisualizeDataTool

tool = VisualizeDataTool(
    file_system=file_system
)

File System Tools

from vanna.tools.file_system import (
    ReadFileTool,
    WriteFileTool,
    EditFileTool,
    ListFilesTool,
    SearchFilesTool
)
from vanna.integrations.local import LocalFileSystem

fs = LocalFileSystem()

read_tool = ReadFileTool(file_system=fs)
write_tool = WriteFileTool(file_system=fs)
edit_tool = EditFileTool(file_system=fs)
list_tool = ListFilesTool(file_system=fs)
search_tool = SearchFilesTool(file_system=fs)

Servers

FastAPI

from vanna.servers.fastapi import VannaFastAPIServer

server = VannaFastAPIServer(
    agent=agent,
    config={
        "cors": {
            "enabled": True,
            "allow_origins": ["*"]
        }
    }
)

# Create ASGI app
app = server.create_app()

# Or run directly
server.run(host="0.0.0.0", port=8000)

Flask

from vanna.servers.flask import VannaFlaskServer

server = VannaFlaskServer(
    agent=agent,
    config={}
)

app = server.create_app()
server.run(host="0.0.0.0", port=5000)

Configuration

AgentConfig

from vanna.core.agent import AgentConfig, UiFeatures, AuditConfig

config = AgentConfig(
    max_tool_iterations=10,
    stream_responses=True,
    auto_save_conversations=True,
    temperature=0.7,
    max_tokens=None,
    ui_features=UiFeatures(
        feature_group_access={
            'tool_names': ['admin'],
            'tool_arguments': ['admin'],
            'tool_error': ['admin']
        }
    ),
    audit_config=AuditConfig(
        enabled=True,
        log_tool_invocations=True,
        log_tool_results=True
    )
)

Components

UiComponent

from vanna.components import UiComponent
from vanna.components.rich import DataFrameComponent
from vanna.components.simple import SimpleTextComponent

ui = UiComponent(
    rich_component=DataFrameComponent(...),
    simple_component=SimpleTextComponent(text="...")
)

DataFrameComponent

from vanna.components.rich import DataFrameComponent

component = DataFrameComponent.from_records(
    records=[{'col1': 'val1', 'col2': 'val2'}],
    title="My Data",
    description="Description"
)

ChartComponent

from vanna.components.rich import ChartComponent

chart = ChartComponent(
    type="plotly",  # or "vega-lite"
    spec={...},
    title="Chart Title"
)

Type Hints

All Vanna classes include complete type hints for IDE support:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from vanna.core.tool import Tool, ToolContext, ToolResult
    from vanna.core.user import User
    from vanna.core.agent import Agent

Examples

See the examples directory in the GitHub repository for complete working examples.

See Also

• Quick Start
• Built-in Tools
• Custom Tools
• Deployment