1. Introducción
Los modelos de IA generativa son razonadores potentes, pero carecen de contexto institucional. Si un ejecutivo le pregunta a un agente de IA "¿Cuáles son nuestros ingresos del primer trimestre?", el agente podría encontrar decenas de tablas llamadas "ingresos" en tu data lake. Algunos son informes financieros rigurosos, otros son estimaciones de marketing en tiempo real y muchos son entornos de pruebas que probablemente estén obsoletos.
Sin una fundamentación explícita, un agente de IA seleccionará una tabla en función de la similitud de nombres simple, lo que generará respuestas "convincentemente incorrectas" derivadas de datos no verificados.
Este codelab forma parte de una serie de dos partes en la que se explora cómo crear un agente de IA que tenga en cuenta la administración.
En esta primera parte, crearás una base de datos. Configurarás un data lake realista y "desordenado" en BigQuery, aplicarás etiquetas de metadatos rígidas (aspectos de Knowledge Catalog) para diferenciar los datos válidos del ruido y usarás la CLI de Antigravity (AGY) para probar de forma local si el agente sigue estrictamente tus reglas de administración de datos.
Puedes leer la segunda parte de esta serie, en la que se explica cómo implementar el prototipo de agente local en una aplicación web segura y de nivel empresarial con el Protocolo de contexto del modelo (MCP) y Cloud Run. 👉 Lee la parte 2
Qué aprenderás
- Implementar un data lake realista de varios niveles con una secuencia de comandos de configuración
- Diseña y registra plantillas de metadatos personalizadas (tipos de aspectos) en Knowledge Catalog para distinguir los productos de datos oficiales de las tablas de zona de pruebas sin procesar.
- Verifica las reglas de administración de datos de forma local con la CLI de AGY antes de escribir cualquier código de aplicación.
Requisitos
- Un proyecto de Google Cloud con facturación habilitada.
- Acceso a Google Cloud Shell (la CLI de AGY está preinstalada en Cloud Shell)
- Conocimientos básicos y familiaridad con BigQuery y Knowledge Catalog
Conceptos clave
- Knowledge Catalog: Es el servicio de administración de metadatos unificado. Lo usamos para enriquecer los metadatos técnicos (esquemas) con el contexto empresarial (administración).
- Tipo de aspecto: Es una plantilla de metadatos estructurados. A diferencia de las etiquetas de texto libre, los aspectos aplican un tipado estricto (enums, booleanos), lo que los hace confiables para que las máquinas los evalúen.
2. Configuración y requisitos
Inicie Cloud Shell
Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.
En la consola de Google Cloud, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:

El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:

