Agent Data Science avec état sur Agent Runtime

1. Présentation

Dans cet atelier de programmation, vous allez créer un agent de science des données qui interroge des données réelles provenant d'ensembles de données publics BigQuery et mémorise vos préférences d'une session à l'autre. Vous le déploierez ensuite dans Agent Runtime, un service Google Cloud entièrement géré qui gère l'infrastructure, le scaling et la gestion des sessions.

L'agent utilise trois capacités fondamentales qui s'activent progressivement :

• Ensemble d'outils BigQuery : l'agent explore les schémas et exécute des requêtes SQL sur de véritables ensembles de données BigQuery. Cela fonctionne à la fois en local et lors du déploiement.
• Memory Bank : une fois déployé, l'agent se souvient des préférences et du contexte de l'utilisateur lors des sessions déconnectées.
• Observabilité : Cloud Trace capture les étapes de raisonnement, les appels d'outils et les latences de l'agent via l'instrumentation OpenTelemetry.

Points abordés

• Créer un agent ADK avec BigQueryToolset pour l'accès aux données réelles
• Configurer Memory Bank pour la persistance inter-session
• Déployer votre agent dans Agent Runtime avec adk deploy
• Accorder des autorisations IAM au compte de service de l'agent déployé
• Tester la persistance et l'observabilité de la mémoire

Prérequis

• Un projet Google Cloud avec facturation activée
• Un navigateur Web (par exemple, Chrome)
• Si vous exécutez le code sur votre propre machine au lieu de Cloud Shell : le Google Cloud SDK (CLI gcloud), uv (gestionnaire de paquets Python) et Python 3.12+ (installé automatiquement par uv si nécessaire)

ADK (Agent Development Kit) est le framework de Google permettant de créer des agents IA. Cet atelier de programmation utilise ADK pour créer un agent et le déployer sur Agent Runtime.

Cet atelier de programmation s'adresse aux développeurs intermédiaires qui connaissent déjà Python et Google Cloud.

Cet atelier de programmation prend environ 35 minutes (dont 5 à 10 minutes pour le déploiement).

Les ressources créées dans cet atelier de programmation devraient coûter moins de 5 $.

2. Configurer votre environnement

Créer un projet Google Cloud

1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
2. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Définir votre projet

Ouvrez l'éditeur Cloud Shell dans le projet GCP que vous avez créé.

Créez ensuite un terminal > Nouveau terminal, puis exécutez la commande suivante pour définir votre projet. Les commandes ultérieures lisent l'ID du projet à partir de ce paramètre.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Activer les API

Dans le terminal, exécutez la commande suivante.

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

• aiplatform.googleapis.com : héberge votre agent sur Agent Runtime, y compris les sessions Gemini Enterprise et la Memory Bank, et sert le modèle Gemini
• API BigQuery (bigquery.googleapis.com) : requêtes SQL sur des ensembles de données publics et privés
• API Telemetry (telemetry.googleapis.com) : traces OpenTelemetry pour l'observabilité des agents

L'activation de l'API peut prendre jusqu'à une minute. Si vous rencontrez des erreurs "API non activée" lors des étapes suivantes, patientez un instant et réessayez.

Installer ADK

Dans le terminal, exécutez les commandes suivantes pour créer un dossier pour cet atelier de programmation et installer ADK et ses dépendances :

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 crée un environnement Python isolé pour cet atelier de programmation. Vous n'avez donc rien à activer. Faites précéder les commandes Python de uv run.

Le package google-adk inclut l'outil CLI adk que vous utiliserez pour tester et déployer l'agent. adk deploy utilise google-cloud-aiplatform pour créer votre agent sur Agent Runtime, et google-cloud-bigquery est la bibliothèque cliente derrière les outils BigQuery de l'ADK.

3. Créer l'agent

Dans le dossier ~/adk-deploy-scale, créez le répertoire de l'agent. Exécutez toutes les commandes ultérieures à partir de ~/adk-deploy-scale (le parent de data_science_agent/) :

mkdir data_science_agent

Exécutez ensuite la commande suivante pour créer data_science_agent/.env avec votre projet, la région dans laquelle vous allez déployer l'agent et les paramètres de l'agent déployé. adk deploy lit ce fichier. Par conséquent, ces paramètres fonctionnent toujours si vous ouvrez un nouveau terminal.

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 et GOOGLE_CLOUD_LOCATION : ID de votre projet (renseigné à partir de gcloud) et région dans laquelle l'agent s'exécute
• GOOGLE_GENAI_USE_ENTERPRISE : a appelé Gemini via l'ADK dans votre projet Google Cloud
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT : enregistre les entrées de requête complètes et les réponses de l'agent, ce qui est utile pour le débogage.

