Usa la CLI de Antigravity para probar el contexto de los datos

Los agentes de IA pueden razonar, pero comienzan sin conocimiento sobre tu empresa específica. Imagina preguntarle a un agente: "¿Cuáles son nuestros ingresos del primer trimestre?". Sin orientación, el agente podría elegir entre docenas de tablas llamadas "ingresos" en tus bases de datos, que van desde informes oficiales hasta datos de prueba desordenados. Si el agente elige la tabla con el nombre que suena más parecido, podría mostrar respuestas convincentemente incorrectas basadas en fuentes no verificadas.

El enriquecimiento de metadatos es la solución a este problema de contexto. En este instructivo, configurarás aspectos que proporcionen este contexto y usarás la CLI de Antigravity para probar el contexto de los datos y verificar que un agente pueda fundamentar con precisión sus respuestas en datos confiables y certificados.

Objetivos

  • Implementar un data lake realista de varios niveles en BigQuery para realizar pruebas
  • Diseñar y registrar plantillas de metadatos personalizadas (tipos de aspecto) en Knowledge Catalog para distinguir los productos de datos oficiales de las tablas de zona de pruebas sin procesar
  • Verificar las reglas de administración de datos y la fundamentación del agente de IA con la CLI de Antigravity (agy).

Antes de comenzar

Antes de comenzar, asegúrate de hacer lo siguiente:

Para completar este instructivo, también debes tener conocimientos básicos de BigQuery y Knowledge Catalog.

Prepara el entorno

En este instructivo, se usa Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube. La CLI de Antigravity (agy) está preinstalada en Google Cloud Shell.

  1. En la Google Cloud consola de, haz clic en Activar Cloud Shell en la barra de herramientas de la esquina superior derecha. El aprovisionamiento y la conexión al entorno demorarán unos minutos.

  2. En Cloud Shell, configura las variables PROJECT_ID y REGION para que todos los comandos futuros apunten a tu Google Cloud proyecto específico.

    export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

  3. Habilita los servicios necesarios Google Cloud .

    gcloud services enable \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

  4. Clona el Google Cloud repositorio de DevRel Demos.

    Descarga el código de infraestructura y las secuencias de comandos de GitHub. Usa una extracción dispersa para extraer solo la carpeta específica que necesitas para este instructivo.

    # 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 you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

Implementa un data lake de muestra en BigQuery

Los entornos de datos del mundo real rara vez están limpios. Para simular la realidad, necesitas una combinación de data marts "oficiales" y tablas de "zona de pruebas" no confiables.

Usarás una secuencia de comandos 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 crea tres conjuntos de datos de BigQuery (finance_mart, marketing_prod, analyst_sandbox) y completa sus tablas con datos de muestra:

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Ahora tienes un data lake completamente completo, pero sin administración. Para un agente de IA, todas las tablas se ven exactamente iguales.

Define un tipo de aspecto personalizado en Knowledge Catalog

Ahora, definirás las reglas de tu administración de datos. Para ello en Knowledge Catalog, crea un tipo de aspecto, que es una plantilla de metadatos reutilizable y con tipo seguro.

En esta sección, registrarás esta plantilla con la CLI de gcloud para que puedas ver cómo se define.

Inspecciona el esquema de la plantilla de aspecto

Genera el contenido de aspect_template.json para ver la definición del esquema:

cat aspect_template.json

Muestra 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 criticidad (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) y un bool para is_certified. Esto garantiza que los metadatos permanezcan estructurados y legibles por máquina.

Registra el tipo de aspecto en Knowledge Catalog

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 data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

Adjunta aspectos de administración a las tablas del data lake

Este es el paso de ingeniería fundamental. En este momento, las tablas finance_mart.fin_monthly_closing_internal y analyst_sandbox.tmp_data_dump_v2_final_real se ven idénticas para un agente de IA. Son solo objetos con columnas.

Para distinguirlos, aplica aspectos, que adjuntan etiquetas de metadatos certificadas a estas tablas para diferenciarlas. En una empresa real, automatizarías esto con canalizaciones de CI/CD. En este instructivo, simularás esa automatización con secuencias de comandos.

Genera las cargas útiles de metadatos de aspecto

Las claves de aspecto de Knowledge Catalog deben ser únicas a nivel global (con el prefijo de tu ID del proyecto). La secuencia de comandos ./generate_payloads.sh genera de forma dinámica los archivos de metadatos YAML:

chmod +x ./generate_payloads.sh
./generate_payloads.sh

