Analytics con Data Agent Kit e Antigravity IDE

1. Introduzione

È lunedì mattina e il CFO ti ha appena inviato un messaggio. Il valore medio degli ordini è diminuito del 7% questo mese, ma le entrate totali sono rimaste invariate. Qualcosa non quadra e il consiglio vuole risposte entro venerdì.

La tua azienda, Cymbal Pets, è uno dei più grandi rivenditori online di articoli per animali domestici negli Stati Uniti. I dati di cui hai bisogno sono sparsi in tre servizi Google Cloud: dati transazionali in BigQuery, record di clienti e prodotti in Cloud SQL e file di marketing in Cloud Storage. In genere, per eseguire un'indagine tra più servizi come questa, è necessario passare da una console all'altra, scrivere il boilerplate di connessione e unire manualmente i risultati.

In questo codelab utilizzerai Google Cloud Data Agent Kit (DAK) nell'IDE Antigravity per analizzare l'anomalia utilizzando il linguaggio naturale. Descrivi cosa stai cercando e l'agente AI gestisce le connessioni, SQL e i join tra servizi in BigQuery, Cloud SQL e Cloud Storage. Una volta risolto il caso, chiederai all'agente di creare una pipeline dbt che metta in pratica i risultati, esegua il debug di un bug di modellazione dei dati reali e fornisca al CFO un consiglio basato su una previsione.

Non hai mai usato Antigravity? Se è la prima volta che utilizzi l'IDE, consulta il fantastico codelab Getting Started with Google Antigravity per una panoramica completa.

In questo lab proverai a:

• Scopri gli asset di dati in BigQuery, Cloud SQL e Cloud Storage utilizzando Knowledge Catalog
• Indaga su un'anomalia eseguendo query su più servizi in una singola conversazione utilizzando gli strumenti MCP
• Crea una pipeline dbt per preparare e unire i dati tra servizi diversi con modelli di staging e test automatizzati
• Esegui il debug di un problema di modellazione dei dati mentre l'agente esegue l'autodiagnosi e il refactoring di un bug di fan-out
• Prevedi le tendenze future e fornisci un suggerimento basato sui dati utilizzando AI.FORECAST di BigQuery.

Che cosa ti serve

• Un browser web come Chrome
• Un progetto cloud Google Cloud con la fatturazione abilitata
• Familiarità di base con SQL e la console Google Cloud

Questo codelab è destinato a professionisti dei dati di livello intermedio (analytics engineer, analisti di dati, data scientist).

Le risorse create in questo codelab dovrebbero costare meno di 5 $.

Scegli lo strumento:questo lab utilizza l'IDE Antigravity. A breve rilasceremo versioni alternative di questa stessa indagine pensate per Antigravity 2.0, Antigravity CLI e Claude Code.

2. Prima di iniziare

In questa sezione, eseguirai uno script di configurazione che esegue il provisioning dell'intero ambiente lab: un set di dati BigQuery con i dati degli ordini, un'istanza Cloud SQL Postgres con i dati di clienti e prodotti e un bucket Cloud Storage con i record delle campagne promozionali. Il completamento dello script richiede circa 8-10 minuti, con il provisioning di Cloud SQL come collo di bottiglia.

Avvia Cloud Shell

Utilizzerai Google Cloud Shell per eseguire lo script di configurazione.

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

2. Una volta connesso, imposta l'ID progetto e conferma l'ambiente:

gcloud config set project <<YOUR_PROJECT_ID>>
export PROJECT_ID=$(gcloud config get-value project)

Dovresti visualizzare un messaggio simile al seguente:

Your active configuration is: [cloudshell-####]
Updated property [core/project]

Clona il repository

Clona il repository del codelab nel tuo ambiente Cloud Shell:

cd ~/
git clone --filter=blob:none --no-checkout https://github.com/GoogleCloudPlatform/devrel-demos.git
cd ~/devrel-demos
git sparse-checkout init --cone
git sparse-checkout set codelabs/agentic-data-labs
git checkout main
cd codelabs/agentic-data-labs/

Esegui lo script di configurazione

Lo script di configurazione prepara l'intero ambiente lab in pochi minuti. Gestisce l'abilitazione delle API, il caricamento e l'aumento dei dati BigQuery, il caricamento degli asset promozionali in GCS e poi genera automaticamente un worker in background per eseguire il provisioning e la configurazione di Cloud SQL Postgres in background mentre inizi il codelab.

Lo script genera automaticamente e in modo sicuro una password Cloud SQL e la salva automaticamente nel file .env.

cd ~/devrel-demos/codelabs/agentic-data-labs/scripts
chmod +x setup.sh setup_sql.sh
./setup.sh

Al termine, vedrai un riepilogo dell'ambiente in primo piano:

╔══════════════════════════════════════════════════════╗
║   Base Setup complete!                               ║
╚══════════════════════════════════════════════════════╝

Your core BigQuery and GCS assets are ready.
Cloud SQL is currently provisioning in the background and will be fully ready by Step 4.

  BigQuery:   YOUR_PROJECT_ID.cymbal_pets
              ├── orders
              └── order_items

  GCS:        gs://YOUR_PROJECT_ID-cymbal-pets-raw
              └── promo_events.json

Mentre continui con i passaggi successivi del lab, il database viene sottoposto a provisioning e inizializzato in background. Puoi monitorare l'avanzamento in qualsiasi momento in un riquadro del terminale separato utilizzando:

tail -f /tmp/cloudsql_setup.log

Nota l'architettura dei dati: i dati transazionali (ordini e articoli dell'ordine) si trovano in BigQuery, mentre i dati operativi (clienti, profili di animali domestici e prodotti) si trovano in Cloud SQL. Questa suddivisione rispecchia il modo in cui i dati vengono spesso distribuiti tra i servizi nelle organizzazioni reali ed è ciò che rende interessante un'indagine cross-service.

