Utilizza Antigravity CLI per testare il contesto dei dati

L'arricchimento dei metadati in Knowledge Catalog (in precedenza Dataplex Universal Catalog) ti consente di fornire un contesto di dati strutturati in modo che gli agenti AI possano basare le loro risposte su fonti attendibili e certificate. In questo tutorial, collegherai aspetti personalizzati a tabelle BigQuery di esempio e utilizzerai l'Antigravity CLI per testare il modo in cui un agente AI applica le tue regole di governance.

Obiettivi

  • Esegui il deployment di un data lake multilivello realistico in BigQuery per i test.
  • Progetta e registra modelli di metadati personalizzati (tipi di aspetto) in Knowledge Catalog per distinguere i prodotti di dati ufficiali dalle tabelle sandbox non elaborate.
  • Verifica le regole di governance dei dati e il grounding dell'agente AI utilizzando l'Antigravity CLI (agy).

Prima di iniziare

Prima di iniziare, assicurati di:

Per completare questo tutorial, devi anche avere una conoscenza di base di BigQuery e Knowledge Catalog.

prepara l'ambiente

Questo tutorial utilizza Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud. L'Antigravity CLI (agy) è preinstallata in Google Cloud Shell.

  1. Nella console Google Cloud , fai clic su Attiva Cloud Shell nella barra degli strumenti in alto a destra. Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente.

  2. In Cloud Shell, imposta le variabili PROJECT_ID e REGION in modo che tutti i comandi futuri abbiano come target il tuo progetto Google Cloud specifico.

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

  3. Abilita i servizi Google Cloud necessari.

    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 il repositoryGoogle Cloud DevRel Demos.

    Scarica il codice e gli script dell'infrastruttura da GitHub. Utilizza un checkout sparse per eseguire il pull solo della cartella specifica necessaria per questo tutorial.

    # 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

Esegui il deployment di un data lake di esempio in BigQuery

Gli ambienti di dati reali sono raramente puliti. Gli agenti AI possono ragionare, ma partono da zero conoscenze sulla tua azienda specifica. Immagina di chiedere a un agente: "Quali sono le nostre entrate del primo trimestre?" Senza indicazioni, l'agente potrebbe scegliere tra decine di tabelle denominate "entrate" nei tuoi database, che vanno dai report ufficiali ai dati di test non elaborati. Se l'agente sceglie la tabella con il nome dal suono più simile, può restituire risposte errate in modo convincente basate su fonti non verificate.

Per simulare questo scenario, hai bisogno di un mix di data mart "ufficiali" e tabelle "sandbox" non attendibili. Utilizza uno script di configurazione per eseguire il deployment dei set di dati e delle tabelle BigQuery.

Rendi eseguibile lo script di configurazione ed eseguilo. Vengono creati tre set di dati BigQuery (finance_mart, marketing_prod, analyst_sandbox) e le relative tabelle vengono compilate con dati campionati:

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

Ora hai un data lake completamente popolato, ma non governato. Per un agente AI, ogni tabella ha esattamente lo stesso aspetto.

Definisci un tipo di aspetto personalizzato in Knowledge Catalog

Ora devi definire le regole della governance dei dati. Per farlo in Knowledge Catalog, devi creare un tipo di aspetto, ovvero un modello di metadati riutilizzabile e con un tipo di dati ben definito.

In questa sezione, registrerai questo template utilizzando l'interfaccia a riga di comando gcloud per vedere come è definito.

Esamina lo schema del template di aspetto

Visualizza i contenuti di aspect_template.json per vedere la definizione dello schema:

cat aspect_template.json

Mostra la seguente struttura 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",
      "...": "..."
    }
  ]
}

Nota come questo schema applica tipi di dati rigorosi, come enum per il livello di criticità (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) e bool per is_certified. In questo modo, i metadati rimangono strutturati e leggibili da macchina.

Registra il tipo di aspetto in Knowledge Catalog

Esegui questo comando gcloud per registrare questo modello nel registro di 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"

Collega gli aspetti di governance alle tabelle del data lake

Questo è il passaggio di progettazione fondamentale. Al momento, la tabella finance_mart.fin_monthly_closing_internal e la tabella analyst_sandbox.tmp_data_dump_v2_final_real sembrano identiche a un agente AI. Sono solo oggetti con colonne.

Per distinguerle, applichi gli aspetti, che collegano etichette di metadati certificate a queste tabelle per differenziarle. In un'azienda reale, questa operazione verrebbe automatizzata con pipeline CI/CD. In questo tutorial, simulerai l'automazione con gli script.

Genera i payload dei metadati degli aspetti

Le chiavi degli aspetti di Knowledge Catalog devono essere univoche a livello globale (con il prefisso dell'ID progetto). Lo script ./generate_payloads.sh genera dinamicamente i file di metadati YAML:

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

Viene creata una directory aspect_payloads/ che contiene 4 file YAML che definiscono diversi scenari di governance dei dati (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Collega gli aspetti alle tabelle BigQuery

  1. Prima di eseguire lo script, esamina i dati che stai collegando alle tabelle. Esegui questo comando per visualizzare i metadati dei dati finanziari interni:

    cat aspect_payloads/fin_internal.yaml

    Il file YAML definisce il contesto aziendale della tabella:

    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

    Nota come questo definisce esplicitamente il contesto aziendale, ad esempio impostando is_certified: true e assegnando il livello GOLD_CRITICAL. In questo modo, l'agente AI riceve regole chiare e strutturate da valutare, anziché dover indovinare in base ai nomi delle tabelle.

  2. Esegui lo script dell'applicazione. Questo script esegue l'iterazione delle tabelle BigQuery e utilizza il comando gcloud dataplex entries update per collegare i payload dei metadati a ogni tabella:

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

Verifica gli aspetti applicati nella console Google Cloud

Prima di procedere, verifica che lo script abbia applicato correttamente gli aspetti nella console Google Cloud :

  1. Apri la pagina Knowledge Catalog nella console Google Cloud . Per trovarla, puoi utilizzare la barra di ricerca in alto alla pagina.
  2. Cerca fin_monthly_closing_internal. Seleziona il nome della tabella BigQuery nei risultati per aprire la relativa pagina dei dettagli.
  3. Nella sezione Tag e aspetti facoltativi in basso, individua l'aspetto official-data-product-spec. Verifica che i valori corrispondano allo scenario "Gold Internal" che hai applicato.

Ora hai confermato che le tabelle BigQuery tecnicamente identiche (fin_monthly_closing_internal e tmp_data_dump_v2_final_real) sono differenziate logicamente dai metadati leggibili da macchina.

Testa il contesto dei dati con l'interfravity CLI

Prima di creare un'applicazione, puoi verificare la logica di governance dei dati localmente con l'interfaccia a riga di comando Antigravity. Per farlo, installa il plug-in Knowledge Catalog e configura la skill dell'agente.

Installa il plug-in Knowledge Catalog

In Cloud Shell, installa il plug-in del servizio:

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Esamina la definizione della skill dell'agente

La skill dell'agente è un file di definizione statico e riutilizzabile che si trova in .agents/skills/knowledge-catalog-governance/SKILL.md. Contiene la logica che traduce regole umane astratte come "Ho bisogno di dati sicuri" in ricerche tecniche strutturate.

Per controllare la configurazione della skill e capire come funziona il contesto dei dati, esamina il file SKILL.md:

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

Nota che indica al modello di seguire cicli rigorosi di Fase 1 (Verifica dei metadati) e Fase 2 (Esecuzione della query). Il modello deve rilevare e verificare i metadati prima di creare qualsiasi istruzione SQL. Questa logica basata sulla ricerca impedisce all'agente di indovinare i nomi delle tabelle o di generare allucinazioni con risposte provenienti da fonti non verificate.

Avvia la sessione Antigravity CLI

Avvia la sessione di Antigravity CLI. Poiché ti trovi nella cartella del progetto, l'interfaccia a riga di comando rileva e carica automaticamente la skill dalla directory .agents/skills:

agy

Verifica l'installazione del plug-in nell'interfaccia a riga di comando

Nel prompt di Antigravity CLI, verifica che il plug-in sia attivo. Digita /mcp per elencare gli strumenti e i plug-in configurati:

/mcp

L'output dovrebbe mostrare knowledge-catalog elencato come plug-in attivo con i relativi strumenti disponibili:

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

Esegui scenari di verifica del contesto dei dati

Ora è il momento di vedere il contesto dei dati in azione. Incolla questi prompt nella sessione dell'interfaccia a riga di comando di Antigravity uno alla volta.

Scenario 1: recupera i dati certificati di livello Gold

Scopri se l'interfaccia a riga di comando di Antigravity riesce a trovare i dati più affidabili per una riunione del consiglio di amministrazione di alto livello:

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 dovrebbe saltare i dati non elaborati e trovare fin_monthly_closing_internal. A questo scopo, abbina la tua richiesta di dati "finalizzati" e "riservati" ai tag GOLD_CRITICAL e INTERNAL_ONLY che hai applicato in precedenza.

Scenario 2: limita il recupero ai dati approvati esternamente

Immagina di voler condividere dati esternamente. Vuoi assicurarti che l'interfaccia a riga di comando non lasci trapelare alcun secret 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?

Anche se la tabella interna contiene il maggior numero di dettagli, l'interfaccia a riga di comando deve ignorarla. Dovrebbe indirizzarti a fin_quarterly_public_report perché è l'unica tabella taggata come EXTERNAL_READY.

Scenario 3: recupera i dati in streaming in tempo reale

I data scientist hanno spesso bisogno delle informazioni più recenti. Verifica se l'Antigravity CLI comprende la differenza tra un batch giornaliero e un live streaming:

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 dovrebbe trovare mkt_realtime_campaign_performance. Identifica la frequenza di aggiornamento di REALTIME_STREAMING nei metadati.

Scenario 4: esplora i dati sandbox non certificati

A volte "abbastanza buono" è meglio di "perfetto". Controlla se l'interfaccia a riga di comando Antigravity riesce a trovare i dati non elaborati della sandbox per un lavoro di ML sperimentale:

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 dovrebbe trovare tmp_data_dump_v2_final_real. Sa che questa è la scelta giusta perché corrisponde al livello BRONZE_ADHOC ed è contrassegnata esplicitamente con is_certified: false.

Al termine del test, puoi uscire dalla sessione dell'interfaccia a riga di comando:

/quit

Esegui la pulizia

Per evitare addebiti ricorrenti, segui questi passaggi:

  1. Se ti trovi nella sessione dell'interfaccia a riga di comando di Antigravity, esci dalla sessione premendo Ctrl+C due volte o digitando /quit.

  2. Esegui lo script di pulizia per eliminare le tabelle BigQuery, i set di dati e i tipi di aspetto di Knowledge Catalog creati in questo tutorial:

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

  3. Disinstalla il plug-in del servizio e rimuovi i file demo locali:

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

Passaggi successivi