Idea central: Vanna es uno de los frameworks de código abierto más utilizados en la actualidad para crear asistentes de SQL con IA. Funciona en dos pasos: primero entrenas un modelo de IA (o un índice vectorial) con tu esquema, documentación y consultas SQL reales pasadas, y luego genera código con una precisión quirúrgica.

Ventajas: Se conecta nativamente a Snowflake, BigQuery, PostgreSQL y MySQL. Incluye interfaces gráficas listas para usar en Slack o aplicaciones web.

Novedades de la versión 2.0

• Atención al usuario en cada nivel: Las consultas se filtran automáticamente según los permisos del usuario.
• Interfaz web moderna <vanna-chat>: Un componente prediseñado de gran belleza.
• Respuestas en tiempo real: Tablas, gráficos y actualizaciones de progreso en tiempo real.
• Seguridad empresarial: Seguridad a nivel de fila (RLS), registros de auditoría y limitación de velocidad (rate limiting).
• Listo para producción: Integración con FastAPI, observabilidad y ganchos de ciclo de vida (lifecycle hooks).

¿Cómo funciona? (Conceptos Clave)

1. Resolutor de usuarios (User Resolver): Define cómo extraer la identidad del usuario de las solicitudes (cookies, JWT, etc.).
2. Herramientas con reconocimiento de usuario: Las herramientas comprueban automáticamente los permisos en función de la pertenencia del usuario a grupos.
3. Componentes de transmisión: El backend transmite componentes de interfaz de usuario estructurados (tablas, gráficos) al frontend en tiempo real.
4. Interfaz de usuario web integrada: El componente predefinido <vanna-chat> lo renderiza todo a la perfección.

Ejemplo de Código (Configuración de producción con su autorización)

Aquí tienes un ejemplo completo de cómo integrar Vanna con tu aplicación FastAPI y tu sistema de autenticación existentes:

1. Backend (Python + FastAPI):

python
python
from fastapi import FastAPI
from vanna import Agent
from vanna.servers.fastapi.routes import register_chat_routes
from vanna.servers.base import ChatHandler
from vanna.core.user import UserResolver, User, RequestContext
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.core.registry import ToolRegistry

App de FastAPI existente

app = FastAPI()

1. Define tu user resolver (usando TU propio sistema de auth)

class MyUserResolver(UserResolver):
async def resolve_user(self, request_context: RequestContext) -> User:
# Extraer desde cookies, JWTs, o sesión
token = request_context.get_header('Authorization')
user_data = self.decode_jwt(token) # Tu lógica existente

    return User(
        id=user_data['id'],
        email=user_data['email'],
        group_memberships=user_data['groups']  # Usado para permisos
    )

2. Configurar el agente con herramientas

llm = AnthropicLlmService(model="claude-3-5-sonnet")
tools = ToolRegistry()
tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))

agent = Agent(
llm_service=llm,
tool_registry=tools,
user_resolver=MyUserResolver()
)

3. Añadir las rutas de Vanna a tu aplicación

chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)

Ahora tienes listo el endpoint: POST /api/vanna/v2/chat_sse (streaming)

