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

Los agentes de IA pueden razonar, pero comienzan sin ningún conocimiento sobre tu empresa específica. Imagina que le preguntas 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 devolver 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 proporcionan 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

  • Implementa un data lake realista de varios niveles para realizar pruebas.
  • Diseña y registra plantillas de metadatos personalizadas (tipos de aspectos) en Knowledge Catalog para distinguir los productos de datos oficiales de las tablas sin procesar de la zona de pruebas.
  • Verifica las reglas de administración de datos 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, 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 tus variables PROJECT_ID y REGION para que todos los comandos futuros se dirijan a tu proyecto Google Cloud específico.

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

  3. Habilita los Google Cloud servicios necesarios.

    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 repositorio de demostraciones deGoogle Cloud DevRel.

    Descarga el código y las secuencias de comandos de la infraestructura desde 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

Crea un data lake de muestra

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 "sandbox" 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 propagado, pero sin administración. Para un agente de IA, todas las tablas se ven exactamente iguales.

Crea la plantilla de administración de datos (tipo de aspecto)

Ahora, define 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 escritura segura.

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 aspectos

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 sigan siendo estructurados y legibles por máquinas.

Registra el tipo de aspecto

Ejecuta el siguiente comando de 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"

Aplica la administración de datos

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 distinguirlas, se aplican aspectos, que adjuntan etiquetas de metadatos certificados 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 cargas útiles de administración de datos

Las claves de aspectos de Knowledge Catalog deben ser únicas a nivel global (con el prefijo de tu ID de 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).

Aplica aspectos con la CLI

  1. Antes de ejecutar la secuencia de comandos, observa los datos que adjuntarás 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 se define explícitamente el contexto comercial, por ejemplo, cómo se establece is_certified: true y se asigna el nivel GOLD_CRITICAL. Esto le brinda al agente de IA reglas claras y estructuradas para evaluar en lugar de adivinar en función de los nombres de las tablas.

  2. Ejecuta la secuencia de comandos de la aplicación. Esta secuencia de comandos itera 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 metadatos

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

  1. Abre la página Knowledge Catalog en la consola de Google Cloud . 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 que se encuentra en la parte inferior, busca el aspecto official-data-product-spec. Confirma que los valores coincidan con la situación de "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 tu contexto de datos con la CLI de Antigravity

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

Instala el complemento de servicio

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 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 datos, inspecciona el archivo SKILL.md:

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

Observa que le indica al modelo que siga estrictos bucles de la fase 1 (verificación de metadatos) y la 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 prioridad de la búsqueda evita que el agente adivine nombres de tablas o alucine respuestas de fuentes no verificadas.

Inicia la CLI de Antigravity y prueba situaciones

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 skill desde el directorio .agents/skills:

agy

Verifica la instalación

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

/mcp

El resultado debería mostrar knowledge-catalog como un complemento activo con sus herramientas disponibles:

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

Probarlo

Ahora es el momento de ver tu contexto de datos en acción. Pega estas instrucciones en la sesión de la CLI de Antigravity una por una.

Caso 1: Cómo encontrar datos de referencia

Comprueba 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 anteriormente.

Situación 2: Divulgación pública

Supongamos que quieres compartir datos de forma externa. Debes asegurarte de que la CLI no filtre 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 la mayor cantidad de detalles, la CLI debe omitirla. Debería dirigirte a fin_quarterly_public_report porque es la única tabla etiquetada como EXTERNAL_READY.

Situación 3: Necesidades operativas en tiempo real

Los científicos de datos suelen necesitar la información más reciente. Comprueba 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 debería encontrar mkt_realtime_campaign_performance. Identifica la frecuencia de actualización de REALTIME_STREAMING en los metadatos.

Situación 4: Exploración de la zona de pruebas

A veces, "suficiente" es mejor que "perfecto". Comprueba si la CLI de Antigravity puede encontrar los datos sin procesar de la zona de pruebas 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 debería encontrar tmp_data_dump_v2_final_real. Sabe que esta es la opción correcta porque coincide con el nivel de 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

Realiza una limpieza

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 aspectos 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 los archivos de demostración locales:

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

Conclusión

Creaste una base de datos sólida, aplicaste un contexto estricto con metadatos y verificaste que todo funcione de forma local con la CLI de Antigravity.

¿Qué sigue?