Il set di dati di base è il set di dati di e-commerce ufficiale Cymbal Pets (~1,9 milioni di ordini per 92.000 clienti), arricchito con record business-to-business che incorporano il mistero che stai per indagare.

Riepilogo della sezione: hai eseguito lo script di configurazione per inizializzare l'ambiente lab e hai avviato il provisioning del database in background.

3. Configura l'IDE e il Data Agent Kit

Apri l'IDE Antigravity

Non devi attendere il completamento dell'operazione di Cloud SQL. Apri l'IDE Antigravity e connettilo al tuo progetto Google Cloud.

1. Se non l'hai ancora fatto, scarica e installa l'IDE Antigravity dalla pagina di download di Google Antigravity.
2. Avvia l'applicazione desktop Antigravity IDE.
3. Crea una nuova cartella vuota sul computer locale (ad es.denominata agentic-data-labs) e aprila nell'IDE scegliendo Apri cartella. che fungerà da spazio di lavoro locale per il codelab.

Installare l'estensione Data Agent Kit

L'estensione Google Cloud Data Agent Kit fornisce una profonda integrazione con i servizi di dati Google Cloud direttamente nell'editor, consentendoti di interagire con BigQuery, Cloud SQL, Cloud Storage e altro ancora senza cambiare contesto.

1. Nell'IDE Antigravity, fai clic sull'icona Estensioni nella barra delle attività all'estrema sinistra dello schermo (simile a quattro quadrati).
2. Nella barra di ricerca nella parte superiore del riquadro Estensioni, digita Google Cloud Data Agent Kit.
3. Individua l'estensione denominata Google Cloud Data Agent Kit pubblicata da googlecloudtools.
4. Fai clic sul pulsante Installa.
5. Potrebbe essere visualizzato un messaggio che chiede: "Ritieni attendibile l'editore "googlecloudtools" e le sue estensioni?". Fai clic su Considera attendibili gli editori e installa per continuare.

Una volta installato, vedrai una nuova icona Google Cloud Data Agent Kit nella barra delle attività all'estrema sinistra dell'IDE Antigravity.

Autenticare e configurare l'estensione

Dopo l'installazione, collega l'estensione al tuo progetto Google Cloud.

1. Dovrebbe aprirsi automaticamente una pagina di onboarding intitolata "Benvenuto in Google Cloud Data Agent Kit". Se non hai eseguito l'accesso al tuo account Cloud, segui le istruzioni per consentire l'accesso.
2. Nella sezione Riepilogo configurazione, individua il campo del progetto. Fai clic sul menu a discesa e seleziona il tuo progetto Google Cloud. Imposta la tua regione su us-central1. Poi seleziona Configura server MCP.

3. Nel riquadro Configurazione MCP, fai clic per attivare BigQuery e Cloud SQL. Poi fai clic su Inizia.

L'app è già installata o la pagina di benvenuto non si è aperta? Puoi aprire manualmente le impostazioni dell'estensione in qualsiasi momento. Fai clic sull'icona Google Cloud Data Agent Kit nella barra delle attività all'estrema sinistra, poi seleziona Impostazioni per attivare/disattivare la configurazione.

Nota sulle competenze/sui server MCP attivi:se hai altre competenze personalizzate o altri server MCP attivi nel tuo IDE, potrebbero interferire con il flusso previsto di questo lab. Se l'agente si comporta in modo imprevisto, valuta la possibilità di disattivarlo per questo lab.

Esplorare le opzioni di configurazione

Al termine della configurazione, verrà visualizzata la pagina "Inizia a utilizzare Google Cloud Data Agent Kit".

1. Nella sezione "Configurazione", fai clic su Inizia.
2. Si apre il riquadro Configurazione agente dati. Esplora le schede:
   • Progetto e regione:verifica l'ID progetto selezionato e controlla che le API richieste (API Cloud Storage, API BigQuery, API Catalog e API Cloud SQL Admin) siano abilitate.
   • BigQuery:configura la località predefinita per le query BigQuery. Utilizza la regione us-central1.
   • Configura i server MCP:visualizza i server MCP abilitati (BigQuery, Notebook, Cloud SQL e così via) che consentono agli agenti AI di interagire in modo sicuro con i tuoi dati.
   • Competenze:esplora le competenze predefinite che forniscono agli agenti funzionalità specializzate per attività complesse sui dati.

Riepilogo della sezione:hai aperto l'IDE Antigravity, l'hai connesso al tuo progetto Google Cloud, hai configurato i server MCP remoti di Data Agent Kit e hai verificato la connessione eseguendo una query su BigQuery.

4. Scopri i tuoi dati

È il momento di preparare la scena. Ecco la situazione: il CFO afferma che il valore medio dell'ordine è diminuito del 7% il mese scorso, ma le entrate totali sono invariate. Prima di chiedere all'agente di eseguire un'indagine, devi prima capire con quali dati stai lavorando.

In questa sezione esplorerai manualmente il riquadro Data Agent Kit per orientarti. Comprendere i dati prima di iniziare a eseguire query è un primo passo fondamentale in qualsiasi indagine.

Esplora le tabelle BigQuery

