Agente Data Science stateful su Agent Runtime

1. Panoramica

In questo codelab creerai un agente di data science che esegue query sui dati reali dei set di dati pubblici BigQuery e memorizza le tue preferenze tra le sessioni. Dopodiché, lo eseguirai il deployment in Agent Runtime, un servizio Google Cloud completamente gestito che gestisce l'infrastruttura, lo scaling e la gestione delle sessioni.

L'agente utilizza tre funzionalità principali che si attivano progressivamente:

• BigQuery Toolset: l'agente esplora gli schemi ed esegue query SQL su set di dati BigQuery reali. Questa operazione funziona sia localmente che al momento del deployment.
• Memory Bank: una volta implementato, l'agente ricorda le preferenze e il contesto dell'utente nelle sessioni disconnesse.
• Osservabilità: Cloud Trace acquisisce i passaggi di ragionamento, le chiamate agli strumenti e le latenze dell'agente tramite l'instrumentazione OpenTelemetry.

Obiettivi didattici

• Come creare un agente ADK con BigQueryToolset per l'accesso ai dati reali
• Come configurare Memory Bank per la persistenza tra sessioni
• Come eseguire il deployment dell'agente in Agent Runtime con adk deploy
• Come concedere le autorizzazioni IAM per il service account dell'agente di cui è stato eseguito il deployment
• Come testare la persistenza e l'osservabilità della memoria

Che cosa ti serve

• Un progetto cloud Google Cloud con la fatturazione abilitata
• Un browser web come Chrome
• Se esegui il codice sulla tua macchina anziché su Cloud Shell: Google Cloud SDK (gcloud CLI), uv (gestore di pacchetti Python) e Python 3.12+ (installato automaticamente da uv, se necessario)

ADK (Agent Development Kit) è il framework di Google per la creazione di agenti AI. Questo codelab utilizza ADK per creare un agente ed eseguirne il deployment in Agent Runtime.

Questo codelab è destinato a sviluppatori di livello intermedio che hanno una certa familiarità con Python e Google Cloud.

Il completamento di questo codelab richiede circa 35 minuti (inclusi 5-10 minuti per il deployment).

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

2. Configura l'ambiente

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Configurare il progetto

Apri l'editor di Cloud Shell nel progetto GCP che hai creato.

Quindi, crea un terminale > Nuovo terminale ed esegui il comando seguente per impostare il progetto. I comandi successivi leggono l'ID progetto da questa impostazione.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Abilita API

Nel terminale, esegui questo comando.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com: ospita l'agente su Agent Runtime, incluse le sessioni Gemini Enterprise e Memory Bank, e serve il modello Gemini
• API BigQuery (bigquery.googleapis.com): query SQL su set di dati pubblici e privati
• API Telemetry (telemetry.googleapis.com): tracce OpenTelemetry per l'osservabilità dell'agente

L'abilitazione dell'API potrebbe richiedere fino a un minuto. Se nei passaggi successivi visualizzi errori "API non abilitata", attendi un momento e riprova.

Installa ADK

Nel terminale, esegui i seguenti comandi per creare una cartella per questo codelab e installare ADK e le relative dipendenze:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv crea un ambiente Python isolato per questo codelab, quindi non devi attivare nulla. Aggiungi il prefisso uv run ai comandi Python.

Il pacchetto google-adk include lo strumento CLI adk che utilizzerai per testare e implementare l'agente. adk deploy utilizza google-cloud-aiplatform per creare l'agente in Agent Runtime e google-cloud-bigquery è la libreria client alla base degli strumenti BigQuery di ADK.

3. Crea l'agente

Nella cartella ~/adk-deploy-scale, crea la directory dell'agente. Esegui tutti i comandi successivi da ~/adk-deploy-scale (il genitore di data_science_agent/):

mkdir data_science_agent

Quindi, esegui questo comando per creare data_science_agent/.env con il tuo progetto, la regione in cui verrà eseguito il deployment dell'agente e le impostazioni per l'agente di cui è stato eseguito il deployment. adk deploy legge questo file, quindi queste impostazioni funzionano ancora se apri un nuovo terminale.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_LOCATION: il tuo ID progetto (compilato da gcloud) e la regione in cui viene eseguito l'agente
• GOOGLE_GENAI_USE_ENTERPRISE: ha ADK che chiama Gemini tramite il tuo progetto Google Cloud
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: registra gli input dei prompt completi e le risposte dell'agente, utili per il debug