`

2. Frontend (Componente Web):

Simplemente agrega esta etiqueta HTML en tu página web. Funciona con React, Vue o HTML simple y utiliza tus cookies/JWT existentes:

HTML

sse-endpoint="/api/vanna/v2/chat_sse"
theme="dark">

Al hacer una pregunta en lenguaje natural, el componente frontend recibe por transmisión ( streaming ):

• Actualizaciones del progreso de la transmisión.
• Bloque de código SQL (Por defecto, solo se muestra a los usuarios "admin").
• Tabla de datos interactiva.
• Gráficos (visualizaciones de Plotly).
• Resumen en lenguaje natural.

Herramientas Personalizadas
Puedes extender Vanna con herramientas específicas para tu caso de uso de negocio (por ejemplo, enviar un correo automático con los resultados):

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

class EmailArgs(BaseModel):
recipient: str = Field(description="Email recipient")
subject: str = Field(description="Email subject")

class EmailTool(Tool[EmailArgs]):
@property
def name(self) -> str:
return "send_email"

@property

def access_groups(self) -> list[str]:

    return ["send_email"]  # Verificación de permisos

def get_args_schema(self) -> Type[EmailArgs]:

    return EmailArgs

async def execute(self, context: ToolContext, args: EmailArgs) -> ToolResult:

    user = context.user  # Inyectado automáticamente por Vanna

# Tu lógica de negocio
await self.email_service.send(
    from_email=user.email,
    to=args.recipient,
    subject=args.subject
)

return ToolResult(success=True, result_for_llm=f"Email sent to {args.recipient}")

Registrar tu herramienta personalizada

tools.register(EmailTool())

Características Avanzadas y Casos de Uso

• Vanna 2.0 incluye potentes funciones empresariales para producción:
• Ganchos del ciclo de vida (Lifecycle Hooks): Agrega comprobación de cuotas, registro personalizado y filtrado de contenido.
• Middlewares de LLM: Implementa almacenamiento en caching, ingeniería de avisos o seguimiento de costos.
• Almacenamiento de conversaciones: Guarda y recupera el historial de conversaciones por usuario.

¿Para qué casos es ideal?

• Aplicaciones de análisis de datos con interfaces de lenguaje natural.
• SaaS multiusuario que requiere permisos con reconocimiento de usuario (Seguridad a nivel de fila).
• Aplicaciones empresariales con requisitos estrictos de seguridad y auditoría.

Flujo de Arquitectura (Sequence Diagram)

El siguiente flujo detalla el ciclo de vida de una solicitud en Vanna 2.0 desde que el usuario realiza la pregunta hasta que se renderizan los componentes visuales:

• Paso 1: El usuario escribe una pregunta como "Show Q4 sales" en el componente <vanna-chat>.
• Paso 2: El frontend envía un POST al endpoint /api/vanna/v2/chat_sse de tu servidor FastAPI, adjuntando las credenciales de autenticación.
• Paso 3: Tu servidor resuelve la identidad del usuario (ej. Alice) y sus grupos de acceso (read_sales) y se los pasa al Agente.
• Paso 4: El Agente invoca la herramienta de ejecución de SQL (User-Aware Tool).
• Paso 5: La herramienta aplica automáticamente las reglas de seguridad a nivel de fila (RLS) según el grupo del usuario.
• Paso 6: La base de datos retorna únicamente los resultados filtrados y autorizados al Agente.
• Paso 7: El Agente transmite (streams) la respuesta en bloques estructurados (Tabla → Gráfico → Resumen) de vuelta al componente web para dibujarlo en pantalla de forma estética.

Comparativa rápida

Conclusiones y buenas prácticas.

• Nunca ejecutes SQL generado por IA sin validarlo. Usa listas de operaciones permitidas ( SELECT solamente) y usuarios de base de datos blancos con permisos de solo lectura.
• El contexto del esquema es clave. Cuanto más claro y completo sea el esquema que le das al modelo, mejor será el SQL generado.
• Los agentes brillan en tareas multipaso , pero cuestan más tokens/latencia que una llamada simple.
• Streamlit es la vía más rápida para llevar un prototipo a manos de usuarios no técnicos. ¿Ya probaste alguno de estos enfoques en tu equipo? Cuéntame en los comentarios qué stack usaste y qué problemas encontraste al conectar LLMs con bases de datos reales.

Comunidad y Apoyo (Vanna Ecosystem)

Si decides inclinarte por la implementación de agentes empresariales con Vanna AI, aquí tienes los accesos directos a sus canales oficiales para resolver dudas de integración avanzada:

**Documentación completa* — Guías completas y referencia detallada de la API de Vanna.
Foros de discusión de GitHub — Espacio para sugerencias de nuevas funciones, extensiones y preguntas/respuestas de la comunidad.
Problemas de GitHub — Reportes de errores, fallos de conectores y seguimiento de parches.
Soporte empresarial — Soporte técnico directo vía [email protected].

Este post recopila y adapta ejemplos de fuentes públicas con fines educativos y de referencia para la comunidad de desarrolladores.

Ejemplos Oficiales de Inicio Rápido: GitHub - vanna-ai/vanna-boilerplate (Este repositorio contiene plantillas listas para clonar usando Flask, Streamlit o FastAPI, ideales para no empezar desde cero).

Componente Frontend Oficial (): GitHub - vanna-ai/vanna-components (El código fuente del componente web de interfaz gráfica que vimos en los diagramas si quieres modificar su diseño o comportamiento).

Notebooks de Jupyter con Ejemplos por Base de Datos: En la misma organización de GitHub tienen guías paso a paso en formato Notebook para configuraciones específicas:

Para conectar e instruir con Snowflake: Vanna Snowflake Notebook
Para conectar e instruir con BigQuery: Vanna BigQuery Notebook
Para entornos locales con SQLite: Vanna SQLite Notebook