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

El enriquecimiento de metadatos en Knowledge Catalog (anteriormente, Dataplex Universal Catalog) te permite proporcionar contexto de datos estructurados para que los agentes de IA puedan fundamentar sus respuestas en fuentes confiables y certificadas. En este instructivo, adjuntarás aspectos personalizados a tablas de BigQuery de ejemplo y usarás la CLI de Antigravity para probar cómo un agente de IA aplica tus reglas de administración.

Objetivos

  • Implementar un data lake realista de varios niveles en BigQuery 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 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 consola de Google Cloud , haz clic en Activar Cloud Shell en la barra de herramientas de la parte 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 orienten a tu proyecto de 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 servicios de Google Cloud 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 de DevRel deGoogle Cloud .

    Descarga el código y las secuencias de comandos de la infraestructura desde GitHub. Usa una confirmación de la compra 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. Los agentes de IA pueden razonar, pero comienzan con cero 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 decenas de tablas llamadas "ingresos" en tus bases de datos, que van desde informes oficiales hasta datos de prueba sin procesar. Si el agente elige la tabla con el nombre que suena más parecido, puede devolver respuestas convincentemente incorrectas basadas en fuentes no verificadas.

Para simular esta situación, necesitas una combinación de data marts "oficiales" y tablas de "zona de pruebas" no confiables. Usa 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 y analyst_sandbox) y propaga 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 administrar. Para un agente de IA, todas las tablas se ven exactamente iguales.

Define un tipo de aspecto personalizado en Knowledge Catalog

Ahora, define las reglas de tu administración de datos. Para ello, en Knowledge Catalog, creas un tipo de aspecto, que es una plantilla de metadatos reutilizable con tipos definidos.

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

Se 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 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 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 de data lakes

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. Solo son objetos con columnas.

Para distinguirlas, aplicas 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 aspectos

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 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 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 empresarial 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 empresarial, como establecer 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 por 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 consola de Google Cloud

Antes de continuar, verifica que la secuencia de comandos haya aplicado los aspectos correctamente en la consola de 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 el escenario "Gold Internal" que aplicaste.

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.

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 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 las 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 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 sentencia de SQL. Esta lógica de búsqueda previa evita que el agente adivine nombres de tablas o genere respuestas incorrectas a partir 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 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

Ejecuta situaciones de verificación del contexto de datos

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

Situación 1: Recupera datos certificados de nivel oro

Veamos si la CLI de Antigravity puede encontrar los datos más confiables para una reunión de junta directiva 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 debería omitir los datos sin procesar y encontrar fin_monthly_closing_internal. Para ello, compara tu solicitud de datos "finalized" y "confidential" con las etiquetas GOLD_CRITICAL y INTERNAL_ONLY que aplicaste antes.

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

Imagina que quieres compartir datos de forma externa. Debes 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 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: Recupera datos de transmisión 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: Explora datos de la zona de pruebas sin certificación

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

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 BRONZE_ADHOC y está marcada de forma explícita con is_certified: false.

Cuando termines de realizar las 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 ella.

  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

¿Qué sigue?