Le paramètre OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT enregistre le contenu complet des requêtes utilisateur et des réponses de l'agent dans Cloud Logging. Cette option est utile pour le débogage, mais peut capturer des données sensibles ou des informations permettant d'identifier personnellement l'utilisateur. En production, définissez cette valeur sur false ou assurez-vous d'avoir mis en place des règles de gestion des données appropriées.

La structure finale de votre répertoire doit ressembler à ce qui suit :

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

Vous allez créer __init__.py et agent.py maintenant, puis ajouter requirements.txt à l'étape de déploiement.

Créez data_science_agent/__init__.py. Ce fichier est nécessaire pour qu'ADK puisse découvrir et charger votre agent :

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

Créez data_science_agent/agent.py :

Cet agent se connecte à BigQuery pour l'extraction de données et conserve les sessions dans Memory Bank.

La mémoire s'active automatiquement lors du déploiement. Agent Runtime définit la variable d'environnement GOOGLE_CLOUD_AGENT_ENGINE_ID, qui est absente lors de l'exécution en local.

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,
)

Examinons ce que fait ce code :

1. BigQueryToolset fournit à l'agent des outils tels que execute_sql, list_table_ids et get_table_info. Il peut explorer les schémas et interroger n'importe quel ensemble de données auquel l'appelant a accès.
2. PreloadMemoryTool récupère automatiquement les souvenirs pertinents avant chaque appel LLM en recherchant dans la Memory Bank du contenu lié au message de l'utilisateur. Le rappel _save_memory conserve la session dans Memory Bank après chaque exécution de l'agent, ce qui permet à l'agent de se souvenir du contexte lors des prochaines sessions.
3. App encapsule l'agent racine dans une application déployable qu'Agent Runtime peut diffuser. Le name doit correspondre au nom du répertoire (data_science_agent). adk web l'utilise pour localiser et charger l'agent.
4. L'instruction indique à l'agent d'utiliser le projet de facturation pour les requêtes SQL et de mémoriser les préférences de l'utilisateur.
5. Gemini avec client_kwargs={"location": "global"} envoie des appels de modèle au point de terminaison mondial, où gemini-3.8-flash est disponible. L'agent lui-même s'exécute dans us-central1. adk deploy définit GOOGLE_CLOUD_LOCATION sur l'agent déployé sur la région dans laquelle vous effectuez le déploiement. L'emplacement du modèle est donc défini dans le code.

4. Déployer dans Agent Runtime

Créez un fichier requirements.txt dans le répertoire 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 et google-genai : ADK et le client Gemini
• google-auth : authentification Google Cloud
• google-cloud-bigquery : bibliothèque cliente BigQuery utilisée par BigQueryToolset. L'ADK ne l'installe pas par défaut.
• python-dotenv : charge le fichier .env au démarrage.
• Les trois packages opentelemetry-instrumentation-* activent les fonctionnalités d'observabilité que vous explorerez plus tard. Ils instrumentent les appels de modèles Gemini et la communication gRPC/HTTP interne afin que les traces apparaissent dans l'onglet Traces de votre agent.

N'ajoutez pas google-cloud-aiplatform à votre requirements.txt, même si vous l'avez installé localement. adk deploy l'ajoute pour vous (ainsi que la version ADK avec laquelle vous déployez), mais uniquement lorsque votre requirements.txt ne l'indique pas déjà. Si vous le déclarez vous-même, cela peut entraîner des conflits de version de package OpenTelemetry qui interrompent l'instrumentation de manière silencieuse, ce qui empêche l'affichage des traces dans l'onglet "Traces".

adk deploy lit également le fichier data_science_agent/.env que vous avez créé précédemment et définit ses paramètres sur l'agent déployé.

Déployez l'agent. Le dernier argument data_science_agent est le répertoire contenant le code de votre agent :

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

Au début, le résultat affiche deux lignes jaunes, Ignoring GOOGLE_CLOUD_PROJECT in .env ... et Ignoring GOOGLE_CLOUD_LOCATION in .env .... Elles sont attendues : les options --project et --region sont prioritaires sur les mêmes valeurs dans .env.

Option	Objectif
--project/--region	Projet et région Google Cloud cibles
--display_name	Nom lisible affiché dans la console Cloud
--otel_to_cloud	Exporte les traces et les journaux OpenTelemetry vers Google Cloud, et active la télémétrie (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) sur l'agent déployé

