Creare agenti AI con ADK: agente data analyst

1. Prima di iniziare

DA LEGGERE:

Questo tutorial richiede un progetto Google Cloud con un account di fatturazione attivo.

Per i partecipanti al workshop di persona: segui le istruzioni specifiche di configurazione e fatturazione fornite dall'insegnante.

Per gli utenti che studiano in autonomia: segui questi passaggi per riscattare una prova:

• Apri una finestra di navigazione in incognito nel browser.
• Vai a questo portale per la riscossione dei premi.
• Accedi utilizzando il tuo account Gmail personale.
• Segui le istruzioni passo passo del portale.

Ti diamo il benvenuto alla quarta parte della serie "Creazione di agenti AI con ADK". In questo codelab pratico, combinerai ciò che hai imparato nelle sessioni precedenti per creare un agente di analisi dei dati. Questo agente sarà progettato per analizzare i dati, generare insight preziosi e automatizzare gli aspetti chiave del workflow di analisi dei dati.

Potrai consentire al tuo agente di esplorare i file caricati e connetterlo a database di livello aziendale come Google Cloud BigQuery, utilizzando i potenti strumenti inclusi in ADK.

Puoi accedere a questo codelab anche tramite questo URL abbreviato: goo.gle/adk-data-analyst

Prerequisiti

• Una comprensione di base dei concetti dell'AI generativa
• Conoscenza di base della programmazione in Python e familiarità con l'utilizzo della riga di comando.
• Familiarità con i concetti dei codelab precedenti di questa serie: "The Foundation" ed "Empowering with Tools".

Cosa imparerai a fare

• Come creare un agente di analisi dei dati funzionale utilizzando il framework ADK.
• Metodi per consentire a un agente di analizzare i dati dei documenti caricati.
• Come connettere l'agente a un database BigQuery per l'analisi dei dati a livello aziendale.
• Tecniche per definire la logica principale dell'agente, inclusi scopo e istruzioni.

Che cosa ti serve

• Un computer funzionante e una connessione a internet affidabile.
• Un browser, ad esempio Chrome, per accedere alla console Google Cloud
• Una mente curiosa e la voglia di imparare.

2. Introduzione

Nel mondo odierno basato sui dati, la capacità di analizzare rapidamente e con precisione grandi quantità di informazioni è più importante che mai. Tuttavia, il processo di estrazione di informazioni significative spesso richiede competenze tecniche approfondite in aree come SQL, creando un collo di bottiglia che può rallentare il processo decisionale. E se potessi colmare questo divario e interagire con set di dati complessi con la stessa facilità di una conversazione?

È qui che gli agenti AI stanno cambiando le regole del gioco. Fungendo da interfaccia intelligente tra te e i tuoi dati, gli agenti AI possono comprendere le domande in linguaggio naturale, tradurle in query tecniche e fornire insight azionabili in pochi secondi.

In questo codelab, entrerai nel futuro dell'analisi dei dati creando un agente di analisi dei dati pratico utilizzando Agent Development Kit (ADK). Inizieremo creando un agente di base e poi ne miglioreremo progressivamente le funzionalità. Per prima cosa, insegnerai all'agente ad analizzare i dati non strutturati dei documenti caricati. Poi, lo collegherai a un data warehouse potente di livello aziendale, Google Cloud BigQuery, per eseguire query e analizzare un set di dati sanitari su larga scala del mondo reale.

Al termine di questo tutorial, non solo avrai un assistente AI funzionale, ma anche una solida comprensione di come creare agenti in grado di automatizzare le attività di routine sui dati, accelerare l'analisi e democratizzare l'accesso a informazioni critiche per te e il tuo team.

3. Configurare i servizi Google Cloud

Crea un progetto Google Cloud

Per mantenere tutto il lavoro per questo codelab organizzato e separato dagli altri progetti, inizierai creando un nuovo progetto Google Cloud.

1. Vai alla pagina console.cloud.google.com/projectcreate.
2. Inserisci le informazioni richieste:

• Nome progetto: puoi inserire il nome che preferisci (ad es. genai-workshop)
• Sede: lascia Nessuna organizzazione
• Account di fatturazione: se viene visualizzata questa opzione, seleziona "Account di fatturazione di prova di Google Cloud Platform" o il tuo account di fatturazione, se preferisci. Se non vedi questa opzione, puoi procedere al passaggio successivo.