Esta máquina virtual está cargada con todas las herramientas para desarrolladores que necesitará. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.
Inicializa el entorno
Abre Cloud Shell y establece las variables de tu proyecto para asegurarte de que todos los comandos se orienten a la infraestructura correcta.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
Habilita las APIs
Habilita los servicios de Google Cloud necesarios para ejecutar la siguiente instrucción.
gcloud services enable \
bigquery.googleapis.com \
dataplex.googleapis.com
Clona el repositorio
Obtén el código de infraestructura y las secuencias de comandos de automatización del repositorio de GitHub. Para ahorrar espacio en el disco en Cloud Shell, solo descargaremos la carpeta específica que se necesita para este lab.
# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
Crea el data lake "desordenado"
Los entornos de datos del mundo real rara vez están limpios. Para simular la realidad, necesitamos una combinación de data marts "oficiales" y tablas de "zona de pruebas" no confiables.
Usaremos un script de configuración para implementar los conjuntos de datos y las tablas de BigQuery.
- Haz que la secuencia de comandos de configuración sea ejecutable y ejecútala. Esto creará tres conjuntos de datos de BigQuery (
finance_mart,marketing_prodyanalyst_sandbox) y propagará sus tablas con datos de muestra.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
Punto de control: Ahora tienes un data lake completamente propagado, pero sin ningún tipo de administración. Para una IA, todas las tablas se ven exactamente iguales.
3. Crea la plantilla de administración de datos (tipo de aspecto)
Ahora, definiremos algunas reglas de administración de datos. En Knowledge Catalog, esto se hace creando un tipo de aspecto, que es una plantilla de metadatos reutilizable con tipos definidos.
Registraremos esta plantilla con la CLI de gcloud para que puedas ver cómo se define.
Inspecciona el esquema de aspecto
Genera el contenido de aspect_template.json para ver la definición del esquema.
cat aspect_template.json
Se mostrará la siguiente estructura JSON:
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
...
}
]
}
Observa cómo este esquema aplica tipos de datos estrictos, como enum para el nivel de importancia (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) y un bool para is_certified. Esto garantiza que los metadatos permanezcan estructurados y legibles por máquinas.
Registra el tipo de aspecto
Ejecuta el siguiente comando gcloud para registrar esta plantilla en tu registro de Knowledge Catalog.
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
4. Aplica la administración
Este es el paso de ingeniería fundamental. Actualmente, las tablas finance_mart.fin_monthly_closing_internal y analyst_sandbox.tmp_data_dump_v2_final_real se ven idénticas para un LLM. Solo son objetos con columnas.
Como ingeniero de administración, debes adjuntar un aspecto (una etiqueta de metadatos certificada) a estas tablas para diferenciarlas. En una empresa real, automatizarías esto a través de canalizaciones de CI/CD. Simularemos esa automatización con secuencias de comandos.
Genera cargas útiles de administración
Las claves de aspecto de Knowledge Catalog deben ser únicas a nivel global (con el prefijo del ID del proyecto). La secuencia de comandos ./generate_payloads.sh generará de forma dinámica los archivos de metadatos YAML.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
Resultado:
Esto crea una carpeta "./aspect_payloads" que contiene 4 archivos YAML, que definen las situaciones de administración (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).
Aplica aspectos con la CLI
Antes de ejecutar la secuencia de comandos, veamos qué estamos aplicando para desmitificar el proceso. Ejecuta el siguiente comando para ver la estructura de la carga útil de finanzas internas:
cat aspect_payloads/fin_internal.yaml
Se mostrará el siguiente contenido.
your-project-id.us-central1.official-data-product-spec:
data:
product_tier: GOLD_CRITICAL
data_domain: FINANCE
usage_scope: INTERNAL_ONLY
update_frequency: DAILY_BATCH
is_certified: true
Observa cómo este YAML define de forma explícita el contexto empresarial, como establecer la marca is_certified: true y asignar el nivel GOLD_CRITICAL. Proporcionar al LLM reglas claras y estructuradas para evaluar en lugar de solo adivinar según los nombres de las tablas
Ahora, ejecuta la secuencia de comandos de la aplicación. Esto itera a través de las tablas de BigQuery y ejecuta el comando gcloud dataplex entries update para adjuntar estos metadatos rígidos.
chmod +x ./apply_governance.sh
./apply_governance.sh
Verificación (opcional)
Antes de continuar, verifica que los metadatos se hayan aplicado correctamente en la consola.
- Abre la página Knowledge Catalog en la consola de Google Cloud. Si no ves "Knowledge Catalog" en el menú de navegación de la izquierda, usa la barra de búsqueda que se encuentra en la parte superior de la ventana de la consola de Google Cloud, escribe "Knowledge Catalog" y selecciona el resultado en "Resultados principales" o "Productos y páginas".
- Busca
fin_monthly_closing_internal. Deberías ver la tabla de BigQuery en los resultados. Haz clic en el nombre de la tabla para ingresar a su página de detalles.

- En la página de detalles de la tabla, busca la sección "Aspectos y etiquetas opcionales" que se encuentra en la parte inferior.
- Encontrarás el aspecto
official-data-product-spec. Confirma que los valores coincidan con la situación "Gold Internal" que aplicamos.