1. Nel riquadro Data Agent Kit, in CATALOGO, espandi il tuo progetto → BigQuery → cymbal_pets.
2. Fai clic sulla tabella orders. Si apre una nuova scheda che mostra i dettagli della tabella.
3. Esplora le schede sul lato sinistro del visualizzatore di tabelle:
   • Dati: visualizza l'anteprima delle righe effettive. Scorri il set di dati ed esamina le colonne.
   • Schema: esamina i nomi e i tipi delle colonne. Prendi nota dei campi come order_type e promo_code, che diventeranno importanti in un secondo momento.
   • Altre schede (Dettagli, Approfondimenti, Profilo dei dati e così via): Accedi a metadati, data lineage e dettagli sulla qualità che normalmente troveresti nella console Google Cloud, il tutto senza uscire dall'editor.

4. Ora fai clic sulla tabella order_items e rivedi il relativo schema. Osserva i campi quantity e price.

Individuare gli indizi in anticipo. Mentre esamini i dati, potresti notare alcune cose che sembrano insolite: un tipo di ordine B2B-Wholesale e un campo promo_code. Non preoccuparti di collegare i punti per ora. L'agente ti aiuterà.

Esplora le tabelle Cloud SQL

Lo script di configurazione ha anche inserito i dati di clienti, animali domestici e prodotti in un database PostgreSQL in Cloud SQL.