Le déploiement prend généralement 5 à 10 minutes. Une fois l'opération terminée, le résultat affiche le nom de ressource de votre agent (projects/.../reasoningEngines/) et un lien permettant de l'afficher dans la console Cloud.

En attendant, consultez la documentation sur Memory Bank pour en savoir plus sur le fonctionnement de la mémoire inter-session.

Si le lien imprimé par adk deploy ne fonctionne pas, ouvrez la page Déploiements dans la console Cloud et cliquez sur votre agent.

Lorsque vous déployez des capacités sur Agent Runtime, deux d'entre elles s'activent automatiquement :

• Memory Bank : adk deploy connecte l'agent aux sessions et à Memory Bank sur son instance Agent Runtime. PreloadMemoryTool lit les données de la Memory Bank et _save_memory conserve automatiquement les sessions.
• Observabilité : Cloud Trace capture les étapes de raisonnement, les appels d'outils et les latences de l'agent.

5. Accorder des autorisations BigQuery

Vous devez accorder à BigQuery l'accès à l'agent de service Agent Runtime (agent de service AI Platform Reasoning Engine). Une fois déployé, l'agent s'exécute en tant que compte de service géré par Google (et non avec vos identifiants personnels). Il a donc besoin d'autorisations explicites pour exécuter des requêtes 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"

Chaque commande affiche Updated IAM policy for project [...] lorsqu'elle est exécutée avec succès.

Si vous ignorez cette étape, l'agent déployé renverra des erreurs 403 lors de l'exécution de requêtes SQL. Le rôle bigquery.jobUser est requis dans le projet de facturation (votre projet), et non dans le projet de données.

Remarque : bigquery.dataViewer accorde un accès en lecture à tous les ensembles de données de votre projet. Pour une utilisation en production, envisagez plutôt d'accorder ce rôle au niveau de l'ensemble de données.

6. Tester l'agent déployé

Ouvrez la page Déploiements dans la console Google Cloud. Cliquez sur l'agent déployé, puis sur l'onglet Playground.

Chaque requête peut prendre entre 10 et 30 secondes, car l'agent doit réfléchir, appeler des outils et renvoyer des résultats.

Testez les capacités de BigQuery :

1. "List the tables in bigquery-public-data.hacker_news"
   • Résultat attendu : l'agent appelle list_table_ids et renvoie les noms de tables, y compris full.
2. "Trouve le nombre de posts par an dans bigquery-public-data.hacker_news.full"
   • Résultat attendu : l'agent appelle execute_sql avec une requête SQL et renvoie un tableau des années et du nombre de posts.
3. "Quel a été le pourcentage de variation des posts d'une année sur l'autre ?"
   • Attendu : l'agent appelle execute_sql avec une requête SQL qui calcule la variation en pourcentage et renvoie les résultats.

7. Tester la persistance de la mémoire

Toujours dans le Playground, enseignez une préférence à l'agent :

1. "Mémorise que mon ensemble de données préféré est bigquery-public-data.hacker_news"
2. "Quelles tables contient-il ?"

Attendez quelques secondes que la mémoire persiste (le rappel _save_memory s'exécute après la réponse de l'agent).

Démarrez une nouvelle session en cliquant sur New Session (Nouvelle session) dans l'atelier, puis posez la question suivante :

3. "Quel est mon ensemble de données préféré ?"

L'agent doit se souvenir de bigquery-public-data.hacker_news, même s'il s'agit d'une toute nouvelle session sans historique de conversation. Voici pourquoi :

• _save_memory est conservé dans Memory Bank à chaque session via callback_context.add_session_to_memory().
• PreloadMemoryTool récupère les souvenirs pertinents avant chaque appel LLM.
• Memory Bank met en correspondance le contenu de manière sémantique, et pas seulement par mot clé.

Si l'agent ne se souvient pas de votre préférence, attendez 10 secondes et réessayez dans une autre session. La persistance de la mémoire est asynchrone et peut prendre un certain temps.

8. Découvrir Observability

Dans la console Cloud, accédez à l'agent déployé, puis cliquez sur l'onglet Traces.

Un tableau des sessions doit s'afficher, listant les sessions des requêtes de test que vous avez exécutées lors des étapes précédentes. Le tableau affiche des métriques récapitulatives pour chaque session : durée moyenne, appels de modèles, appels d'outils, utilisation de jetons et éventuelles erreurs.