L'impostazione OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT registra i contenuti completi dei prompt degli utenti e delle risposte dell'agente in Cloud Logging. Questa funzionalità è utile per il debug, ma potrebbe acquisire dati sensibili o PII. In produzione, imposta questo valore su false o assicurati di aver implementato norme di gestione dei dati appropriate.

La struttura di directory finale avrà questo aspetto:

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

Ora creerai __init__.py e agent.py, poi aggiungerai requirements.txt nel passaggio di deployment.

Crea data_science_agent/__init__.py. Questo file è necessario per consentire ad ADK di rilevare e caricare l'agente:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

Crea data_science_agent/agent.py:

Questo agente si connette a BigQuery per l'estrazione dei dati e salva le sessioni in Memory Bank.

La memoria si attiva automaticamente quando viene distribuita. Agent Runtime imposta la variabile di ambiente GOOGLE_CLOUD_AGENT_ENGINE_ID, che non è presente durante l'esecuzione in locale.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by Agent Runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Runtime, where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

Vediamo cosa fa questo codice:

1. BigQueryToolset fornisce all'agente strumenti come execute_sql, list_table_ids e get_table_info. Può esplorare gli schemi ed eseguire query su qualsiasi set di dati a cui il chiamante ha accesso.
2. PreloadMemoryTool recupera automaticamente le Memory pertinenti prima di ogni chiamata LLM cercando nella Memory Bank contenuti correlati al messaggio dell'utente. Il callback _save_memory salva la sessione in Memory Bank dopo ogni esecuzione dell'agente, in modo che l'agente possa ricordare il contesto nelle sessioni future.
3. App racchiude l'agente principale in un'applicazione di cui è possibile eseguire il deployment e che può essere gestita da Agent Runtime. name deve corrispondere al nome della directory (data_science_agent). adk web lo utilizza per individuare e caricare l'agente.
4. L'istruzione indica all'agente di utilizzare il progetto di fatturazione per le query SQL e di ricordare le preferenze dell'utente.
5. Gemini con client_kwargs={"location": "global"} invia chiamate al modello all'endpoint globale, dove è disponibile gemini-3.8-flash. L'agente stesso viene eseguito in us-central1: adk deploy imposta GOOGLE_CLOUD_LOCATION sull'agente di cui è stato eseguito il deployment nella regione in cui viene eseguito il deployment, quindi la posizione del modello viene impostata nel codice.

4. Esegui il deployment in Agent Runtime

Crea un file requirements.txt nella directory data_science_agent:

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk e google-genai: ADK e il client Gemini
• google-auth: Autenticazione Google Cloud
• google-cloud-bigquery: la libreria client BigQuery utilizzata da BigQueryToolset. ADK non lo installa per impostazione predefinita.
• python-dotenv: carica il file .env all'avvio
• I tre pacchetti opentelemetry-instrumentation-* abilitano le funzionalità di osservabilità che esplorerai in un secondo momento. Strumentano le chiamate al modello Gemini e la comunicazione gRPC/HTTP interna in modo che le tracce vengano visualizzate nella scheda Tracce dell'agente.

Non aggiungere google-cloud-aiplatform a requirements.txt, anche se l'hai installato localmente. adk deploy lo aggiunge per te (insieme alla versione dell'ADK che implementi), ma solo se non è già presente nel tuo requirements.txt. Se lo dichiari tu, possono verificarsi conflitti tra le versioni dei pacchetti OpenTelemetry che interrompono l'instrumentazione in modo invisibile, impedendo la visualizzazione delle tracce nella scheda Tracce.

adk deploy legge anche il file data_science_agent/.env creato in precedenza e imposta le relative impostazioni sull'agente di cui è stato eseguito il deployment.

Esegui il deployment dell'agente. L'ultimo argomento data_science_agent è la directory contenente il codice dell'agente:

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

All'inizio, l'output mostra due linee gialle, Ignoring GOOGLE_CLOUD_PROJECT in .env ... e Ignoring GOOGLE_CLOUD_LOCATION in .env .... Sono previsti: i flag --project e --region hanno la precedenza sugli stessi valori in .env.

Flag	Finalità
--project/--region	Progetto Google Cloud e regione di destinazione
--display_name	Nome leggibile mostrato nella console Cloud
--otel_to_cloud	Esporta tracce e log OpenTelemetry in Google Cloud e attiva la telemetria (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) sull'agente di cui è stato eseguito il deployment

In genere, il deployment richiede 5-10 minuti. Al termine, l'output mostra il nome della risorsa dell'agente (projects/.../reasoningEngines/) e un link per visualizzarlo in Cloud Console.

Mentre aspetti, consulta la documentazione di Memory Bank per scoprire di più su come funziona la memoria cross-session.

Se il link stampato da adk deploy non funziona, apri la pagina Deployment nella console Google Cloud e fai clic sull'agente.

Quando viene eseguito il deployment su Agent Runtime, vengono attivate automaticamente due funzionalità:

• Memory Bank: adk deploy connette l'agente a Sessioni e Memory Bank nella sua istanza di Agent Runtime. PreloadMemoryTool legge dalla Memory Bank e _save_memory mantiene automaticamente le sessioni.
• Osservabilità: Cloud Trace acquisisce i passaggi di ragionamento, le chiamate agli strumenti e le latenze dell'agente.

5. Concedi le autorizzazioni BigQuery

Devi concedere a BigQuery l'accesso all'agente di servizio Agent Runtime (l'agente di servizio AI Platform Reasoning Engine). Una volta eseguito il deployment, l'agente viene eseguito come questo service account gestito da Google (non le tue credenziali personali), pertanto ha bisogno di autorizzazioni esplicite per eseguire query SQL.

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

Ogni comando stampa Updated IAM policy for project [...] se ha esito positivo.

Se salti questo passaggio, l'agente di cui è stato eseguito il deployment restituirà errori 403 durante l'esecuzione delle query SQL. Il ruolo bigquery.jobUser è necessario nel progetto di fatturazione (il tuo progetto), non nel progetto di dati.

Nota: bigquery.dataViewer concede l'accesso in lettura a tutti i set di dati del tuo progetto. Per l'utilizzo in produzione, valuta la possibilità di concedere questo ruolo a livello di set di dati.

6. Testa l'agente di cui è stato eseguito il deployment

Apri la pagina Deployment nella console Google Cloud. Fai clic sull'agente di cui è stato eseguito il deployment, quindi sulla scheda Playground.

Il completamento di ogni query potrebbe richiedere 10-30 secondi, poiché l'agente ragiona, chiama gli strumenti e restituisce i risultati.

Testa le funzionalità di BigQuery:

1. "Elenca le tabelle in bigquery-public-data.hacker_news"
   • Previsto: l'agente chiama list_table_ids e restituisce i nomi delle tabelle, incluso full.
2. "Trova il numero di post all'anno in bigquery-public-data.hacker_news.full"
   • Previsto: l'agente chiama execute_sql con una query SQL e restituisce una tabella di anni e conteggi dei post.
3. "Qual è stata la variazione percentuale dei post su base annua?"
   • Previsto: l'agente chiama execute_sql con una query SQL che calcola la variazione percentuale e restituisce i risultati.

7. Testa la persistenza della memoria

Sempre in Playground, insegna all'agente una preferenza:

1. "Ricorda che il mio set di dati preferito è bigquery-public-data.hacker_news"
2. "Quali tabelle contiene?"

Attendi qualche secondo affinché la memoria venga mantenuta (il callback _save_memory viene eseguito dopo la risposta dell'agente).

Ora avvia una nuova sessione facendo clic su Nuova sessione in Playground, poi chiedi:

3. "Qual è il mio set di dati preferito?"

L'agente deve ricordare bigquery-public-data.hacker_news anche se si tratta di una sessione nuova di zecca senza cronologia delle conversazioni. Questo funziona perché:

• _save_memory viene mantenuto in ogni sessione nella Memory Bank tramite callback_context.add_session_to_memory()
• PreloadMemoryTool recupera i ricordi pertinenti prima di ogni chiamata LLM
• Memory Bank abbina i contenuti in modo semantico, non solo in base alle parole chiave

Se l'agente non ricorda la tua preferenza, attendi 10 secondi e riprova in una nuova sessione. La persistenza della memoria è asincrona e il completamento potrebbe richiedere un momento.

8. Esplora Observability

Nella console Cloud, vai all'agente di cui è stato eseguito il deployment e fai clic sulla scheda Tracce.

Dovresti visualizzare una tabella delle sessioni che elenca le sessioni delle query di test eseguite nei passaggi precedenti. La tabella mostra le metriche di riepilogo per ogni sessione: durata media, chiamate del modello, chiamate degli strumenti, utilizzo dei token ed eventuali errori.

Fai clic su una sessione per ispezionare i dettagli della traccia, tra cui:

• Un grafo diretto aciclico (DAG) dei suoi span, che mostra la suddivisione passo passo del ragionamento dell'agente, delle chiamate di strumenti (query BigQuery) e delle latenze
• Input e output per ogni intervallo (attivati tramite la variabile di ambiente OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT in .env)
• Attributi dei metadati come ID intervallo, ID traccia e tempistica

Puoi anche passare alla visualizzazione intervallo (attiva/disattiva in alto) per visualizzare i singoli intervalli in tutte le sessioni.

Potrebbero essere necessari 1-2 minuti prima che le tracce vengano visualizzate al termine di una query. Se non vedi ancora tracce, attendi un momento e aggiorna la pagina.

Come funziona il tracciamento

Quando esegui il deployment con --otel_to_cloud, adk deploy crea un container che esegue il server API ADK con OpenTelemetry attivato. In Agent Runtime, il server inizializza una pipeline OpenTelemetry che:

1. Crea un TracerProvider con un esportatore OTLP che invia gli span a telemetry.googleapis.com
2. Registra gli intervalli dell'ADK per le esecuzioni degli agenti, le chiamate di modelli e le chiamate di strumenti e utilizza i tre pacchetti di strumentazione di requirements.txt per aggiungere intervalli dalle librerie chiave (Gemini, httpx, gRPC)
3. Raggruppa ed esporta gli intervalli nell'API Telemetry, dove vengono letti dalla scheda Tracce

Il container di cui è stato eseguito il deployment include ADK e l'SDK e l'esportatore OpenTelemetry, ma non include i pacchetti di instrumentazione. Per questo motivo, l'elenco requirements.txt include tutti e tre. Senza, il server API ADK registra un avviso e ignora questi intervalli.

Risoluzione dei problemi

Se dopo qualche minuto non vengono visualizzate tracce:

1. Verifica che l'API Telemetry sia abilitata: l'hai abilitata nel passaggio di configurazione. Verifica con: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. Controlla Cloud Logging per avvisi: vai a Logging > Esplora log e cerca "proceeding without" o "GoogleGenAiSdkInstrumentor". Un avviso che indica uno strumento (GenAI, HTTPX o gRPC) significa che il pacchetto opentelemetry-instrumentation-* corrispondente non è presente in requirements.txt.
3. Non aggiungere google-cloud-aiplatform al tuo requirements.txt. adk deploy lo aggiunge automaticamente; dichiararlo manualmente può causare conflitti tra i pacchetti OpenTelemetry e interrompere silenziosamente la strumentazione.

9. Elimina

Per evitare addebiti continui, elimina le risorse create durante questo codelab.

Elimina l'agente di cui è stato eseguito il deployment dalla pagina Deployment nella console Cloud. Seleziona l'agente e fai clic su Elimina.

Le query BigQuery in questo codelab utilizzavano set di dati pubblici, che non comportano addebiti per l'archiviazione. I ruoli IAM che hai concesso rimangono nel progetto, ma non hanno alcun impatto sui costi.

Se hai creato un progetto specifico per questo codelab, puoi eliminare l'intero progetto:

gcloud projects delete <YOUR_PROJECT_ID>

(Facoltativo) Libera spazio nell'ambiente locale:

cd ~
rm -rf ~/adk-deploy-scale

10. Complimenti

Hai creato un agente data scientist stateful e ne hai eseguito il deployment in Agent Runtime.

Che cosa hai imparato

• Come creare un agente ADK con BigQueryToolset per l'accesso ai dati reali
• Come attivare la memoria persistente con Memory Bank utilizzando PreloadMemoryTool e after_agent_callback
• Come concedere le autorizzazioni IAM per il service account dell'agente di cui è stato eseguito il deployment
• Come eseguire il deployment in Agent Runtime e attivare l'osservabilità con Cloud Trace

Passaggi successivi

• Esegui query sui tuoi set di dati BigQuery privati concedendo all'agente di servizio Agent Runtime l'accesso ai tuoi dati.
• Aggiungi Esegui il codice per eseguire l'analisi Python in una sandbox sicura
• Configura le dashboard di osservabilità di Cloud Trace per monitorare l'agente in produzione
• Pubblica i risultati su Google Workspace utilizzando gli strumenti MCP

Documenti di riferimento

• Documentazione ADK
• Documentazione di Agent Runtime
• Documentazione di Memory Bank
• Guida all'implementazione di Agent Runtime