Data Science Agent stateful su Agent Engine

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 implementerai in Agent Engine, 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 durante il deployment.
• Memory Bank: una volta implementato, l'agente ricorda le preferenze e il contesto dell'utente in più 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 Engine 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
• Google Cloud SDK (CLI gcloud)
• Un browser web come Chrome
• uv (gestore di pacchetti Python)
• 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 Engine.

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

Imposta le variabili di ambiente

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

Quindi crea un terminale (Terminale > Nuovo terminale) ed esegui i seguenti comandi.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Abilita API

Nel terminale, esegui questo comando.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT

• API AI Platform (aiplatform.googleapis.com) - Hosting di Agent Engine
• 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.

Crea un ambiente virtuale e installa ADK

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

Il pacchetto google-adk include lo strumento CLI adk che utilizzerai per testare e implementare l'agente.

3. Crea l'agente

Crea una nuova directory del progetto dell'agente. Tutti i comandi successivi devono essere eseguiti da questa directory di lavoro (la directory principale di data_science_agent/):

mkdir data_science_agent

La struttura di directory finale avrà questo aspetto:

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

Ora creerai __init__.py e agent.py, poi aggiungerai requirements.txt e .env 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 al momento del deployment. La variabile di ambiente GOOGLE_CLOUD_AGENT_ENGINE_ID viene impostata dal runtime di Agent Engine ed è assente 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.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export 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 the Agent Engine 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 Engine 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-2.5-pro",
    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 i ricordi pertinenti prima di ogni chiamata LLM cercando in 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 richiamare il contesto nelle sessioni future.
3. App racchiude l'agente principale in un'applicazione di cui è possibile eseguire il deployment e che può essere pubblicata da Agent Engine. 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.

4. Esegui il deployment in Agent Engine

Crea un file requirements.txt nella directory data_science_agent:

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk e google-genai: il framework ADK e il client Gemini
• google-auth: autenticazione Google Cloud
• python-dotenv: carica il file .env all'avvio
• I quattro pacchetti opentelemetry-instrumentation-* abilitano le funzionalità di osservabilità che esplorerai in un secondo momento. Strumentano le richieste HTTP FastAPI, le chiamate al modello Gemini e la comunicazione gRPC/HTTP interna in modo che le tracce vengano visualizzate nella scheda Tracce di Agent Engine.

Non aggiungere google-cloud-aiplatform[agent-engines] al requirements.txt. La CLI di deployment dell'ADK aggiunge automaticamente questa dipendenza durante il deployment. La sua nuova dichiarazione con una versione diversa può causare conflitti tra le versioni dei pacchetti OpenTelemetry che interrompono silenziosamente l'instrumentazione, impedendo la visualizzazione delle tracce nella scheda Tracce.

Crea un file .env nella directory data_science_agent per abilitare la telemetria sull'agente di cui è stato eseguito il deployment:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: attiva la pipeline OpenTelemetry nel runtime di Agent Engine.
• 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.

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

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

Flag	Finalità
--project/--region	Progetto cloud e regione Google Cloud di destinazione
--display_name	Nome leggibile mostrato nella console Cloud
--trace_to_cloud	Abilita l'esportatore Cloud Trace per gli span dell'agente
--otel_to_cloud	Attiva la pipeline di instrumentazione OpenTelemetry

In genere, il deployment richiede 5-10 minuti. Al termine, vedrai: Created agent engine: projects/.../reasoningEngines/

Durante l'attesa, consulta la documentazione di Memory Bank per scoprire di più su come funziona la memoria cross-session.

L'URL stampato da adk deploy potrebbe essere errato. Se il link non funziona, vai alla pagina Agent Engine in Cloud Console e fai clic sull'agente.

Quando viene eseguito il deployment in Agent Engine, vengono attivate automaticamente due funzionalità:

• Memory Bank: PreloadMemoryTool si connette a Memory Bank di Agent Engine 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. Concedere le autorizzazioni BigQuery

Devi concedere l'accesso a BigQuery al service account Agent Engine. Una volta eseguito il deployment, l'agente viene eseguito come 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 $GOOGLE_CLOUD_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 $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

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

Ogni comando stampa Updated IAM policy for project [...] se viene eseguito correttamente.

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 Agent Engine nella console Google Cloud. Fai clic sull'agente di cui è stato eseguito il deployment per aprire Agent Engine 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 sul pulsante "+ Nuova sessione" nella barra laterale del 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. Funziona perché:

• _save_memory memorizza ogni sessione in 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 un'altra 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 (abilitati 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 attimo e aggiorna la pagina.

Come funziona il tracciamento

Quando esegui il deployment con --trace_to_cloud e --otel_to_cloud, il runtime di Agent Engine inizializza una pipeline OpenTelemetry che:

1. Crea un TracerProvider con un esportatore OTLP che invia gli intervalli a telemetry.googleapis.com
2. Utilizza i quattro pacchetti di strumentazione del tuo requirements.txt per acquisire gli intervalli dalle librerie chiave (FastAPI, Gemini, httpx, gRPC). google-genai è strumentato in modo esplicito dal runtime, mentre gli altri contribuiscono tramite il rilevamento automatico di OpenTelemetry
3. I batch e le esportazioni si estendono all'API Telemetry, dove vengono letti dalla scheda Trace.

L'immagine di base di Agent Engine fornisce l'SDK e l'esportatore OpenTelemetry, ma non include i pacchetti di instrumentazione. Per questo motivo, il tuo requirements.txt deve elencare tutti e quattro gli elementi. In caso contrario, non vengono creati intervalli e non vengono visualizzate tracce.

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=$GOOGLE_CLOUD_PROJECT | grep telemetry
2. Controlla Cloud Logging per avvisi: vai a Logging > Esplora log e cerca "telemetry enabled but proceeding without". Se visualizzi un avviso relativo all'instrumentazione dell'AI generativa, opentelemetry-instrumentation-google-genai non è presente nel tuo requirements.txt.
3. Non aggiungere google-cloud-aiplatform[agent-engines] al tuo requirements.txt. La CLI di deployment dell'ADK lo aggiunge automaticamente; la sua nuova dichiarazione con una versione diversa 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 Agent Engine in Cloud Console. Seleziona l'agente e fai clic su Elimina.

Le query BigQuery in questo codelab hanno utilizzato set di dati pubblici, che non comportano costi di 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 ${GOOGLE_CLOUD_PROJECT}

(Facoltativo) Libera spazio nell'ambiente locale:

deactivate
rm -rf .venv data_science_agent

10. Complimenti

Hai creato un agente data science stateful e ne hai eseguito il deployment in Agent Engine.

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 Engine e abilitare l'osservabilità con Cloud Trace

Passaggi successivi

• Esegui query sui tuoi set di dati BigQuery privati concedendo all'account di servizio Agent Engine 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.
• Pubblicare i risultati su Google Workspace utilizzando gli strumenti MCP

Documenti di riferimento

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