3. Copia l'ID progetto generato, ti servirà in un secondo momento.

4. Se è tutto a posto, fai clic sul pulsante Crea.

Configurare Cloud Shell

Una volta creato il progetto, segui questi passaggi per configurare Cloud Shell.

1. Avvia Cloud Shell

Vai a shell.cloud.google.com. Se viene visualizzato un popup che chiede l'autorizzazione, fai clic su Autorizza.

2. Imposta ID progetto

Sostituisci replace-with-your-project-id con l'ID progetto effettivo del passaggio di creazione del progetto riportato sopra. Esegui questo comando nel terminale Cloud Shell per impostare l'ID progetto corretto.

gcloud config set project replace-with-your-project-id

Ora dovresti vedere che nel terminale Cloud Shell è selezionato il progetto corretto. L'ID progetto selezionato è evidenziato in giallo.

3. Abilita le API richieste

Per utilizzare i servizi Google Cloud, devi prima attivare le rispettive API per il tuo progetto. Esegui i comandi riportati di seguito nel terminale Cloud Shell per abilitare i servizi per questo codelab:

gcloud services enable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

Se l'operazione è andata a buon fine, nel terminale verrà visualizzato il messaggio Operation/... finished successfully.

4. Crea un ambiente virtuale Python

Poi, crea un ambiente Python isolato per gestire le dipendenze del progetto.

Nota:utilizzeremo uv per creare il nostro ambiente virtuale anziché il pacchetto venv standard. È un gestore di pacchetti e progetti Python incredibilmente veloce scritto in Rust.

Se ti interessa, puoi scoprire di più nella documentazione ufficiale di uv.

1. Crea la directory del progetto e accedi alla directory:

mkdir -p ai-agents-adk && cd ai-agents-adk

2. Crea e attiva un ambiente virtuale:

uv venv --python 3.12
source .venv/bin/activate

Vedrai il prefisso (ai-agents-adk) davanti al prompt del terminale, a indicare che l'ambiente virtuale è attivo.

3. Pagina di installazione di ADK

uv pip install google-adk --no-cache

Nota:se chiudi accidentalmente il terminale, dovrai andare nella cartella ai-agents-adk ed eseguire di nuovo source .venv/bin/activate.

5. Crea un agente iniziale

Ora che l'ambiente è pronto, è il momento di creare l'agente AI utilizzando un semplice comando ADK.

1. Crea un agente

Nel terminale, esegui questo comando:

adk create data_analyst_agent

2. Configura l'agente

Ti verrà chiesto di configurare l'agente. Seleziona i seguenti valori:

• Scegli un modello: seleziona 1. gemini-2.5-flash.
• Scegli un backend: seleziona 2. Vertex AI.
• Inserisci l'ID progetto Google Cloud: premi Invio per confermare l'ID progetto corretto.
• Inserisci la regione Google Cloud: premi Invio per utilizzare il valore predefinito us-central1.

3. Avvia il server web di sviluppo

Una volta creato l'agente, avvia il server web di sviluppo eseguendo questo comando:

adk web

Puoi Ctrl + fare clic o Cmd + fare clic sul link (ad es. http://localhost:8000) nel terminale oppure puoi

• Fai clic sul pulsante Anteprima web.
• Seleziona Cambia porta.
• Inserisci il numero di porta (ad es. 8000)
• Fai clic su Cambia e visualizza anteprima.

A questo punto, nel browser verrà visualizzata l'interfaccia utente simile a un'applicazione di chat.

4. Chatta con il tuo agente

Inizia a chattare con il tuo agente tramite questa interfaccia. Di' qualcosa come "Ciao, cosa sai fare?".

6. Analizzare i dati di un documento

In questa sezione caricherai un documento nell'agente e porrai domande sui suoi contenuti.

1. Riassumi il documento

Segui questi passaggi per ottenere un riepilogo del documento:

1. Scarica il file sulla strategia di Google per l'assistenza sanitaria.
2. Fai clic sul pulsante Carica file nell'interfaccia utente dell'agente e seleziona il file che hai appena scaricato.
3. Nell'interfaccia della chat, chiedi all'agente di riassumere il file: "Dammi un riepilogo di questo file".
4. Premi Invio.

Dovresti ricevere un riepilogo conciso dei contenuti del documento.

2. Fare domande più dettagliate

Ora prova a fare domande più dettagliate per approfondire il documento:

• Quali sono le principali malattie che Google sta attualmente prendendo di mira con le sue iniziative di AI e dati?
• In che modo Google prevede di migliorare l'interoperabilità dei dati sanitari e abbattere i silos di dati?
• In che modo Google Cloud viene utilizzato per supportare le aziende sanitarie e i ricercatori?
• Quali nuove aree di patologie sta potenzialmente esplorando Google (ad es. BPCO, cancro, salute mentale)?

3. Fai domande aggiuntive

Puoi anche porre domande aggiuntive, ad esempio per scoprire il numero di riferimento della pagina per ulteriori indagini:

• Dove hai visto le informazioni relative al diabete?
• Indirizzami alle pagine pertinenti sulle malattie.
• Dove si trovano i grafici interessanti che dovrei esaminare?

Sfida: trova un documento personale che vuoi che l'agente analizzi e caricalo. Fare domande all'agente sui suoi contenuti.

7. Combinare gli approfondimenti sui documenti con la ricerca web live

L'agente ora è un esperto del documento, ma un analista potente ha anche bisogno di accedere a informazioni esterne e aggiornate. Diamo al nostro agente la possibilità di cercare sul web.

1. Nel terminale Cloud Shell, premi Ctrl+C per arrestare il server web.
2. Apri il file data_analyst_agent/agent.py nell'editor di Cloud Shell eseguendo questo comando:

cloudshell edit data_analyst_agent/agent.py

3. Modifica il file per importare e aggiungere lo strumento google_search:

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction="""
        First, check the uploaded files for an answer. 
        If the information is not in the files, use your tools to search the web. 
        Answer user questions to the best of your ability.
    """,
    tools=[
        google_search
    ]
)

NOTA:l'istruzione è stata aggiornata anche per guidare l'agente su quando utilizzare lo strumento di ricerca Google.

4. Salva il file e riavvia il server web nel terminale digitando adk web
5. Nell'interfaccia utente dell'agente, ricaricamento il file GoogleHealthStrategy.pdf.
6. Ora poni una domanda che richieda sia il contesto del documento sia informazioni esterne:

The document discusses Google's strategy in healthcare. What are three other major tech companies that are also investing heavily in healthcare AI, and what are their primary focus areas?

L'agente sintetizzerà le informazioni del documento e di una ricerca Google in tempo reale per fornirti una risposta completa. Puoi provare a porre alcune domande:

• Il documento menziona l'utilizzo dell'AI per la retinopatia diabetica. Quali sono alcune delle tecnologie approvate dalla FDA più recenti in questo settore che sono state annunciate nell'ultimo anno?
• Il file menziona partnership. Puoi trovare articoli di notizie o comunicati stampa recenti sulle ultime collaborazioni di Google nel settore sanitario?

Sfida: prova a fare domande simili a un tuo documento. Qualcosa che utilizza un documento locale e i risultati di internet.

8. Analizzare i dati sanitari con BigQuery

Il caricamento di singoli documenti non è scalabile. In uno scenario reale, i dati risiedono in sistemi aziendali come Google Cloud BigQuery.

Attualmente, gli sviluppatori che creano applicazioni con agenti spesso devono creare e gestire i propri strumenti personalizzati. Questo processo manuale è lento, rischioso e crea un overhead significativo. obbligando gli sviluppatori a gestire tutto, dall'autenticazione alla gestione degli errori, anziché concentrarsi sull'innovazione.

Agent Development Kit (ADK) include strumenti proprietari per l'interazione con BigQuery. Per questa analisi specifica, utilizzeremo il set di dati sull'utilizzo di Medicare disponibile pubblicamente e fornito dai Centers for Medicare & Medicaid Services (CMS).

Innanzitutto, colleghiamo il nostro agente a un enorme set di dati sanitari pubblici.

1. Nel terminale Cloud Shell, premi Ctrl+C per arrestare il server web.
2. Apri il file data_analyst_agent/agent.py nell'editor di Cloud Shell eseguendo questo comando nel terminale:

cloudshell edit data_analyst_agent/agent.py

3. Sostituisci l'intero contenuto del file con il seguente codice per configurare il potente BigQueryToolset:

import google.auth
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.bigquery import (
    BigQueryToolset,
    BigQueryCredentialsConfig
)
from google.adk.tools.bigquery.config import (
    BigQueryToolConfig,
    WriteMode
)

# Automatically get credentials from the gcloud environment
application_default_credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
    credentials=application_default_credentials
)

# Configure the BigQuery tool
tool_config = BigQueryToolConfig(
    write_mode=WriteMode.ALLOWED,
    application_name='data_analyst_agent'
)

# Create the toolset with the specified configurations
bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config, bigquery_tool_config=tool_config
)

# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

# Define the final agent with its instructions and tools
root_agent = Agent(
    model="gemini-2.5-flash",
    name="bigquery_agent",
    description=(
        "Agent to answer questions about BigQuery data and execute SQL queries."
    ),
    instruction="""
        You are an expert data analyst agent with access to BigQuery tools.
        When a user asks about a dataset, first use your tools to understand its schema.
        Then, use this knowledge to construct and execute SQL queries to answer the user's questions.
        Always confirm with the user if their question is ambiguous (e.g., for which year?).
    """,
    tools=[
        AgentTool(google_search_agent),
        bigquery_toolset
    ],
)

4. Salva il file e riavvia il server web nel terminale digitando adk web
5. Ora puoi chiedere al tuo agente di analizzare il set di dati pubblici Medicare. Inizia esplorando i dati:

Look into the cms_medicare dataset in the bigquery-public-data project. What can you tell me about it?

L'agente utilizzerà i suoi strumenti per esaminare il set di dati e fornire un elenco delle tabelle disponibili. Da qui, puoi visualizzare in dettaglio con domande analitiche specifiche. L'agente potrebbe porre domande chiarificatrici per assicurarsi che le sue query siano accurate.

Per alcune domande, dovrai fornire all'agente l'ID progetto in modo che possa utilizzarlo per creare una query. Ad esempio:

Ecco alcuni prompt analitici di esempio che puoi provare:

• Utilizzando la tabella inpatient_charges_2015, quali sono le prime 5 procedure (definizioni DRG) in base al numero totale di dimissioni?
• Qual è il pagamento totale medio per l'"INTERVENTO DI SOSTITUZIONE ARTICOLARE MAGGIORE" in California (CA)?
• Quale stato ha le spese coperte medie più elevate per la stessa procedura?

Questo codelab termina qui. Hai solo scalfito la superficie di ciò che puoi ottenere con gli agenti dei dati basati su sistemi di dati aziendali. Non esitare a porre all'agente eventuali domande sul set di dati cms_medicare.

Sfida: trova un altro set di dati pubblico in BigQuery e usa il tuo agente per esplorarlo. Puoi anche creare il tuo set di dati con i tuoi dati e analizzarlo in privato.

9. Liberare spazio (facoltativo)

Nota: se prevedi di continuare con la serie, NON DEVI eseguire questo passaggio. Se partecipi a questo codelab di persona con un istruttore, quest'ultimo ti fornirà ulteriori istruzioni su cosa fare.

Per evitare addebiti futuri, puoi eliminare le risorse utilizzate in questo codelab.

1. Interrompi l'agente

Nel terminale Cloud Shell, premi Ctrl+C per arrestare il processo adk web.

2. Eliminare i file del progetto

Per rimuovere il codice dell'agente dall'ambiente Cloud Shell, esegui questo comando nel terminale:

cd ~ && rm -rf ai-agents-adk

3. Disabilita le API

Per disabilitare le API che hai abilitato in precedenza, esegui il seguente comando nel terminale:

gcloud services disable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

4. Arresto del progetto

Se vuoi eliminare l'intero progetto Google Cloud, segui la guida alla chiusura dei progetti.

10. Conclusione

Complimenti! Hai creato correttamente un agente per l'analisi dei dati utilizzando il framework Agent Development Kit (ADK). Questo agente è in grado di analizzare i dati provenienti da varie fonti, generare insight e contribuire ad automatizzare parti del workflow di analisi dei dati.

Per continuare il tuo percorso di apprendimento, esplora queste risorse:

• Leggi il post del blog ufficiale: Annuncio del set di strumenti BigQuery per gli agenti AI
• Esplora la documentazione: visita la documentazione ufficiale dell'Agent Development Kit (ADK) per nuove funzionalità e guide avanzate.
• Sfoglia il codice: consulta il repository GitHub dell'ADK.
• Scopri altri dati: esplora il catalogo dei set di dati pubblici di Google Cloud.