Confirmaste que las tablas de BigQuery técnicamente idénticas (fin_monthly_closing_internal y tmp_data_dump_v2_final_real) se diferencian de forma lógica por los metadatos legibles por máquinas.
5. Configura y crea un prototipo del agente
Antes de compilar una aplicación (lo que haremos en la parte 2), verificaremos nuestra lógica de administración de datos de forma local. Debemos instalar el complemento de Knowledge Catalog y configurar la habilidad del agente.
Instalar la extensión
En Cloud Shell, instala el complemento de Knowledge Catalog. Se te pedirá que confirmes la acción y que proporciones los detalles de la configuración.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
Inspecciona la habilidad del agente
La habilidad del agente es un archivo de definición estático y reutilizable que se encuentra en .agents/skills/knowledge_catalog_governance/SKILL.md. Contiene la lógica que traduce las reglas humanas abstractas (p.ej., "Necesito datos seguros") en búsquedas técnicas estrictas.
Inspecciona el archivo para comprender el algoritmo que le estamos enseñando a la IA:
cat .agents/skills/knowledge_catalog_governance/SKILL.md
Observa que le indica de forma explícita al modelo que siga un bucle estricto de Fase 1 (Verificación de metadatos) y Fase 2 (Ejecución de consultas). El modelo debe descubrir y verificar los metadatos antes de construir cualquier SQL.
Inicia el agente y prueba las situaciones
Inicia la sesión de la CLI de AGY. Descubrirá y cargará automáticamente la habilidad desde el directorio .agents/skills.
agy
Nota: Es posible que veas que se cargan varios archivos de contexto. Esto es normal. La CLI carga la habilidad local para las reglas específicas de este proyecto, además de las instrucciones predeterminadas para el complemento de Knowledge Catalog.
Verifica la instalación
Escribe /mcp para confirmar que el complemento de Knowledge Catalog está activo. Deberías ver knowledge-catalog como un complemento activo con sus herramientas disponibles.
/mcp
Resultado esperado:
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
Situaciones de prueba (prototipado)
Pega las siguientes instrucciones en la sesión del agente en ejecución, una por una, para verificar que cumpla con tus reglas.
- Situación A (certificar los datos del director de finanzas):
"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"
Resultado esperado: El agente descubre automáticamente tu proyecto y región activos desde sus herramientas, consulta fin_monthly_closing_internal porque coincide semánticamente con GOLD_CRITICAL (preciso) y INTERNAL_ONLY (reunión de la junta directiva) en su aspecto, y lo recomienda.
- Situación B (divulgación pública):
"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"
Resultado esperado: El agente debe omitir la tabla interna mensual y seleccionar estrictamente fin_quarterly_public_report porque es el único recurso etiquetado como EXTERNAL_READY.
- Situación C (necesidades operativas):
"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"
Resultado esperado: El agente selecciona mkt_realtime_campaign_performance porque identifica la frecuencia de actualización de REALTIME_STREAMING, lo que prioriza eso por sobre el nivel GOLD_CRITICAL de los datos financieros.
- Situación D (experimentación en la zona de pruebas):
"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."
Resultado esperado: El agente selecciona tmp_data_dump_v2_final_real porque coincide semánticamente con BRONZE_ADHOC (datos sin procesar) y is_certified: false (entorno de zona de pruebas) en su aspecto.
(Para salir de la sesión de AGY, escribe /exit o /quit)
6. ¡Felicitaciones! Próximos pasos
Creaste correctamente una base de datos gobernada y demostraste que una IA puede seguir estrictamente tus reglas de metadatos con un prototipo de CLI local.
Ahora, llegaste a un punto de control. Elige el siguiente paso:
Opción A: Quiero continuar con la Parte 2 ahora mismo.
Si tienes todo listo para convertir este prototipo local en una aplicación web segura y de nivel de producción con el Protocolo de contexto del modelo (MCP) y Cloud Run, haz lo siguiente:
👉 Vínculo al codelab de la parte 2
Opción B: Realizaré la parte 2 más tarde o solo quería completar la parte 1.
Si quieres detenerte por hoy y evitar costos de la nube, debes limpiar tus recursos.
¡No te preocupes! En la parte 2, proporcionaremos una "secuencia de comandos de vía rápida" que reconstruirá por completo este entorno de la parte 1 en solo 2 minutos para que puedas retomar exactamente donde lo dejaste.
👉 Continúa con la sección de limpieza.
7. Realiza una limpieza (solo para la opción B)
Si te detienes aquí, destruye los recursos para evitar que se generen cargos.
Destruye el data lake
Si estás en la sesión de la CLI de AGY, presiona Ctrl+C dos veces o escribe /quit para salir de ella. Luego, ejecuta los siguientes comandos:
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
Desinstala el complemento de la CLI de AGY y quita los archivos locales
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos