Utilizza Antigravity CLI per testare il contesto dei dati

Gli agenti AI possono ragionare, ma non hanno alcuna conoscenza specifica della tua azienda. 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 disordinati. Se l'agente sceglie la tabella con il nome più simile, potrebbe restituire risposte convincenti ma errate basate su fonti non verificate.

L'arricchimento dei metadati è la soluzione a questo problema di contesto. In questo tutorial, configurerai gli aspetti che forniscono questo contesto e utilizzerai la CLI Antigravity per testare il contesto dei dati e verificare che un agente possa basare con precisione le sue risposte su dati attendibili e certificati.

Obiettivi

  • Esegui il deployment di un data lake multi-livello realistico 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 utilizzando 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'interfaccia a riga di comando Antigravity (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. Attiva i Google Cloud servizi 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 sparso per estrarre solo la 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

Crea un data lake di esempio

Gli ambienti di dati reali sono raramente puliti. Per simulare la realtà, hai bisogno di un mix di data mart "ufficiali" e tabelle "sandbox" non attendibili.

Utilizzi 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 di esempio:

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 lo stesso aspetto.

Crea il modello di governance dei dati (tipo di aspetto)

Ora definisci le regole della governance dei dati. Per farlo in Knowledge Catalog, crea un tipo di aspetto, ovvero un modello di metadati riutilizzabile e fortemente tipizzato.

In questa sezione, registri questo modello utilizzando la CLI gcloud per vedere come è definito.

Esamina lo schema degli aspetti

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 imponga tipi di dati rigorosi, ad esempio enum per il livello di criticità (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) e un bool per is_certified. In questo modo, i metadati rimangono strutturati e leggibili dalla macchina.

Registra il tipo di aspetto

Esegui questo comando gcloud per registrare il 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"

Applica la governance dei dati

Questo è il passaggio di ingegneria fondamentale. Al momento, le tabelle finance_mart.fin_monthly_closing_internal e analyst_sandbox.tmp_data_dump_v2_final_real hanno lo stesso aspetto di un agente AI. Sono solo oggetti con colonne.

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

Genera payload di governance dei dati

Le chiavi degli aspetti del 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 quattro file YAML che definiscono diversi scenari di governance dei dati (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Applicare gli aspetti utilizzando la CLI

  1. Prima di eseguire lo script, esamina i dati che stai allegando 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 per la 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 dispone di regole chiare e strutturate da valutare anziché di ipotesi basate sui nomi delle tabelle.

  2. Esegui lo script dell'applicazione. Questo script scorre le 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 i metadati

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 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 automaticamente.

Testa il contesto dei dati con Antigravity CLI

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

Installare il plug-in del servizio

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

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Ispeziona la competenza 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

Tieni presente che indica al modello di seguire rigorosi cicli di Fase 1 (verifica dei metadati) e Fase 2 (esecuzione della query). Il modello deve rilevare e verificare i metadati prima di creare istruzioni SQL. Questa logica di ricerca prioritaria impedisce all'agente di indovinare i nomi delle tabelle o di generare risposte da fonti non verificate.

Avvia l'interfaccia a riga di comando Antigravity e gli scenari di test

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

agy

Verifica l'installazione

Nel prompt della CLI Antigravity, 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

Fai una prova

Ora è il momento di vedere il contesto dei dati in azione. Incolla questi prompt nella sessione della CLI Antigravity uno alla volta.

Scenario 1: trova i dati standard "Gold"

Scopri se la CLI Antigravity può 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 deve ignorare i dati non elaborati e trovare fin_monthly_closing_internal. A questo scopo, confronta la tua richiesta di dati "finalizzati" e "confidenziali" con i tag GOLD_CRITICAL e INTERNAL_ONLY che hai applicato in precedenza.

Scenario 2: divulgazione pubblica

Fai finta di voler condividere i dati esternamente. Vuoi assicurarti che la CLI non riveli 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, la CLI deve ignorarla. Dovrebbe indirizzarti a fin_quarterly_public_report perché è l'unica tabella taggata come EXTERNAL_READY.

Scenario 3: esigenze operative in tempo reale

I data scientist spesso hanno bisogno delle informazioni più recenti. Verifica se la CLI Antigravity 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?

L'interfaccia a riga di comando dovrebbe trovare mkt_realtime_campaign_performance. Identifica la frequenza di aggiornamento REALTIME_STREAMING nei metadati.

Scenario 4: esplorazione della sandbox

A volte "abbastanza buono" è meglio di "perfetto". Verifica se la CLI Antigravity riesce a trovare i dati non elaborati della sandbox per alcuni lavori di ML sperimentali:

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.

L'interfaccia a riga di comando 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 CLI:

/quit

Esegui la pulizia

Segui questi passaggi per evitare addebiti ricorrenti:

  1. Se ti trovi nella sessione CLI di Antigravity, esci dalla sessione premendo due volte Ctrl+C o digitando /quit.

  2. Esegui lo script di pulizia per eliminare le tabelle, 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

Conclusione

Hai creato una base di dati solida, applicato un contesto rigoroso utilizzando i metadati e verificato che tutto funzioni a livello locale utilizzando Antigravity CLI.

Passaggi successivi