Esto crea un directorio aspect_payloads/ que contiene 4 archivos YAML que definen diferentes situaciones de administración de datos (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Adjunta aspectos a las tablas de BigQuery

  1. Antes de ejecutar la secuencia de comandos, observa los datos que adjuntas a las tablas. Ejecuta el siguiente comando para ver los metadatos de tus datos financieros internos:

    cat aspect_payloads/fin_internal.yaml

    El archivo YAML define el contexto comercial de la tabla:

    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 esto define explícitamente el contexto comercial, como configurar is_certified: true y asignar el nivel GOLD_CRITICAL. Esto le da al agente de IA reglas claras y estructuradas para evaluar en lugar de adivinar según los nombres de las tablas.

  2. Ejecuta la secuencia de comandos de la aplicación. Esta secuencia de comandos itera a través de tus tablas de BigQuery y usa el comando gcloud dataplex entries update para adjuntar tus cargas útiles de metadatos a cada tabla:

    chmod +x ./apply_governance.sh
./apply_governance.sh

Verifica los aspectos aplicados en la Google Cloud consola

Antes de continuar, verifica que la secuencia de comandos haya aplicado los aspectos correctamente en la Google Cloud consola de:

  1. Abre la página Knowledge Catalog en la Google Cloud consola. Puedes usar la barra de búsqueda superior para encontrarlo.
  2. Busca fin_monthly_closing_internal. Selecciona el nombre de la tabla de BigQuery en los resultados para abrir su página de detalles.
  3. En la sección Aspectos y etiquetas opcionales en la parte inferior, busca el aspecto official-data-product-spec. Confirma que los valores coincidan con la situación "Gold Internal" que aplicaste.

Ahora confirmaste que las tablas de BigQuery técnicamente idénticas (fin_monthly_closing_internal y tmp_data_dump_v2_final_real) se diferencian lógicamente por metadatos legibles por máquina.

Prueba el contexto de tus datos con la CLI de Antigravity

Antes de compilar una aplicación, puedes verificar la lógica de administración de datos de forma local con la CLI de Antigravity. Para ello, instala el complemento de Knowledge Catalog y configura la habilidad del agente.

Instala el complemento de Knowledge Catalog

En Cloud Shell, instala el complemento de servicio:

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

Inspecciona la definición de 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 reglas humanas abstractas como "Necesito datos seguros" en búsquedas técnicas estructuradas.

Para verificar la configuración de la habilidad y comprender cómo funciona el contexto de los datos, inspecciona el archivo SKILL.md:

cat .agents/skills/knowledge-catalog-governance/SKILL.md

Observa que le indica al modelo que siga bucles estrictos 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 instrucción SQL. Esta lógica de búsqueda primero evita que el agente adivine los nombres de las tablas o alucine respuestas de fuentes no verificadas.

Inicia la sesión de la CLI de Antigravity

Inicia la sesión de la CLI de Antigravity. Como estás en la carpeta del proyecto, la CLI descubre y carga automáticamente la habilidad desde el directorio .agents/skills:

agy

Verifica la instalación del complemento en la CLI

En el símbolo del sistema de la CLI de Antigravity, confirma que el complemento esté activo. Escribe /mcp para enumerar las herramientas y los complementos configurados:

/mcp

El resultado debe mostrar knowledge-catalog como un complemento activo con sus herramientas disponibles:

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Ejecuta situaciones de verificación del contexto de los datos

Ahora es el momento de ver el contexto de tus datos en acción. Pega estos mensajes uno por uno en la sesión de la CLI de Antigravity.

Caso 1: Recupera datos certificados de nivel oro

Observa si la CLI de Antigravity puede encontrar los datos más confiables para una reunión de la junta de alto riesgo:

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?

La CLI debe omitir los datos sin procesar y encontrar fin_monthly_closing_internal. Para ello, compara tu solicitud de datos "finalizados" y "confidenciales" con las etiquetas GOLD_CRITICAL y INTERNAL_ONLY que aplicaste antes.

Caso 2: Restringe la recuperación a datos aprobados de forma externa

Imagina que quieres compartir datos de forma externa. Quieres asegurarte de que la CLI no deje escapar ningún secreto interno:

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?

Aunque la tabla interna tiene más detalles, la CLI debe omitirla. Debería dirigirte a fin_quarterly_public_report porque es la única tabla etiquetada como EXTERNAL_READY.

Caso 3: Recupera datos de transmisión en tiempo real

Los científicos de datos suelen necesitar la información más reciente. Observa si la CLI de Antigravity comprende la diferencia entre un lote diario y una transmisión en vivo:

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?

La CLI debe encontrar mkt_realtime_campaign_performance. Identifica la frecuencia de actualización REALTIME_STREAMING en los metadatos.

Caso 4: Explora datos de zona de pruebas no certificados

A veces, "suficientemente bueno" es mejor que "perfecto". Observa si la CLI de Antigravity puede encontrar los datos de zona de pruebas sin procesar para algún trabajo experimental de AA:

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.

La CLI debe encontrar tmp_data_dump_v2_final_real. Sabe que esta es la opción correcta porque coincide con el nivel BRONZE_ADHOC y está marcada explícitamente con is_certified: false.

Cuando termines de hacer pruebas, puedes salir de la sesión de la CLI:

/quit

Limpia

Sigue estos pasos para evitar cargos recurrentes:

  1. Si estás en la sesión de la CLI de Antigravity, presiona Ctrl+C dos veces o escribe /quit para salir de la sesión.

  2. Ejecuta la secuencia de comandos de limpieza para destruir las tablas, los conjuntos de datos y los tipos de aspecto de Knowledge Catalog de BigQuery que se crearon en este instructivo:

    chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

  3. Desinstala el complemento de servicio y quita tus archivos de demostración locales:

    agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos

¿Qué sigue?