Cómo Construir Chatbots de Atención al Cliente Conectados a tu Stock en BigQuery

Matriz de Decisión: Enfoques para Consultar Stock con IA

Elegir el patrón adecuado para conectar un agente conversacional con un almacén de datos requiere balancear latencia, coste por consulta y precisión del modelo.

Implementación Práctica: Agente de Stock con ADK y BigQuery

A continuación se muestra la estructura modular en Python para registrar las tablas dimensionales de BigQuery, inicializar el servicio de análisis de datos y configurar el agente conversacional mediante el SDK de Google GenAI / Agent Development Kit.

import os
from google import genai
from google.genai import types

# 1. Configuración de Entorno y Referencias de BigQuery
PROJECT_ID = os.getenv("GCP_PROJECT_ID", "data-agent-3-preguntas")
DATASET_ID = "fake_business_data"
LOCATION = "us-central1"

TABLE_PRODUCTS_STOCK = f"{PROJECT_ID}.{DATASET_ID}.dim_products_stock"
TABLE_STORES = f"{PROJECT_ID}.{DATASET_ID}.dim_stores"
TABLE_INVENTORY = f"{PROJECT_ID}.{DATASET_ID}.fact_inventory"

# 2. Definición del Prompt de Sistema del Agente
SYSTEM_INSTRUCTION = """
Eres un asistente de inventario y ventas altamente eficiente para atención al cliente.
Tu objetivo es resolver dudas de disponibilidad, precio y ubicación de productos.

Reglas obligatorias de ejecución:
1. Identifica el producto solicitado (categoría, modelo, talla, color).
2. Utiliza siempre la herramienta 'check_stock_tool' cruzando 'dim_products_stock', 'dim_stores' y 'fact_inventory'.
3. Si el producto solicitado no tiene stock disponible en una tienda, ofrece proactivamente alternativas en tiendas cercanas o tallas similares.
4. Responde de forma concisa, educada y orientada al cierre de la venta.
"""

# 3. Definición de la Tool Conectada al Motor Analítico
def check_stock_tool(query_intent: str) -> dict:
    """
    Ejecuta una consulta SQL segura sobre el dataset dimensional de BigQuery
    a partir de la intención estructurada del usuario.
    """
    client = genai.Client()
    
    # Enrutamiento al servicio de Data Analytics de Vertex / ADK
    response = client.models.generate_content(
        model="gemini-2.0-flash",
        contents=f"Consulta de inventario para la intención: {query_intent}",
        config=types.GenerateContentConfig(
            system_instruction="Genera y ejecuta SQL ANSI estándar contra BigQuery usando el esquema provisto.",
            temperature=0.0
        )
    )
    return {"status": "success", "data": response.text}

# 4. Inicialización del Agente Conversacional en ADK
def create_stock_agent():
    client = genai.Client()
    
    chat_session = client.chats.create(
        model="gemini-2.0-flash",
        config=types.GenerateContentConfig(
            system_instruction=SYSTEM_INSTRUCTION,
            tools=[check_stock_tool],
            temperature=0.2
        )
    )
    return chat_session

if __name__ == "__main__":
    agent = create_stock_agent()
    user_query = "Tienen las Nike Air en rojo talla 42? Cuánto cuestan y en qué tienda?"
    response = agent.send_message(user_query)
    print("Respuesta del Agente:\n", response.text)

Patrones de Diseño y Buenas Prácticas en Producción

1. Modelado en Esquema Estrella para Reducir Ambigüedad

Para que el modelo de IA genere filtros precisos sin ambigüedad léxica, separa las entidades en tablas dimensionales limpias: dim_products (metadatos, descripciones, atributos), dim_stores (ubicaciones y nombres de tienda) y fact_inventory (unidades disponibles actualizadas en streaming o micro-batch).

2. Seguridad e IAM de Mínimo Privilegio

La cuenta de servicio (Service Account) utilizada por el agente en Cloud Run o ADK nunca debe tener privilegios de edición sobre el Data Warehouse. Asigna exclusivamente roles/bigquery.dataViewer y roles/bigquery.jobUser sobre datasets específicos para mitigar riesgos de modificación accidental o inyección maliciosa.

3. Respuestas Proactivas y Recomendaciones Dinámicas

Un chatbot de stock no debe limitarse a devolver un "No hay existencias". Instruye al agente en su system prompt para que, ante un resultado con cantidad cero, evalúe productos en el mismo rango de precio o verifique existencias en el almacén online para ofrecer reserva inmediata.

Preguntas Frecuentes (FAQ)