Cliquez sur une session pour inspecter les détails de la trace, y compris :

• Un graphe orienté acyclique (DAG) de ses spans, qui montre la répartition étape par étape du raisonnement de l'agent, des appels d'outils (requêtes BigQuery) et des latences
• Entrées et sorties pour chaque portée (activées via la variable d'environnement OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT dans .env)
• Attributs de métadonnées tels que les ID de span et de trace, et le timing

Vous pouvez également passer à la vue "Span" (en haut de l'écran) pour afficher les spans individuels de toutes les sessions.

L'affichage des traces peut prendre une à deux minutes après l'exécution d'une requête. Si aucune trace ne s'affiche, patientez un instant, puis actualisez la page.

Fonctionnement du traçage

Lorsque vous effectuez un déploiement avec --otel_to_cloud, adk deploy crée un conteneur qui exécute le serveur d'API ADK avec OpenTelemetry activé. Sur Agent Runtime, le serveur initialise un pipeline OpenTelemetry qui :

1. Crée un TracerProvider avec un exportateur OTLP qui envoie des spans à telemetry.googleapis.com
2. Enregistre les propres spans de l'ADK pour les exécutions d'agents, les appels de modèles et les appels d'outils, et utilise les trois packages d'instrumentation de votre requirements.txt pour ajouter des spans à partir des bibliothèques clés (Gemini, httpx, gRPC)
3. Regroupe et exporte les spans vers l'API Telemetry, où l'onglet "Traces" les lit.

Le conteneur déployé inclut ADK ainsi que le SDK et l'exportateur OpenTelemetry, mais n'inclut pas les packages d'instrumentation. C'est pourquoi votre requirements.txt les liste toutes les trois. Sans ces informations, le serveur d'API ADK consigne un avertissement et ignore ces portées.

Dépannage

Si aucune trace ne s'affiche après quelques minutes :

1. Vérifiez que l'API Telemetry est activée : vous l'avez activée lors de l'étape de configuration. Valider avec : gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. Recherchez les avertissements dans Cloud Logging : accédez à Logging > Explorateur de journaux et recherchez "proceeding without" ou "GoogleGenAiSdkInstrumentor". Un avertissement mentionnant une instrumentation (GenAI, HTTPX ou gRPC) signifie que le package opentelemetry-instrumentation-* correspondant est manquant dans votre requirements.txt.
3. N'ajoutez pasgoogle-cloud-aiplatform à votre requirements.txt. adk deploy l'ajoute automatiquement. Si vous le déclarez vous-même, cela peut entraîner des conflits de packages OpenTelemetry et interrompre l'instrumentation sans que vous le sachiez.

9. Effectuer un nettoyage

Pour éviter que des frais ne vous soient facturés en continu, supprimez les ressources créées lors de cet atelier de programmation.

Supprimez l'agent déployé de la page Déploiements de la console Cloud. Sélectionnez votre agent, puis cliquez sur Supprimer.

Les requêtes BigQuery de cet atelier de programmation ont utilisé des ensembles de données publics, qui n'entraînent pas de frais de stockage. Les rôles IAM que vous avez attribués restent dans le projet, mais n'ont aucun impact sur les coûts.

Si vous avez créé un projet spécifiquement pour cet atelier de programmation, vous pouvez le supprimer entièrement :

gcloud projects delete <YOUR_PROJECT_ID>

(Facultatif) Nettoyez votre environnement local :

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

10. Félicitations

Vous avez créé un agent data science avec état et l'avez déployé sur Agent Runtime.

Connaissances acquises

• Créer un agent ADK avec BigQueryToolset pour l'accès aux données réelles
• Activer la mémoire persistante avec Memory Bank à l'aide de PreloadMemoryTool et after_agent_callback
• Accorder des autorisations IAM au compte de service de l'agent déployé
• Déployer sur Agent Runtime et activer l'observabilité avec Cloud Trace

Étapes suivantes

• Interrogez vos propres ensembles de données BigQuery privés en accordant à l'agent de service Agent Runtime l'accès à vos données.
• Ajoutez Exécution de code pour exécuter l'analyse Python dans un bac à sable sécurisé.
• Configurer des tableaux de bord Cloud Trace Observability pour surveiller votre agent en production
• Publier les résultats dans Google Workspace à l'aide des outils MCP

Documents de référence

• Documentation ADK
• Documentation Agent Runtime
• Documentation sur la Memory Bank
• Guide de déploiement d'Agent Runtime