Utilizza Antigravity CLI per testare il contesto dei dati

Gli agenti AI possono ragionare, ma iniziano senza alcuna conoscenza della tua azienda specifica. Immagina di chiedere a un agente: "Qual è il nostro fatturato del primo trimestre?" Senza indicazioni, l'agente potrebbe scegliere tra decine di tabelle denominate "fatturato" 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 Antigravity CLI per testare il contesto dei dati e verificare che un agente possa basare con precisione le sue risposte su dati attendibili e certificati.

Obiettivi

• Eseguire il deployment di un data lake realistico a più livelli in BigQuery per i test.
• Progettare e registrare modelli di metadati personalizzati (tipi di aspetto) in Knowledge Catalog per distinguere i prodotti di dati ufficiali dalle tabelle sandbox non elaborate.
• Verificare le regole di governance dei dati e la base dell'agente AI utilizzando Antigravity CLI (agy).

Prima di iniziare

Prima di iniziare, assicurati di:

• Scegliere un Google Cloud progetto per questo tutorial.
• Verificare che la fatturazione sia abilitata per il progetto.

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. Il Antigravity CLI (agy) è preinstallato in Google Cloud Shell.

1. Dalla Google Cloud console, fai clic su Attiva Cloud Shell in 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 siano destinati al tuo specifico Google Cloud progetto.

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

3. Abilita i servizi necessari 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 il Google Cloud repository DevRel Demos.

   Scarica il codice e gli script dell'infrastruttura da GitHub. Utilizza un checkout sparse per estrarre solo la cartella specifica di cui hai bisogno 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
   

Eseguire il deployment di un data lake di esempio in BigQuery

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.

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

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

Ora hai un data lake completamente compilato, ma non regolamentato. Per un agente AI, tutte le tabelle hanno lo stesso aspetto.

Definire un tipo di aspetto personalizzato in Knowledge Catalog

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

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

Esaminare lo schema del modello di aspetto

Genera l'output dei contenuti di aspect_template.json per visualizzare la definizione dello schema:

cat aspect_template.json

Viene visualizzata 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",
      "...": "..."
    }
  ]
}

Tieni presente che questo schema applica tipi di dati rigorosi, come 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.

Registrare il tipo di aspetto in Knowledge Catalog

Esegui il seguente 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"

Collegare gli aspetti di governance alle tabelle del data lake

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

Per distinguerli, 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.

Generare 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/ contenente 4 file YAML che definiscono diversi scenari di governance dei dati (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Collegare gli aspetti alle tabelle BigQuery

1. Prima di eseguire lo script, esamina i dati che stai collegando alle tabelle. Esegui il comando seguente 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
   

   Tieni presente che 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é indovinare in base ai 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
   

Verificare gli aspetti applicati nella Google Cloud console

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

1. Apri la pagina Knowledge Catalog nella Google Cloud console. Puoi utilizzare la barra di ricerca in alto per trovarla.
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, trova l'aspetto official-data-product-spec. Verifica che i valori corrispondano allo scenario "Gold Internal" che hai applicato.

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

Testare il contesto dei dati con Antigravity CLI

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

Installare 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

Esaminare 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 le 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 loop rigorosi di Fase 1 (verifica dei metadati) e Fase 2 (esecuzione delle query). Il modello deve scoprire e verificare i metadati prima di creare qualsiasi istruzione SQL. Questa logica di ricerca impedisce all'agente di indovinare i nomi delle tabelle o di generare risposte da fonti non verificate.

Avviare la sessione di 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

Nota: potresti vedere il caricamento di più file di contesto. È normale. L'interfaccia a riga di comando carica la skill locale per le regole specifiche di questo progetto, oltre alle istruzioni predefinite per il plug-in del servizio.

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

Al 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

Eseguire scenari di verifica del contesto dei dati

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

Suggerimento: se ti viene richiesto di autorizzare l'utilizzo dello strumento, seleziona "2. Sì e consenti sempre 'knowledge-catalog/search_entries' in questa conversazione" per eseguire i test senza dover approvare ogni passaggio.

Scenario 1: recuperare i dati certificati di livello Gold

Verifica se Antigravity CLI riesce a trovare i dati più attendibili per una riunione del consiglio di amministrazione ad alto rischio:

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?

L'interfaccia a riga di comando deve ignorare i dati non elaborati e trovare fin_monthly_closing_internal. Per farlo, confronta la tua richiesta di dati "finalizzati" e "riservati" con i tag GOLD_CRITICAL e INTERNAL_ONLY che hai applicato in precedenza.

Scenario 2: limitare il recupero ai dati approvati esternamente

Supponiamo che tu voglia condividere i dati esternamente. Devi assicurarti che l'interfaccia a riga di comando non riveli segreti interni:

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 i dettagli più completi, l'interfaccia a riga di comando deve ignorarla. Dovrebbe indirizzarti a fin_quarterly_public_report perché è l'unica tabella con il tag EXTERNAL_READY.

Scenario 3: recuperare i dati di streaming in tempo reale

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

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

Scenario 4: esplorare i dati sandbox non certificati

A volte "abbastanza buono" è meglio di "perfetto". Verifica se Antigravity CLI riesce a trovare i dati sandbox non elaborati 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 deve 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 dei test, puoi uscire dalla sessione dell'interfaccia a riga di comando:

/quit

Libera spazio

Per evitare addebiti ricorrenti:

1. Se ti trovi nella sessione di Antigravity CLI, 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

• Prova altri casi d'uso di Knowledge Catalog.