5. Nel riquadro Data Agent Kit, fai clic su Ricerca universale nella sezione CATALOGO.
6. Nella casella di ricerca, digita pet_profiles e premi Invio.
7. Nei risultati di ricerca, fai clic sul risultato Tabella PostgreSQL per pet_profiles (nell'istanza Cloud SQL del tuo progetto). Nota che la fisarmonica della barra laterale si espande automaticamente, mostrando esattamente la posizione della tabella nella struttura ad albero del database. Ora fai clic sulla tabella customers che si trova subito sopra nell'albero per aprirne i dettagli ed esplorare le schede Schema e Dettagli.

Esplora i file di Cloud Storage

Infine, i record delle campagne di marketing e promozionali vengono archiviati come file JSON non elaborati in Cloud Storage.

8. Nel riquadro Data Agent Kit a sinistra, espandi la sezione CLOUD STORAGE. Individua il bucket non elaborato del tuo progetto (YOUR_PROJECT_ID-cymbal-pets-raw).
9. Fai clic sul file promo_events.json all'interno del bucket. Si apre una nuova scheda dell'editor, che ti consente di visualizzare i contenuti JSON Lines non elaborati delle campagne di marketing direttamente nell'IDE.

Fare il punto della situazione

Ecco cosa sai ora del panorama dei dati:

Servizio	Tabelle	Cosa c'è
BigQuery	orders, order_items	Circa 1,9 milioni di ordini, circa 4,3 milioni di elementi pubblicitari, intervallo di date 2023-2025
Cloud SQL	customers, pet_profiles, products	Circa 92.000 clienti, circa 7600 profili di animali domestici, 206 prodotti
Cloud Storage	promo_events.json	Record delle campagne promozionali

Perché i dati sono suddivisi tra i servizi? che rispecchiano le architetture del mondo reale. Cloud SQL è un database OLTP (transazionale). È ottimizzato per operazioni rapide a livello di riga, come l'aggiornamento dell'indirizzo di un cliente o l'elaborazione di un singolo ordine. BigQuery è un data warehouse OLAP (analitico). È più adatta per analizzare milioni di righe per rispondere a domande come "Qual è il valore medio dell'ordine questo mese?". Nella maggior parte delle organizzazioni, i dati si trovano in entrambi, motivo per cui gli strumenti di indagine tra servizi come Data Agent Kit sono così importanti.

I dati sono distribuiti su tre servizi. In un flusso di lavoro tradizionale, dovresti configurare le connessioni, scrivere il codice di integrazione e unire manualmente i risultati. Nel passaggio successivo, lascerai che l'agente AI gestisca tutto tramite un'unica conversazione.

Riepilogo della sezione:hai utilizzato il riquadro Data Agent Kit per esplorare manualmente l'architettura dei dati in BigQuery, Cloud SQL e Cloud Storage. Ora sai dove si trovano i dati e quali campi sono disponibili, quindi puoi iniziare l'indagine.

5. Segui i numeri

Ora inizia l'indagine. Utilizzerai il riquadro Chat per chiedere all'agente AI di estrarre i dati sul valore medio dell'ordine (AOV) da BigQuery. Il valore medio dell'ordine è una metrica aziendale che rappresenta l'importo medio in dollari speso per ordine. L'agente eseguirà query per tuo conto utilizzando gli strumenti MCP e potrai visualizzare ogni query SQL eseguita.

Estrarre l'andamento del valore medio dell'ordine

1. Nel riquadro della chat sul lato destro dell'IDE, digita il seguente prompt e premi Invio:

   Calculate our monthly average order value from August 2024 through January 2025
   using the orders and order_items tables in BigQuery.
   

2. Approva le autorizzazioni di accesso ai dati. È normale essere cauti nei confronti degli agenti AI che eseguono query sui tuoi database. Data Agent Kit ti consente di mantenere il controllo mettendo in pausa la procedura per richiedere l'autorizzazione esplicita prima di accedere ai dati. Quando richiesto, puoi scegliere:
   • Consenti questa volta:approva un singolo utilizzo (ideale per il controllo delle query ad alto rischio).
   • Consenti sempre:approva l'uso continuo di questo strumento specifico per la sessione.
   • No:blocca completamente l'azione.
   Per un'esperienza ottimale con il laboratorio, seleziona Sì, e consenti sempre.Nota:le autorizzazioni vengono concesse per ogni strumento. A breve vedrai altri prompt man mano che l'agente utilizza nuovi strumenti (come list_table_ids o execute_sql_readonly). Puoi anche "consentire sempre" questi prompt.

3. Guarda l'agente all'opera. Il riquadro della chat funge anche da log di trasparenza per tutto ciò che fa l'agente. Invece di una scatola nera, l'agente ti mostra il suo ragionamento e le sue azioni in tempo reale.
4. Al termine dell'operazione dell'agente, fai clic sul menu a discesa Ha lavorato per Xm sotto il prompt per espandere il log di lavoro completo. Qui puoi esaminare esattamente come è stata ottenuta la risposta:
   • Esplorati:espandi questi elementi per visualizzare l'agente che legge i file, sfoglia le cartelle o chiama gli strumenti MCP (come datacloud_bigquery_remote / list_table_ids e execute_sql_readonly). Puoi visualizzare gli argomenti JSON esatti passati agli strumenti e l'SQL eseguito.
   • Eseguiti:espandi questi elementi per visualizzare eventuali comandi del terminale eseguiti dall'agente, ad esempio gcloud config list.

5. Esamina i risultati. L'agente deve restituire una tabella dei valori AOV mensili. Guarda tu stesso i numeri: i mesi precedenti si aggirano intorno ai 110 $, mentre a gennaio scendono a circa 103 $. È l'anomalia segnalata dal CFO.

Cosa sono gli strumenti MCP e le competenze dell'agente? Gli strumenti MCP sono le connessioni sicure che consentono all'agente di interagire con servizi esterni come BigQuery e Cloud SQL. Le skill dell'agente sono set di istruzioni predefiniti (come discovering-gcp-data-assets) che insegnano all'agente come affrontare attività specifiche. Insieme, formano uno strato di controllabilità. Fai clic su un passaggio per vedere esattamente cosa ha fatto l'agente e perché.

Visualizza in dettaglio per canale

L'AOV complessivo è diminuito, ma da dove proviene la diminuzione? Scopriamolo.

5. Nel riquadro Chat, digita:

   January looks lower than the prior months. 
   Break down January's AOV by order_type to see what's going on?
   

6. L'agente esegue un'altra query BigQuery, questa volta raggruppata per order_type. Esamina attentamente i risultati.Dovresti notare qualcosa di sorprendente: l'AOV online e offline rimane stabile a circa 110 $. Tuttavia, esiste un nuovo canale, B2B-Wholesale, con un AOV molto più basso (circa 75 $). Questo nuovo canale sta abbassando la media combinata.
7. L'agente può suggerire in modo proattivo di esaminare i clienti B2B. In caso contrario, non preoccuparti. Lo farai nel passaggio successivo.

L'agente collega i punti. Tieni presente che l'agente interpreta i risultati e potrebbe fornire informazioni come "Il canale B2B-Wholesale sembra essere un nuovo tipo di ordine che non era presente nei mesi precedenti". Questo tipo di analisi proattiva è una funzionalità chiave dell'agente DAK.

Riepilogo della sezione:hai notato il calo dell'AOV di gennaio da un'estrazione di dati neutra, poi hai esaminato in dettaglio order_type per identificare B2B-Wholesale come il nuovo canale che abbassa la media combinata. Ora devi scoprire chi sono questi clienti B2B.

6. Attraversare il confine del servizio

Hai identificato B2B-Wholesale come canale anomalo in BigQuery, ma i dati dei clienti si trovano in Cloud SQL. Con Data Agent Kit, puoi continuare la stessa conversazione e gestire il limite del servizio.

Esaminare i clienti B2B

1. Nel riquadro della chat, digita:

   Who are these B2B customers? Their profiles should be in our Cloud SQL database. 
   Check for:
   - Who they are
   - When they signed up
   - Whether they're new or existing customers
   

2. Guarda attentamente il riquadro della chat. Questa volta dovrebbe essere visualizzato uno strumento MCP diverso. L'agente ora esegue query su Cloud SQL anziché su BigQuery.L'agente si connette all'istanza Cloud SQL Postgres cymbal-pets-ops ed esegue una query sulla tabella customers. Fai clic su Mostra dettagli per visualizzare l'SQL.
3. Esamina i risultati. L'agente dovrebbe mostrare diverse conclusioni chiave:
   • Tutti i clienti B2B hanno customer_type = 'Business'
   • Tutti si sono registrati negli ultimi 30 giorni (gennaio 2025)
   • I loro valori last_name sono nomi di attività come "Pet Supply Co", "Animal Care LLC" e "Happy Paws Inc".
   • Sono circa 100, una coorte che non esisteva prima di questo mese.

Attraversamento dei confini del servizio. L'agente ha eseguito query su due diversi servizi Google Cloud (BigQuery e Cloud SQL) all'interno della stessa conversazione. Nota il nome diverso dello strumento MCP nel riquadro della chat. Nessuna configurazione della connessione, nessuna configurazione delle credenziali. L'agente ha gestito la situazione automaticamente.

Collegare il codice promozionale

4. L'agente potrebbe notare da solo che molti ordini B2B in BigQuery hanno un valore promo_code pari a BIGORDER25. Se si offre di farlo, tanto meglio. L'indagine sta procedendo naturalmente.Se l'agente non menziona il codice promozionale, sollecitalo:

   I noticed a promo_code field on the orders table in BigQuery. 
   Check what promo codes appear on the B2B-Wholesale orders?
   

5. L'agente esegue di nuovo query su BigQuery e scopre che circa il 92% degli ordini B2B-Wholesale ha promo_code = 'BIGORDER25'. Quasi tutte le attività B2B sono legate a una singola campagna promozionale.L'agente dovrebbe ora chiedersi da dove provenga questo codice promozionale. Potrebbe chiederti se ci sono dati promozionali in altre parti dell'ambiente. (Esiste in Cloud Storage.)

Riepilogo della sezione: l'agente ha eseguito una query su Cloud SQL per rivelare che i clienti B2B sono tutte nuove attività che si sono registrate a gennaio 2025. In combinazione con il risultato di BigQuery secondo cui circa il 92% degli ordini include promo_code = 'BIGORDER25', la traccia ora punta a una campagna promozionale. È ora di trovare la fonte.

7. Trova il pezzo mancante

Due servizi in meno, uno in più. Sai cosa è successo (gli ordini B2B stanno abbassando l'AOV) e chi lo sta facendo (nuovi clienti aziendali degli ultimi 30 giorni). Ora devi scoprire perché e la risposta si trova in Cloud Storage.

Controlla il bucket GCS

1. Nel riquadro della chat, digita:

   Good catch on the promo code. 
   We might have promotional campaign data in our GCS bucket. 
   Can you check what's there?
   

2. L'agente non dispone di uno strumento MCP preconfigurato per Cloud Storage, quindi passa automaticamente all'utilizzo dello strumento terminale per eseguire i comandi gcloud storage. Ti chiederà l'autorizzazione per eseguire comandi come gcloud storage ls. Consenti questi comandi, quindi espandi il log Ran nel riquadro Chat per visualizzare i comandi CLI esatti utilizzati per leggere e analizzare il file promo_events.json.
3. L'agente deve identificare tre campagne promozionali nel file:

   Campagna	Codice promozionale	Sconto	Target	Date
   Saldi estivi per la cura di animali domestici	PETSUMMER15	Il 15% di sconto	Tutti	Giugno 2024
   B2B Wholesale Push	BIGORDER25	25% di sconto	B2B	Gennaio 2025
   Bonus festivo per i membri del programma fedeltà	LOYAL10	10% di sconto	Membri del programma fedeltà	Dicembre 2024

   Ecco fatto. Il codice promozionale BIGORDER25 è associato a una campagna chiamata B2B Wholesale Push: 25% di sconto per i clienti B2B con una quantità minima ordinabile di 50 unità. Questa è la prova schiacciante.

Tre servizi, una conversazione. Nelle ultime tre sezioni, l'agente ha eseguito query su BigQuery (dati transazionali), Cloud SQL (dati dei clienti) e Cloud Storage (dati promozionali), il tutto dallo stesso thread di chat, senza alcuna configurazione o cambio di contesto da parte tua. Questo è il valore principale del Data Agent Kit: un singolo agente AI che opera nell'intero patrimonio di dati.

Metti insieme tutti i pezzi

4. Chiedi all'agente di sintetizzare tutto ciò che ha trovato:

   Put it all together. 
   What happened to our average order value?
   

5. L'agente fornisce una sintesi chiara e strutturata che collega tutte e tre le origini dati. Dovrebbe spiegare qualcosa del tipo:
   1. Il calo dell'AOV è reale, ma non si tratta di un calo dell'attività esistente. L'AOV online e offline rimane stabile a circa 110 $.
   2. A gennaio 2025 è stato creato un nuovo canale B2B-Wholesale, con circa 25.000 ordini a un AOV molto più basso (circa 75-100 $).
   3. I clienti B2B sono 100 nuovi account aziendali che si sono registrati tutti negli ultimi 30 giorni (Cloud SQL).
   4. L'attività è guidata da una campagna promozionale ("B2B Wholesale Push") che offre uno sconto del 25% sugli ordini all'ingrosso con un minimo di 50 unità (Cloud Storage).
   5. Le entrate sono stabili perché l'elevato volume di ordini B2B compensa i prezzi più bassi. Tuttavia, i margini unitari sono fortemente compressi (ridotti di circa il 65%) con lo sconto all'ingrosso del 25%, il che minaccia gravemente la redditività complessiva quando vengono presi in considerazione le spese di spedizione e le spese operative.
   Questo è il momento in cui l'indagine fa un passo avanti. La domanda del CFO ha una risposta chiara: l'AOV è diminuito perché un programma B2B basato sul marketing ha inondato gennaio di ordini a basso prezzo e volume elevato. L'attività esistente è integra.

Riepilogo della sezione:hai trovato la prova schiacciante in Cloud Storage: una campagna promozionale B2B che offre uno sconto del 25% sugli ordini di grandi dimensioni. L'agente ha sintetizzato i risultati di tutti e tre i servizi in una narrazione chiara. La fase di indagine è stata completata. Dopodiché, metterai in pratica queste scoperte.

8. Crea la pipeline

Hai risolto il caso. Ora il CFO vuole che questa analisi venga aggiornata automaticamente. In questa sezione, chiederai all'agente di creare un progetto dbt che organizzi i dati BigQuery e produca una tabella dei fatti per l'analisi continua dell'AOV.

È qui che l'agente passa da investigatore a ingegnere. Vedrai che crea la struttura di un intero progetto dbt ed esegue l'intera pipeline, tutto da un unico prompt.

Che cos'è dbt? dbt (data build tool) è un framework che consente ai professionisti dei dati di trasformare i dati nel proprio data warehouse utilizzando SQL. Tratta SQL come codice, aggiungendo il controllo delle versioni, i test automatici e la gestione delle dipendenze.

Crea la struttura del progetto dbt

1. Nel riquadro della chat, digita il seguente prompt. È volutamente orientato agli obiettivi, non passo passo. Stai dicendo all'agente cosa vuoi, non come crearlo:

   I want to productionize our AOV analysis so it updates automatically. Build a dbt project that:
   1. Creates staging models for the BigQuery tables (orders and order_items) and a mart called fct_order_analysis that calculates AOV by channel and month
   2. Add a uniqueness test on order_id and run dbt build
   

2. Osserva l'autocorrezione:se espandi il log "Funzionato per Ns", potresti vedere l'agente controllare dbt e, non trovandolo, eseguire automaticamente i comandi per creare un ambiente virtuale Python (.venv). Gestisce la configurazione dell'ambiente per te.

3. Esamina il piano di implementazione:l'agente genererà un piano di implementazione formale. Puoi esaminare i file e l'architettura proposti, aggiungere commenti se necessario e fare clic su Procedi per consentire all'agente di eseguire il piano.

4. Guarda il riquadro Chat mentre l'agente esegue il piano, scrivendo i file .sql e le configurazioni YAML necessari. Al termine della compilazione del progetto, viene visualizzato un riepilogo delle modifiche. Fai clic su Accetta tutto per aggiungere questi file al tuo spazio di lavoro.

5. Esplora il progetto dbt appena generato in Explorer a sinistra. Dovresti visualizzare una struttura simile a questa:

   dbt/
   ├── models/
   │   ├── marts/
   │   │   └── fct_order_analysis.sql
   │   └── staging/
   │       ├── schema.yml
   │       ├── sources.yml
   │       ├── stg_order_items.sql
   │       └── stg_orders.sql
   ├── dbt_project.yml
   └── profiles.yml
   

6. Fai clic sui file del modello .sql per esaminare l'SQL generato dall'agente. Presta attenzione a come gestisce:
   • Modelli di staging: colonne pulite e rinominate con riferimenti all'origine
   • Il modello mart: la logica di unione e il calcolo dell'AOV per canale

Revisione del codice del negozio: apri models/marts/fct_order_analysis.sql. Nota come aggrega prima gli elementi pubblicitari per mantenere la tabella dei fatti al livello di granularità dell'ordine. Suggerimento: modifica solo i file di origine all'interno della directory models/, non quelli generati automaticamente in /target/.

7. Controlla il riquadro della chat per la conferma dell'agente che tutti i modelli sono stati materializzati e tutti i test sono stati superati. I risultati dell'AOV del mart devono confermare ciò che hai riscontrato durante l'indagine:

   - Online: ~$110
   - Offline: ~$110
   - B2B-Wholesale: ~$75 to $77
   

Riepilogo della sezione:l'agente ha creato un progetto dbt da un singolo prompt orientato all'obiettivo: ha creato modelli di staging e mart, ha eseguito correttamente dbt build e ha confermato l'anomalia dell'AOV. Poi, lancerai una palla curva per vedere come l'agente gestisce la complessità.

9. Quando i test non vanno a buon fine, l'agente esegue il debug

La pipeline funziona, ma utilizza solo i dati BigQuery. Il team di prodotto vuole arricchire l'analisi con i dati dei profili di clienti e animali domestici di Cloud SQL per poter consigliare i prodotti in base alle esigenze alimentari. Ciò significa che l'agente deve colmare il confine di Cloud SQL e gestire un bug sottile di modellazione dei dati, un classico join "fan-out" di modellazione dimensionale.

Che cos'è un "fan-out"? Se un ordine appartiene a un cliente che ha 3 animali domestici, un JOIN SQL standard creerà 3 righe identiche per quell'unico ordine (una per ogni animale domestico). In questo modo i dati vengono "distribuiti" e le metriche come il valore medio dell'ordine vengono rovinate perché le entrate dello stesso ordine vengono conteggiate tre volte. Per risolvere il problema, devi aggregare gli animali in un elenco (array) prima di unirli.

A seconda del modello che utilizzi e delle sue capacità di ragionamento, l'agente gestirà questa richiesta in due modi: evitando proattivamente il bug (opzione A) o eseguendo l'autoriparazione dopo un test non riuscito (opzione B). Vediamo quale percorso segue il tuo agente.

Attivare la richiesta

1. Nel riquadro della chat, digita:

   Enrich fct_order_analysis with customer data and pet profile data from our Cloud SQL database. 
   Include customer type and each customer's pets and dietary needs so we can recommend products. 
   Keep the uniqueness test on order_id and run dbt build.
   

2. Guarda l'agente all'opera. Rileverà le tabelle Cloud SQL, capirà come trasferire i dati in BigQuery (tramite query federata o copia materializzata), creerà nuovi modelli di staging e modificherà fct_order_analysis.sql.

Opzione A: l'agente proattivo (prevenzione dei bug)

Se utilizzi un modello di ragionamento avanzato, l'agente potrebbe rilevare lo spostamento della grana prima di scrivere qualsiasi codice. Si rende conto che, poiché un cliente può possedere più animali domestici, un'unione diretta duplicherà gli ordini e non supererà immediatamente il test di unicità che hai richiesto il giorno order_id.

1. Osserva l'aggregazione proattiva: nella spiegazione del riquadro della chat o nell'artefatto della procedura dettagliata, l'agente potrebbe notare che ha preaggregato i dati degli animali domestici prima di unirli per evitare un "fan-out classico". In genere, lo fa comprimendo più animali domestici per cliente utilizzando una funzione di aggregazione (ad es. ARRAY_AGG() o STRING_AGG()).
2. Controlla i risultati: il dbt build viene eseguito e superato correttamente al primo tentativo perché l'agente ha protetto in modo proattivo la granularità della tabella dei fatti. Puoi verificarlo controllando l'artefatto della procedura dettagliata generato, che spesso mostra l'output del test riuscito insieme ai risultati della query.

Se il tuo agente ha fatto questo, complimenti. Hai assistito all'ingegneria proattiva dell'AI. Esamina il codice SQL generato in fct_order_analysis.sql per vedere come è strutturata l'aggregazione, poi vai alla sezione successiva, Fornire la risposta.

Opzione B: l'agente di autoriparazione (debug e diagnostica)

Se il modello scrive prima un join diretto a sinistra ingenuo, la query SQL verrà eseguita correttamente, ma la suite di test automatizzati dbt test rileverà lo spostamento della granularità.

1. Osserva l'errore del test: vedrai l'errore segnalato nei log di avanzamento dell'esecuzione del riquadro della chat:

   Completed with 1 error
   
   Failure in test unique_fct_order_analysis_order_id
   Got 287 results, configured to fail if != 0
   

   Il test di unicità su order_id ha rilevato voci duplicate perché i clienti con più animali domestici hanno distribuito gli ordini.
2. Lascia che l'agente esegua la diagnosi e l'autoriparazione: poiché il test non è riuscito, chiedi all'agente di eseguire il debug. Nel riquadro della chat, digita:

   The uniqueness test failed. Can you figure out why and fix it?
   

3. Guarda la diagnosi: l'agente eseguirà una query sui dati, rileverà la relazione uno-a-molti in pet_profiles, spiegherà che l'unione diretta modifica la granularità da una riga per ordine a una riga per ordine per animale domestico e riscriverà il modello per preaggregare i profili degli animali domestici:

   -- Pre-aggregating pets per customer to resolve fan-out
   LEFT JOIN (
     SELECT
       customer_id,
       COUNT(*) AS num_pets,
       STRING_AGG(DISTINCT pet_type, ', ') AS pet_types,
       STRING_AGG(DISTINCT dietary_needs, ', ') AS dietary_needs
     FROM pet_profiles
     GROUP BY customer_id
   ) pet_agg ON c.customer_id = pet_agg.customer_id
   

4. Verifica della correzione: l'agente esegue di nuovo dbt build e questa volta tutti i modelli si materializzano e tutti i test vengono superati.

Riepilogo della sezione:che l'agente abbia evitato in modo proattivo il bug o si sia autoriparato correttamente dopo un test non riuscito, hai visto che ha superato il limite di Cloud SQL, integrato i dati dei profili di clienti e animali domestici e mantenuto una perfetta granularità della tabella dei fatti. La pipeline è ora solida, completa e completamente testata.

10. Fornire la risposta

È giovedì. Hai iniziato la settimana con un CFO preoccupato e dati sparsi su tre servizi cloud. Ora hai la causa principale e una pipeline di produzione. È il momento di fornire la risposta, insieme a un consiglio lungimirante supportato da una previsione quantitativa.

Scrivere il riepilogo esecutivo

1. Nel riquadro della chat, digita:

   Write an executive summary covering:
   - Main findings and the quantitative margin impact
   - Project AOV for the subsequent quarter if the B2B program continues at its current trajectory
   - A data-driven recommendation
   

2. Guarda l'agente in azione.

   Una nota sui formati di output e sulle variazioni:i modelli linguistici di grandi dimensioni non sono deterministici. A seconda del modello attivo, l'agente può generare il riepilogo direttamente nel riquadro della chat oppure può creare un file Markdown dedicato (ad esempio executive_summary_cfo.md o output.txt) e collegarlo nella chat.

   I numeri esatti, i totali calcolati (come il potenziale margine perso o le riduzioni medie dell'AOV) e il layout di formattazione varieranno da un'esecuzione all'altra. Ciò che conta è la logica strutturale di base dei risultati.

3. Esamina il riepilogo esecutivo dell'agente. Una risposta tipica e ben strutturata dovrebbe affrontare:
   • Risultato principale: il valore medio dell'ordine di gennaio è diminuito esclusivamente a causa del nuovo canale B2B-Wholesale. Online e Offline rimangono stabili a circa 110 $.
   • Causa principale: la promozione "B2B Wholesale Push" (25% di sconto sugli ordini all'ingrosso) ha attirato 100 nuovi account, generando circa 25.000 ordini.
   • Impatto sul margine: gli ordini all'ingrosso hanno compresso il profitto medio per unità di circa il 65% (da circa 7,50$a circa 2,60 $).
   • Entrate: entrate complessive stabili, in quanto l'elevato volume B2B compensa i prezzi più bassi.

Prevedi l'AOV con AI.FORECAST

4. L'agente deve anche generare una proiezione prospettica. Cerca una chiamata allo strumento MCP in cui l'agente esegue una query AI.FORECAST su BigQuery. Utilizza il modello di base TimesFM integrato per proiettare l'AOV in avanti di 90 giorni in base alle tendenze storiche. La query deve proiettare l'AOV in avanti di 90 giorni in due scenari: continuazione della campagna (AOV strutturalmente depresso) e interruzione della campagna (recupero fino a circa 110 $).

Suggerimento (se l'agente non utilizza AI.FORECAST): se l'agente fornisce una proiezione qualitativa anziché quantitativa, prova a:

Use BigQuery's AI.FORECAST function to generate a 90-day forecast with confidence intervals.

5. Esamina i consigli strategici dell'agente. Un insieme completo di consigli potrebbe includere:
   • Ristruttura gli sconti: implementa i margini minimi o limita gli sconti collettivi per proteggere i margini a livello di unità.
   • Applica MOQ più rigorosi: impedisci agli acquirenti al dettaglio di abusare dei prezzi all'ingrosso.
   • Report separati: monitora le divisioni retail e B2B in modo indipendente per evitare di mascherare il rendimento del retail.

La storia completa

Quello che è iniziato lunedì come una simulazione di incendio per un calo del 7% del valore medio dell'ordine ha una soluzione chiara per il CFO:

• Retail Health: i canali di vendita al dettaglio principali rimangono integri e stabili al livello di base.
• Afflusso di vendite all'ingrosso: il calo dell'AOV è interamente dovuto al nuovo canale B2B Wholesale e alla campagna BIGORDER25.
• Impatto sul margine: lo sconto all'ingrosso del 25% ha eroso notevolmente i margini unitari, minacciando la redditività nonostante le entrate stabili.
• Previsione strategica: una proiezione AI.FORECAST mostra che la ristrutturazione dei livelli di vendita all'ingrosso ripristinerà l'AOV combinato.

Fornisci un consiglio basato sui dati per stabilire i margini minimi all'ingrosso e report separati per la vendita al dettaglio/B2B.

Riepilogo della sezione:hai chiesto all'agente di scrivere un riepilogo per i dirigenti con l'analisi del margine, generare una proiezione AI.FORECAST e fornire un consiglio basato sui dati. L'indagine è stata completata.

11. Elimina

Per evitare che al tuo account Google Cloud vengano addebitati costi continui, elimina le risorse create in questo codelab eseguendo lo script di pulizia.

1. Nel riquadro Terminale nella parte inferiore dell'IDE Antigravity (o in Cloud Shell), vai alla directory del codelab ed esegui:

cd ~/devrel-demos/codelabs/agentic-data-labs/scripts
chmod +x teardown.sh
./teardown.sh

2. Lo script mostrerà tutte le risorse che prevede di eliminare e chiederà la conferma prima di procedere:
   • Istanza Cloud SQL (cymbal-pets-ops): questa è la risorsa più costosa
   • Set di dati BigQuery (cymbal_pets): tutte le tabelle e tutti i modelli
   • Bucket Cloud Storage (gs://YOUR_PROJECT_ID-cymbal-pets-raw)
   • Connessione BigQuery (cymbal-pets-cloudsql)
3. Digita y per confermare. Lo smontaggio richiede circa 2-3 minuti.

[INFO]  Deleting Cloud SQL instance cymbal-pets-ops...
[ OK ]  Cloud SQL instance deleted.
[INFO]  Deleting BigQuery dataset cymbal_pets...
[ OK ]  BigQuery dataset deleted.
[INFO]  Deleting GCS bucket gs://YOUR_PROJECT_ID-cymbal-pets-raw...
[ OK ]  GCS bucket deleted.

Non dimenticare questo passaggio. L'istanza Cloud SQL comporta addebiti anche quando è inattiva. Se salti l'eliminazione, puoi eseguirla in un secondo momento o eliminare l'intero progetto Google Cloud che hai utilizzato per questo codelab.

12. Complimenti!

Hai completato L'indagine sugli animali domestici con i piatti. Sei passato da una domanda vaga del CFO a un consiglio completamente operativo e basato sulle previsioni, utilizzando un agente AI che funziona su tutto il tuo patrimonio di dati Google Cloud.

Cosa hai realizzato

1. 🔍 Esplorati nei servizi: asset scoperti e visualizzati in anteprima in BigQuery, Cloud SQL e Cloud Storage utilizzando Data Agent Kit's Knowledge Catalog.
2. 🕵️‍♂️ Indagine con l'AI: è stata eseguita una query su più servizi in una singola conversazione nel riquadro della chat utilizzando gli strumenti MCP per risalire all'anomalia del valore medio dell'ordine a una campagna promozionale B2B collettiva.
3. 🔧 Creazione di una pipeline di produzione: è stato creato un progetto dbt completo per pulire, unire e testare i dati transazionali e dei clienti.
4. 🐛 È stato eseguito il debug di un bug di fan-out: è stato osservato che l'agente diagnostica automaticamente un problema di granularità e refattorizza il modello SQL dbt per pre-aggregare i profili degli animali domestici dei clienti.
5. 📈 Previsto e consigliato: è stato utilizzato il modello AI.FORECAST integrato di BigQuery per modellare le tendenze dell'AOV e fornire un consiglio basato sui dati al CFO.

Concetti fondamentali

Concetto	Che cosa hai imparato
Strumenti MCP	Connessioni sicure e controllabili che consentono all'agente AI di eseguire query su servizi come BigQuery, Cloud SQL, Spanner e altri database per tuo conto, con ogni chiamata visibile nel riquadro della chat
Competenze dell'agente	Set di istruzioni predefiniti (come dbt-bigquery o discovering-gcp-data-assets) che insegnano all'agente le best practice specifiche del dominio senza che tu debba richiederle
Indagine cross-service	L'agente esegue query su più servizi Google Cloud in una singola conversazione, senza configurazione della connessione e senza cambio di contesto tra le console
Prompting orientato agli obiettivi	Comunicare all'agente cosa vuoi ("crea un progetto dbt che calcoli l'AOV per canale") anziché come e lasciare che scelga l'approccio di implementazione
Data Agent Kit	L'estensione che lega tutto insieme (strumenti MCP, competenze degli agenti e individuazione dei dati), consentendoti di accedere all'intero patrimonio di dati Google Cloud dall'IDE che preferisci

Passaggi successivi

• Leggi la documentazione di Data Agent Kit per scoprire di più sulle sue funzionalità.
• Scopri di più su BigQuery ML e sulle funzioni AI, tra cui AI.FORECAST, AI.GENERATE e AI.EMBED.
• Prova a creare la tua indagine cross-service con l'IDE Antigravity sui tuoi dati