Claude + MCP + ADK: Construyo un Agente IA con BigQuery que Sustituye al Data Analyst

Matriz de Decisión Arquitectónica para Analítica con LLMs

Comparativa entre los tres enfoques predominantes para exponer datos analíticos a usuarios de negocio mediante interfaces conversacionales:

Implementación del Agente Analítico con ADK y BigQuery Toolset

Estructura de producción modular en Python utilizando el SDK de adk, autenticación enterprise vía google.auth (ADC) y una herramienta personalizada para generar gráficos como artefactos visuales interactivos:

"""
Agente Analítico Autónomo con Google ADK y BigQuery
Orquestación code-first con autenticación ADC y generación de artefactos visuales.
"""

import os
import io
import base64
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
import google.auth
from adk.agents import Agent
from adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig
from adk.context import ToolContext

# 1. Configuración de credenciales de Google Cloud (ADC)
credentials, project_id = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
bq_config = BigQueryCredentialsConfig(
    project_id=project_id,
    credentials=credentials
)
bq_toolset = BigQueryToolset(config=bq_config)

# 2. Herramienta personalizada para renderizado de artefactos gráficos
async def generate_chart(
    chart_type: str,
    labels: list,
    values: list,
    title: str,
    x_label: str = "",
    y_label: str = "",
    tool_context: ToolContext = None
) -> dict:
    """Genera una gráfica (bar, pie, line) y la guarda como artefacto visible en chat."""
    plt.figure(figsize=(9, 5))
    plt.style.use('seaborn-v0_8-whitegrid' if 'seaborn-v0_8-whitegrid' in plt.style.available else 'default')
    
    if chart_type == "bar":
        plt.bar(labels, values, color="#36f097", edgecolor="#0c2520")
        plt.xticks(rotation=45, ha='right')
    elif chart_type == "pie":
        plt.pie(values, labels=labels, autopct='%1.1f%%', startangle=140)
    elif chart_type == "line":
        plt.plot(labels, values, marker='o', color="#36f097", linewidth=2.5)
        plt.xticks(rotation=45, ha='right')
        
    plt.title(title, fontsize=14, fontweight='bold', pad=15)
    if x_label and chart_type != "pie": plt.xlabel(x_label)
    if y_label and chart_type != "pie": plt.ylabel(y_label)
    plt.tight_layout()

    buf = io.BytesIO()
    plt.savefig(buf, format='png', dpi=150)
    buf.seek(0)
    img_bytes = buf.getvalue()
    plt.close()

    # Emisión del artefacto multimedia a la interfaz del chat
    if tool_context and hasattr(tool_context, "save_artifact"):
        await tool_context.save_artifact(
            name="chart.png",
            mime_type="image/png",
            data=img_bytes
        )

    return {"status": "success", "message": f"Gráfico '{title}' generado y renderizado como artefacto."}

# 3. Inicialización del Agente Analítico con modelo de frontera en Vertex AI
agent_instructions = f"""
Eres un Data Analyst Senior experto en Google BigQuery.
Tu objetivo es responder consultas de negocio sobre el dataset de e-commerce en `{project_id}.ecommerce_data`.

REGLAS OBLIGATORIAS:
1. Inspecciona las tablas (`list_tables`) y su esquema (`get_table_info`) antes de construir consultas.
2. Escribe únicamente sentencias SELECT optimizadas; nunca ejecutes DDL ni mutaciones destructivas.
3. Para tendencias temporales o distribuciones, invoca automáticamente `generate_chart`.
4. Utiliza BigQuery ML (`forecast`) cuando el usuario solicite predicciones a futuro.
5. Responde siempre de forma clara, ejecutiva y en español con cifras normalizadas.
"""

root_agent = Agent(
    model="gemini-2.5-flash",  # O backend Claude 3.7 Sonnet en Vertex Model Garden
    name="bigquery_data_analyst",
    description="Agente autónomo para análisis de datos y forecasting en BigQuery.",
    instructions=agent_instructions,
    tools=[
        bq_toolset.list_datasets,
        bq_toolset.list_tables,
        bq_toolset.get_table_info,
        bq_toolset.execute_sql,
        bq_toolset.forecast,
        generate_chart
    ]
)

if __name__ == "__main__":
    # Ejecución con interfaz web reactiva: adk web --port 8000
    print("[✓] Agente inicializado con autenticación ADC y herramientas BigQuery.")

Patrones de Diseño: Vibecoding & Model Context Protocol (MCP)

El flujo de trabajo moderno de desarrollo con IA (Vibecoding) traslada el foco de la sintaxis repetitiva a la dirección arquitectónica de alto nivel. Sin embargo, para que un asistente de código como Copilot o Claude genere implementaciones libres de alucinaciones sobre frameworks emergentes como ADK, requiere acceso a la documentación viva de la API en tiempo real.

{
  "mcpServers": {
    "adk-docs": {
      "command": "npx",
      "args": ["-y", "@google/adk-docs-mcp-server"],
      "transport": "stdio"
    }
  }
}

Framework de Implementación en Producción

• 1
  Configurar Autenticación ADC: Ejecutar gcloud auth application-default login para aprovisionar tokens OAuth de corta duración sin exponer llaves estáticas de Service Account.
• 2
  Vincular Servidor MCP en el Workspace: Conectar el repositorio de documentación técnica al entorno de desarrollo para guiar al modelo de generación de código.
• 3
  Definir el System Prompt con Sandboxing: Restringir las operaciones a sólo lectura en el catálogo de BigQuery y parametrizar los límites de partición por fecha.
• 4
  Implementar Handlers de Artefactos: Exponer herramientas capaces de capturar buffers de gráficos en memoria y transmitirlos como payloads MIME directos al chat.
• 5
  Validar Inferencia y Forecasting Local: Levantar el servidor interactivo con adk web --port 8000 y ejecutar pruebas de estrés analítico y predicción de series temporales.

Preguntas Frecuentes Técnicas