Agente conversacional de BigQuery en Vertex AI con Google ADK: seis trampas
Cree un agente de lenguaje natural para BigQuery con Google ADK y Gemini, despliéguelo en Vertex AI Agent Engine, y evite las trampas relacionadas con Python, dependencias, facturación e IAM.
Fuentes: Building a BigQuery Conversational Agent on Vertex AI with ADK and the traps nobody warns you about
El problema: preguntas simples atascadas en una cola
Los equipos empresariales necesitan constantemente datos que ya se encuentran en el almacén de datos. ¿Cuántos pedidos se enviaron el mes pasado? ¿Qué producto se vende mejor? Cada pregunta se convierte en un ticket, luego en una extracción manual y, finalmente, en un intercambio de mensajes que puede durar horas o días, aunque la respuesta está a solo una consulta de distancia en BigQuery.
La alternativa es un agente conversacional. El usuario escribe una pregunta en inglés sencillo, el agente genera el SQL por sí mismo, lo ejecuta contra BigQuery y devuelve el resultado. No se necesita ticket, ni extracción, ni conocimientos de SQL. Hacer que funcione en una laptop es la parte fácil. Implementarlo correctamente en Google Cloud es donde aparecen los problemas ocultos, como conflictos de versión de Python, dependencias no declaradas y sorpresas relacionadas con IAM que solo se manifiestan una vez que el agente se ejecuta en la nube.
La pila para esta compilación consta de cuatro partes:
- Google ADK, el marco de trabajo del Kit de Desarrollo de Agentes que orquesta al agente.
- Gemini 2.5 Flash en Vertex AI como motor de razonamiento.
- El conjunto de herramientas BigQuery que incluye ADK para inspeccionar esquemas y ejecutar SQL.
- Vertex AI Agent Engine, el entorno de ejecución gestionado utilizado para el despliegue.
Configuración del proyecto
Un proyecto de Python nuevo con ADK instalado sirve como base, y en teoría se necesitan tres comandos: crear un entorno virtual, activarlo y ejecutar pip-install del paquete.
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk
Trampa 1: la versión de Python. ADK necesita Python 3.10 o una versión más reciente. Una Mac que aún cuenta con Python 3.9 del sistema parece funcionar bien hasta que se inicia el agente, momento en el que se muestran numerosos mensajes FutureWarning seguidos de un error grave que indica que MCP requiere Python 3.10 o superior. En macOS, evite cualquier conflicto con el intérprete del sistema e instale uno limpio a través de Homebrew, como se muestra en el siguiente bloque.
brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install google-adk
Verifique el resultado con python --version; debe indicar 3.12.x, y asegúrese de que el símbolo del sistema comience con (.venv). Después de eso, genere el esqueleto del agente mediante la línea de comandos de ADK.
adk create bq_agent_app
Trampa 2: nombres de carpetas. La carpeta del agente debe ser un identificador válido en Python, lo que significa que solo pueden utilizarse letras, dígitos y guiones bajos. Un nombre con guion como bq-agent-app hace que la implementación falle con el error Invalid agent name. La forma con guiones bajos bq_agent_app funciona. Es un detalle insignificante que puede hacer perder fácilmente diez minutos.
Todo el agente en un solo archivo
Aquí es donde ADK resulta útil. La lógica que de otro modo requeriría cientos de líneas de código de orquestación cabe en un único archivo declarativo. El archivo comienza con las importaciones para la autenticación de Google, la clase Agent, el conjunto de herramientas de BigQuery y sus clases de configuración de credenciales e instrumentos.
import google.auth
from google.adk.agents import Agent
from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig
from google.adk.tools.bigquery.config import BigQueryToolConfig
El resto reutiliza las Credenciales Predeterminadas de la Aplicación, crea la configuración de credenciales, configura el conjunto de herramientas y define al agente en sí, incluyendo su modelo, instrucciones y filtro de herramientas.
# Reuse your Application Default Credentials
application_default_credentials, project = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
credentials=application_default_credentials
)# Google's first-party BigQuery toolset
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # bills the query jobs
),
tool_filter=[
"list_dataset_ids",
"get_dataset_info",
"list_table_ids",
"get_table_info",
"execute_sql",
],
)root_agent = Agent(
model="gemini-2.5-flash",
name="bq_data_assistant",
description="Answers natural-language questions over BigQuery data.",
instruction=(
"You are a data assistant for business teams. "
"When asked a question, first inspect the schema of the relevant "
"tables (get_table_info) BEFORE writing any SQL, so you use real "
"column names and never invent them. "
"You always run your query jobs in the configured billing project, "
"but you CAN read data from any accessible dataset, including public "
"ones. Reading a public dataset from your billing project is normal "
"and allowed, never refuse for that reason. "
"Write standard BigQuery SQL, execute it with execute_sql, then "
"return a clear answer with the number and, in one line, the query used. "
"If a question is ambiguous, ask for clarification before running."
),
tools=[bigquery_toolset],
)
Tres aspectos en ese archivo reflejan la verdadera esencia de un agente.
Primero, el pensamiento y la acción están separados. Gemini se encarga del razonamiento, pero por sí solo no tiene conocimiento de tus datos ni acceso a BigQuery. El BigQueryToolset proporciona las herramientas que el modelo puede decidir utilizar, como verificar un esquema o ejecutar una consulta. Todo funciona en forma de bucle: el modelo analiza la pregunta y elige una herramienta, ADK la ejecuta, se obtiene el resultado y el modelo selecciona su siguiente acción hasta poder responder. Ese bucle constituye la línea divisoria entre un agente y un chatbot. Un chatbot habla, mientras que un agente actúa en tus sistemas dentro de un ciclo controlado.
En segundo lugar, la instrucción es el elemento clave. La línea que indica al agente inspeccionar el esquema antes de escribir SQL evita que invente nombres de columnas. El comportamiento se determina a través del prompt y no mediante código, y eso es más importante de lo que parece a primera vista.
En tercer lugar, tool_filter es el mecanismo de control con menor nivel de privilegios, ya que solo expone las herramientas que realmente necesita el agente. Para entornos de producción con datos sensibles, sería conveniente configurarlo en modo solo lectura para que el agente pueda ejecutar consultas pero no modificar nada.
Ejecutarlo localmente
ADK ofrece dos formas de ejecutar un agente. adk run bq_agent_app abre una conversación en terminal sencilla, mientras que adk web inicia una interfaz web local con un panel de chat y otro de eventos que muestra cada llamada a las herramientas. La interfaz web es más atractiva, aunque adk run es la opción mejor para solucionar problemas, ya que muestra los errores abiertamente en lugar de fallar en silencio.
Trampa 3: dependencias que el conjunto de herramientas nunca declara
Las cosas se estropean en esta etapa, y esta es la que genera más intercambios de mensajes. Se dice que el conjunto de herramientas BigQuery está integrado en ADK, pero en realidad depende silenciosamente de paquetes que google-adk no instala. El primer intento de ejecución falla con ModuleNotFoundError: No module named 'google.cloud'. Instalar google-cloud-bigquery provoca otro fallo, cannot import name 'dataplex_v1', y luego se solicita db-dtypes. Eso son tres fallos seguidos, cada uno causado por un paquete que el conjunto de herramientas asume pero nunca enumera.
La solución es instalar los tres de antemano y evitar ese bucle interminable.
pip install google-cloud-bigquery google-cloud-dataplex db-dtypes
Luego inicie la interfaz de usuario web.
adk web
Abra la URL local, seleccione el agente y haga una pregunta sencilla para verificar las tuberías.
List the tables in bigquery-public-data.thelook_ecommerce
Los datos de prueba son thelook_ecommerce, un conjunto de datos sintético de comercio electrónico que Google publica abiertamente. Los clientes, los productos y los pedidos lo hacen adecuado para un agente que responde preguntas empresariales, y no se involucran datos reales. Si se muestra la lista de tablas, la configuración funciona correctamente. Observe el panel de Eventos mientras responde, donde el agente enlaza get_table_info con execute_sql. Ese panel ofrece la visión más clara del comportamiento del agente y funciona bien en las demostraciones.
Trampa 4: el proyecto de facturación
Una vez confirmada la conectividad, intente hacer una pregunta real.
What is the most sold product?
El agente se niega amablemente. Indica que carece de permisos para crear trabajos en el proyecto bigquery-public-data, luego muestra el SQL que habría ejecutado y pide que se le indique un proyecto en el que tenga derechos. Parece una mala configuración, pero no lo es. Se trata de un concepto de BigQuery que resulta obvio con el tiempo pero que confunde a casi todos al principio.
bigquery-public-data es un proyecto de solo lectura propiedad de Google. Puedes leer sus tablas, pero no puedes ejecutar consultas dentro de él, ya que ejecutar una consulta crea un trabajo y ese trabajo debe facturarse en un proyecto en el que tengas derechos. Google no permite que nadie facture los costos de procesamiento en su proyecto. Por lo tanto, leer datos y ejecutar una consulta son dos acciones separadas vinculadas a dos proyectos distintos: uno alberga los datos y el otro paga por el procesamiento.
La solución indica al conjunto de herramientas que ejecute tareas en su propio proyecto mientras sigue leyendo del conjunto de datos público. La configuración es compute_project_id, y se encuentra en BigQueryToolConfig, el cual debe importarse primero.
from google.adk.tools.bigquery.config import BigQueryToolConfig
Luego, el conjunto de herramientas se crea con esa configuración, incluyendo un comentario que indica qué tareas se ejecutan y se facturan en su proyecto.
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # jobs run and bill here
),
tool_filter=[...],
)
Después de volver a desplegarlo, aparece un segundo muro, aún más interesante. El agente ahora sabe cómo facturar tu proyecto, pero concluye que no puede leer el conjunto de datos público en absoluto y se niega nuevamente. Esta vez está equivocado, ya que leer un conjunto de datos público desde tu propio proyecto de facturación es algo normal y permitido. El agente simplemente fue excesivamente cauteloso.
Aquí es donde vuelve a ser relevante el enfoque de utilizar las instrucciones como herramienta para resolver problemas. El problema radica en la instrucción, no en el código, porque el agente llegó a una conclusión basada en una regla que en realidad no existe. Una oración explícita en las instrucciones lo soluciona: esa oración establece que los trabajos de consulta siempre se ejecutan en el proyecto de facturación configurado, que se puede leer datos de cualquier conjunto de datos accesible, incluidos los públicos, y que leer un conjunto de datos público desde el proyecto de facturación es algo normal y nunca debería ser motivo para rechazar una solicitud.
Después de otro despliegue, el agente inspecciona el esquema, escribe la consulta de unión, la ejecuta y devuelve el producto principal junto con la consulta que utilizó. Este ejemplo demuestra que un agente puede tener el acceso técnico adecuado y, aun así, comportarse mal debido a una instrucción ambigua. La redacción precisa de las instrucciones forma parte de la ingeniería en este contexto, no es una habilidad secundaria.
Despliegue en Agent Engine
Ejecutarse en una laptop es una cosa; ejecutarse por sí solo en la infraestructura de Google es donde el agente cobra verdadera importancia. Vertex AI Agent Engine es el entorno de ejecución gestionado creado para los agentes ADK: usted entrega el agente y Google lo ejecuta, lo escala y lo mantiene activo sin necesidad de gestionar servidores.
El despliegue comienza habilitando un par de APIs y creando un bucket de pruebas donde ADK coloca el código empaquetado.
gcloud services enable aiplatform.googleapis.com storage.googleapis.com
gcloud storage buckets create gs://your-project-id-adk-staging --location=us-central1
Luego viene la orden de despliegue, que utiliza el proyecto, la región y el bucket de pruebas.
adk deploy agent_engine \
--project=your-project-id \
--region=us-central1 \
--staging_bucket=gs://your-project-id-adk-staging \
bq_agent_app
Se necesitan unos minutos porque se crea un contenedor en segundo plano, y la siguiente trampa se encuentra dentro de ese contenedor.
Trampa 5: el contenedor no sabe nada sobre tu portátil
La primera ejecución de Agent Engine termina con una caída, debido al mismo error cannot import name 'dataplex_v1' que parecía haberse resuelto. Una implementación no puede ver qué está instalado en la máquina del desarrollador; solo conoce los paquetes mencionados en un requirements.txt ubicado dentro de la carpeta del agente. Por lo tanto, el portátil contenía las dependencias mientras que el contenedor no. Esta lección es aplicable a todos los targets de GCP, ya sean Cloud Functions, Cloud Run o Agent Engine. Funcionar localmente y funcionar en producción son situaciones diferentes, y una lista explícita de dependencias conecta ambas.
La solución es especificar claramente los paquetes.
# requirements.txt
google-adk
google-cloud-bigquery
google-cloud-dataplex
db-dtypes
Vuelve a desplegar y el contenedor instalará lo que necesite.
Trampa 6: el agente ya no eres tú
La última trampa enseña lo más importante sobre los agentes en entornos de producción. El despliegue tiene éxito, pero una consulta introducida en el Cloud Playground es rechazada por BigQuery debido a la falta del permiso bigquery.jobs.create. Eso no es un error; es que IAM funciona tal como está diseñado.
En una computadora portátil, el agente actuaba como tú, utilizando todos tus permisos. Después del despliegue, funciona bajo una cuenta de servicio, esencialmente una identidad de robot, y esa identidad no cuenta con derechos en BigQuery al principio. Este diseño es lo que hace seguros a los agentes cerca de datos sensibles. Un agente no puede ir más allá de lo que permite su identidad, nada queda oculto, y IAM lo limita del mismo modo en que lo hace con cualquier persona.
La cuenta de servicio necesita dos roles: uno para ejecutar consultas y otro para leer datos. El primer bloque concede roles/bigquery.jobUser.
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.jobUser"
El segundo otorga roles/bigquery.dataViewer.
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.dataViewer"
Espera un minuto a que el cambio se propague y vuelve a preguntar en el Playground. El agente responde entonces desde la nube, ejecutándose completamente en la infraestructura de Google mientras la laptop permanece cerrada.
Lecciones del proceso de desarrollo
- Un agente no es un chatbot. La diferencia radica en el bucle mediante el cual el modelo razona, llama a una herramienta, ve el resultado y lo repite hasta poder responder.
- La instrucción realiza la mayor parte del trabajo real. Código e acceso idénticos producen comportamientos muy diferentes según cómo esté redactada la instrucción, y eliminar nombres de columnas inventados y rechazos innecesarios fue pura labor de formulación de instrucciones.
- El hecho de que algo esté incluido por defecto no garantiza que esté instalado. El conjunto de herramientas de BigQuery viene con ADK, pero depende de
google-cloud-bigquery,google-cloud-dataplexydb-dtypes; por lo tanto, instálalos primero. - El entorno local y el de producción son mundos diferentes. En el entorno local, el agente funciona con tu identidad y tus paquetes. Una vez desplegado, opera como una cuenta de servicio con solo lo que se indica en
requirements.txt, y ambas situaciones se gestionan de forma explícita. - IAM es la garantía de seguridad. Un agente desplegado no puede superar los derechos de su cuenta de servicio, por lo que cada acceso es explícito, rastreable y revocable, al igual que el de un usuario humano. Esa es la tranquilidad que necesitan los interesados empresariales antes de permitir que un agente acceda a datos reales.
Un proyecto que comienza como una pregunta sobre cómo obtener respuestas en lenguaje natural desde BigQuery termina siendo un agente de Vertex AI completamente desplegado que responde a preguntas empresariales sin necesidad de SQL ni extracción manual. Todo está basado en GCP nativo, por lo que un equipo ya familiarizado con BigQuery no está adoptando una nueva tecnología, sino que simplemente añade Gemini a las herramientas que ya utiliza. Los tutoriales no mencionan ninguno de estos problemas: la versión de Python, las dependencias no declaradas, la confusión entre proyectos de facturación y la cuenta de servicio sin los derechos adecuados. Saber dónde están las deficiencias ahorra horas, así que comience con algo sencillo, provoque errores y lea los mensajes de error.
Lecturas relacionadas
- Agentes Bedrock: Resumen de memoria, límites versionados y base de conocimientos — Controles de agentes Bedrock impulsados por Terraform: memoria de sesión con un prompt personalizado para resumir, límites versionados con implementación mediante detectar-luego-bloquear, y RAG respaldado por S3.
- Notas prácticas: Google ADK explicado: construyendo sistemas multi-agente con — Guía paso a paso de las Notas prácticas: Google ADK explicado: construyendo sistemas multi-agente con: contratos, verificaciones y espacios de código listos para usar para los equipos que implementan este patrón.