Cette page a été traduite par l'API Cloud Translation.

Déployer, gérer et observer l'agent ADK sur Cloud Run

1. Introduction

Ce tutoriel vous guidera dans le déploiement, la gestion et la surveillance d'un agent puissant créé avec l'Agent Development Kit (ADK) sur Google Cloud Run. L'ADK vous permet de créer des agents capables de gérer des workflows complexes multi-agents. En tirant parti de Cloud Run, une plate-forme sans serveur entièrement gérée, vous pouvez déployer votre agent en tant qu'application conteneurisée et évolutive sans vous soucier de l'infrastructure sous-jacente. Cette combinaison puissante vous permet de vous concentrer sur la logique de base de votre agent tout en bénéficiant de l'environnement robuste et évolutif de Google Cloud.

Tout au long de ce tutoriel, nous allons explorer l'intégration fluide de l'ADK à Cloud Run. Vous apprendrez à déployer votre agent, puis vous vous plongerez dans les aspects pratiques de la gestion de votre application dans un environnement de type production. Nous vous expliquerons comment déployer de nouvelles versions de votre agent en toute sécurité en gérant le trafic. Vous pourrez ainsi tester de nouvelles fonctionnalités auprès d'un sous-ensemble d'utilisateurs avant un déploiement complet.

Vous vous entraînerez également à surveiller les performances de votre agent. Nous allons simuler un scénario réel en effectuant un test de charge pour observer les capacités de scaling automatique de Cloud Run en action. Pour obtenir des insights plus détaillés sur le comportement et les performances de votre agent, nous allons activer le traçage avec Cloud Trace. Vous obtiendrez ainsi une vue détaillée de bout en bout des requêtes qui transitent par votre agent, ce qui vous permettra d'identifier et de résoudre les éventuels goulots d'étranglement des performances. À la fin de ce tutoriel, vous comprendrez parfaitement comment déployer, gérer et surveiller efficacement vos agents optimisés par l'ADK sur Cloud Run.

Dans cet atelier de programmation, vous allez suivre une approche par étapes :

Créez une base de données PostgreSQL sur Cloud SQL à utiliser pour le service de session de base de données de l'agent ADK.
Configurer un agent ADK de base
Configurer le service de session de base de données à utiliser par le runner ADK
Déployer l'agent initialement sur Cloud Run
Tester la charge et inspecter l'autoscaling Cloud Run
Déployer une nouvelle révision de l'agent et augmenter progressivement le trafic vers les nouvelles révisions
Configurer le traçage cloud et inspecter le traçage de l'exécution de l'agent

Présentation de l'architecture

Prérequis

Vous êtes à l'aise avec Python.
Comprendre l'architecture full stack de base à l'aide du service HTTP

Points abordés

Structure de l'ADK et utilitaires locaux
Configurer l'agent ADK avec le service de session de base de données
Configurer PostgreSQL dans Cloud SQL pour l'utiliser avec le service de session de base de données
Déployer l'application sur Cloud Run à l'aide du fichier Dockerfile et configurer les variables d'environnement initiales
Configurer et tester l'autoscaling Cloud Run avec des tests de charge
Stratégie de déploiement progressif avec Cloud Run
Configurer le traçage de l'agent ADK vers Cloud Trace

Prérequis

Navigateur Web Chrome
Un compte Gmail
Un projet Cloud pour lequel la facturation est activée

Cet atelier de programmation, conçu pour les développeurs de tous niveaux (y compris les débutants), utilise Python dans son exemple d'application. Toutefois, vous n'avez pas besoin de connaître Python pour comprendre les concepts présentés.

2. Avant de commencer

Sélectionner le projet actif dans la console Cloud

Cet atelier de programmation suppose que vous disposez déjà d'un projet Google Cloud pour lequel la facturation est activée. Si vous ne l'avez pas encore, vous pouvez suivre les instructions ci-dessous pour commencer.

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
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.

Préparer la base de données Cloud SQL

Nous aurons besoin d'une base de données pour l'agent ADK ultérieurement. Commençons par créer une base de données PostgreSQL sur Cloud SQL. Tout d'abord, accédez à la barre de recherche en haut de la console Cloud et saisissez "cloud sql". Cliquez ensuite sur le produit Cloud SQL.

Ensuite, nous devrons créer une instance de base de données. Pour ce faire, cliquez sur Créer une instance et sélectionnez PostgreSQL.

Si vous commencez avec un nouveau projet, vous devrez peut-être également activer l'API Compute Engine. Si cette invite s'affiche, cliquez simplement sur Activer l'API.

Ensuite, nous allons choisir les spécifications de la base de données. Sélectionnez l'édition Enterprise avec le préréglage de l'édition Sandbox.

Ensuite, définissez le nom de l'instance et le mot de passe par défaut pour l'utilisateur postgres. Vous pouvez configurer cela avec les identifiants de votre choix. Toutefois, pour les besoins de ce tutoriel, nous utiliserons adk-deployment pour le nom de l'instance et le mot de passe.

Pour ce tutoriel, nous allons utiliser us-central1 avec une seule zone. Nous pouvons ensuite finaliser la création de notre base de données et laisser l'ensemble de la configuration requise se terminer en cliquant sur le bouton Créer une instance.

En attendant la fin de cette opération, nous pouvons passer à la section suivante.

Configurer un projet Cloud dans le terminal Cloud Shell

Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.

Une fois connecté à Cloud Shell, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :

gcloud auth list

Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.

gcloud config list project

Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

Vous pouvez également voir l'ID PROJECT_ID dans la console.

Cliquez dessus pour afficher tous vos projets et leur ID sur la droite.

Activez les API requises à l'aide de la commande ci-dessous. Cette opération peut prendre quelques minutes. Veuillez patienter.

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

Si la commande s'exécute correctement, un message semblable à celui ci-dessous s'affiche :

Operation "operations/..." finished successfully.

Vous pouvez également utiliser la console au lieu de la commande gcloud. Pour ce faire, recherchez chaque produit ou utilisez ce lien.

Si vous oubliez d'activer une API, vous pourrez toujours le faire au cours de l'implémentation.

Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.

Accéder à l'éditeur Cloud Shell et configurer le répertoire de travail de l'application

Nous pouvons maintenant configurer notre éditeur de code pour effectuer certaines tâches de codage. Pour cela, nous allons utiliser l'éditeur Cloud Shell.

Cliquez sur le bouton "Ouvrir l'éditeur" pour ouvrir un éditeur Cloud Shell dans lequel vous pourrez écrire votre code.
Assurez-vous que le projet Cloud Code est défini en bas à gauche (barre d'état) de l'éditeur Cloud Shell, comme indiqué dans l'image ci-dessous, et qu'il est défini sur le projet Google Cloud actif pour lequel la facturation est activée. Autoriser si vous y êtes invité. Si vous avez déjà suivi la commande précédente, le bouton peut également pointer directement vers votre projet activé au lieu du bouton de connexion.

Ensuite, clonons le répertoire de travail du modèle pour cet atelier de programmation à partir de GitHub en exécutant la commande suivante. Le répertoire de travail sera créé dans le répertoire deploy_and_manage_adk.

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

Ensuite, accédez à la section supérieure de l'éditeur Cloud Shell et cliquez sur Fichier > Ouvrir le dossier, recherchez votre répertoire nom d'utilisateur, puis le répertoire deploy_and_manage_adk, puis cliquez sur le bouton OK. Le répertoire choisi deviendra le répertoire de travail principal. Dans cet exemple, le nom d'utilisateur est alvinprayuda. Le chemin d'accès au répertoire est donc indiqué ci-dessous.

Votre éditeur Cloud Shell devrait maintenant se présenter comme suit :

Nous pouvons ensuite configurer notre environnement Python.

Configurer l'environnement

Préparer l'environnement virtuel Python

L'étape suivante consiste à préparer l'environnement de développement. Le répertoire de travail du terminal actif actuel doit se trouver dans le répertoire de travail deploy_and_manage_adk. Dans cet atelier de programmation, nous utiliserons Python 3.12 et le gestionnaire de projets Python uv pour simplifier la création et la gestion de la version Python et de l'environnement virtuel.

Si vous n'avez pas encore ouvert le terminal, ouvrez-le en cliquant sur Terminal > Nouveau terminal ou en utilisant le raccourci clavier Ctrl+Maj+C. Une fenêtre de terminal s'ouvre alors en bas du navigateur.

Téléchargez uv et installez Python 3.12 avec la commande suivante :

curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

Initialisons maintenant l'environnement virtuel à l'aide de uv. Exécutez cette commande :

uv sync --frozen

Cela créera le répertoire .venv et installera les dépendances. Un petit aperçu rapide du fichier pyproject.toml vous donnera des informations sur les dépendances, comme ceci :

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]

Pour tester l'environnement virtuel, créez un fichier main.py et copiez-y le code suivant :

def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()

Exécutez ensuite la commande suivante :

uv run main.py

Vous obtiendrez un résultat semblable à celui ci-dessous.

Using CPython 3.12
Creating virtual environment at: .venv
Hello from deploy_and_manage_adk!

Cela montre que le projet Python est correctement configuré.

Configurer les fichiers de configuration

Nous devons maintenant configurer les fichiers de configuration pour ce projet.

Renommez le fichier .env.example en .env. La valeur ci-dessous s'affichera. Mettez à jour la valeur GOOGLE_CLOUD_PROJECT avec l'ID de votre projet.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432

Pour cet atelier de programmation, nous allons utiliser les valeurs préconfigurées pour GOOGLE_CLOUD_LOCATION et GOOGLE_GENAI_USE_VERTEXAI.. Pour l'instant, nous allons laisser SESSION_SERVICE_URI en commentaire.

Nous pouvons maintenant passer à l'étape suivante : inspecter la logique de l'agent et la déployer.

3. Créer l'agent météo avec ADK et Gemini 2.5

Présentation de la structure des répertoires ADK

Commençons par explorer ce que l'ADK a à offrir et comment créer l'agent. La documentation complète de l'ADK est disponible sur cette URL . L'ADK nous offre de nombreux utilitaires dans l'exécution de commandes CLI. En voici quelques-uns :

Configurer la structure de répertoire de l'agent
Essayer rapidement l'interaction via l'entrée/sortie de la CLI
Configurer rapidement l'interface utilisateur Web de développement local

À présent, vérifions la structure de l'agent dans le répertoire weather_agent.

weather_agent/
├── __init__.py
├── agent.py

Si vous inspectez init.py et agent.py, vous verrez ce code.

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.cloud import logging as google_cloud_logging

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)

# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")


def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city (e.g., "New York", "London", "Tokyo").

    Returns:
        dict: A dictionary containing the weather information.
              Includes a 'status' key ('success' or 'error').
              If 'success', includes a 'report' key with weather details.
              If 'error', includes an 'error_message' key.
    """
    logger.log_text(
        f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
    )  # Log tool execution
    city_normalized = city.lower().replace(" ", "")  # Basic normalization

    # Mock weather data
    mock_weather_db = {
        "newyork": {
            "status": "success",
            "report": "The weather in New York is sunny with a temperature of 25°C.",
        },
        "london": {
            "status": "success",
            "report": "It's cloudy in London with a temperature of 15°C.",
        },
        "tokyo": {
            "status": "success",
            "report": "Tokyo is experiencing light rain and a temperature of 18°C.",
        },
    }

    if city_normalized in mock_weather_db:
        return mock_weather_db[city_normalized]
    else:
        return {
            "status": "error",
            "error_message": f"Sorry, I don't have weather information for '{city}'.",
        }


root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
    tools=[get_weather],
)

Explication du code ADK

Ce script contient l'initialisation de notre agent, où nous initialisons les éléments suivants :

Définissez le modèle à utiliser sur gemini-2.5-flash.
Fournis l'outil get_weather pour prendre en charge la fonctionnalité d'agent météo.

Exécuter l'UI Web

Nous pouvons maintenant interagir avec l'agent et inspecter son comportement localement. L'ADK nous permet de disposer d'une interface utilisateur Web de développement pour interagir et inspecter ce qui se passe pendant l'interaction. Exécutez la commande suivante pour démarrer le serveur d'interface utilisateur de développement local.

uv run adk web --port 8080

Il générera une sortie semblable à l'exemple suivant, ce qui signifie que nous pouvons déjà accéder à l'interface Web.

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Pour le vérifier, cliquez sur le bouton Aperçu Web en haut de l'éditeur Cloud Shell, puis sélectionnez Prévisualiser sur le port 8080.

La page Web suivante s'affiche. Vous pouvez y sélectionner les agents disponibles dans le menu déroulant en haut à gauche ( dans notre cas, il s'agit de weather_agent) et interagir avec le bot. De nombreuses informations sur les détails du journal s'affichent dans la fenêtre de gauche pendant l'exécution de l'agent.

Maintenant, essayez d'interagir avec lui. Dans la barre de gauche, nous pouvons inspecter la trace de chaque entrée. Nous pouvons ainsi comprendre le temps nécessaire à chaque action effectuée par l'agent avant de former la réponse finale.

Il s'agit de l'une des fonctionnalités d'observabilité intégrées à ADK. Pour le moment, nous l'inspectons localement. Nous verrons plus tard comment l'intégrer à Cloud Trace pour obtenir un suivi centralisé de toutes les requêtes.

4. Script du serveur backend

Pour rendre l'agent accessible en tant que service, nous l'encapsulerons dans une application FastAPI. Nous pouvons configurer les services nécessaires pour prendre en charge l'agent ici, comme la préparation des services Session, Memory ou Artifact à des fins de production. Voici le code de server.py qui sera utilisé.

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

Explication du code du serveur

Voici les éléments définis dans le script server.py :

Convertissez notre agent en application FastAPI à l'aide de la méthode get_fast_api_app. Nous hériterons ainsi de la même définition de route que celle utilisée pour l'UI de développement Web.
Configurez le service de session, de mémoire ou d'artefact nécessaire en ajoutant les arguments de mot clé à la méthode get_fast_api_app. Dans ce tutoriel, si nous configurons la variable d'environnement SESSION_SERVICE_URI, le service de session l'utilisera. Sinon, il utilisera la session en mémoire.
Nous pouvons ajouter un itinéraire personnalisé pour prendre en charge d'autres logiques métier de backend. Dans le script, nous ajoutons un exemple d'itinéraire de fonctionnalité de commentaires.
Activez le traçage dans le cloud pour envoyer la trace à Google Cloud Trace.

5. Déployer sur Cloud Run

Déployons maintenant ce service d'agent sur Cloud Run. Pour cette démonstration, ce service sera exposé en tant que service public accessible à tous. Toutefois, n'oubliez pas qu'il ne s'agit pas des bonnes pratiques, car cette méthode n'est pas sécurisée.

Dans cet atelier de programmation, nous allons utiliser Dockerfile pour déployer notre agent sur Cloud Run. Vous trouverez ci-dessous le contenu du Dockerfile qui sera utilisé.

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

À ce stade, nous disposons déjà de tous les fichiers nécessaires pour déployer nos applications sur Cloud Run. Déployons-les. Accédez au terminal Cloud Shell et assurez-vous que le projet actuel est configuré sur votre projet actif. Si ce n'est pas le cas, utilisez la commande gcloud configure pour définir l'ID du projet :

gcloud config set project [PROJECT_ID]

Exécutez ensuite la commande suivante pour le déployer sur Cloud Run.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
                  --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --region us-central1

Pour obtenir la valeur {YOUR_DB_CONNECTION_NAME}, vous pouvez de nouveau accéder à Cloud SQL et cliquer sur l'instance que vous avez créée. Sur la page de l'instance, faites défiler la page jusqu'à la section Se connecter à cette instance, puis copiez le nom de la connexion pour remplacer la valeur {YOUR_DB_CONNECTION_NAME}. Par exemple, regardez l'image ci-dessous.

Si vous êtes invité à confirmer la création d'un registre d'artefacts pour le dépôt Docker, répondez simplement Y. Notez que nous autorisons ici l'accès non authentifié, car il s'agit d'une application de démonstration. Nous vous recommandons d'utiliser une authentification appropriée pour vos applications d'entreprise et de production.

Une fois le déploiement terminé, vous devriez obtenir un lien semblable à celui ci-dessous :

https://weather-agent-*******.us-central1.run.app

N'hésitez pas à utiliser votre application depuis la fenêtre de navigation privée ou votre appareil mobile. Il devrait déjà être en ligne.

6. Inspecter l'autoscaling Cloud Run avec les tests de charge

Nous allons maintenant examiner les capacités d'autoscaling de Cloud Run. Dans ce scénario, déployons une nouvelle révision tout en activant le nombre maximal de simultanéités par instance. Exécutez la commande suivante :

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --concurrency 10

Ensuite, examinons le fichier load_test.py. Il s'agit du script que nous utiliserons pour effectuer le test de charge à l'aide du framework locust. Ce script effectue les actions suivantes :

user_id et session_id randomisés
Créer un session_id pour le user_id
Appelez le point de terminaison "/run_sse" avec les user_id et session_id créés.

Si vous l'avez manquée, nous aurons besoin de l'URL du service déployé. Accédez à la console Cloud Run et cliquez sur votre service weather-agent.

Recherchez ensuite votre service weather-agent et cliquez dessus.

L'URL du service s'affiche juste à côté des informations sur la région. Par exemple,

Exécutez ensuite la commande suivante pour effectuer le test de charge.

uv run locust -f load_test.py \
              -H {YOUR_SERVICE_URL} \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

En exécutant cette commande, vous verrez des métriques comme celles-ci s'afficher. ( Dans cet exemple, toutes les exigences sont remplies.)

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00

Ensuite, voyons ce qui s'est passé dans Cloud Run. Accédez de nouveau à votre service déployé et consultez le tableau de bord. Vous verrez ainsi comment Cloud Run met automatiquement à l'échelle l'instance pour traiter les requêtes entrantes. Étant donné que nous limitons la simultanéité maximale à 10 par instance, l'instance Cloud Run tentera d'ajuster automatiquement le nombre de conteneurs pour satisfaire cette condition.

7. Déployer progressivement de nouvelles révisions

Prenons l'exemple suivant. Nous souhaitons modifier la requête de l'agent comme suit :

# agent.py

...

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash-preview-05-20",
    instruction="You are a helpful AI assistant designed to provide accurate and useful information. You only answer inquiries about the weather. Refuse all other user query",
    tools=[get_weather],
)

Vous souhaitez ensuite publier de nouvelles révisions, mais vous ne voulez pas que tout le trafic de requêtes soit directement dirigé vers la nouvelle version. Nous pouvons effectuer une publication progressive avec Cloud Run. Nous devons d'abord déployer une nouvelle révision, mais avec l'indicateur –no-traffic. Enregistrez le script d'agent précédent et exécutez la commande suivante.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

Une fois l'opération terminée, vous recevrez un journal semblable à celui du processus de déploiement précédent, à la différence du nombre de requêtes traitées. Le trafic diffusé sera de 0 %.

Ensuite, accédez à la page produit Cloud Run et recherchez votre instance déployée. Saisissez "cloud run" dans la barre de recherche, puis cliquez sur le produit Cloud Run.

Recherchez ensuite votre service weather-agent et cliquez dessus.

Accédez à l'onglet Révisions pour afficher la liste des révisions déployées.

Vous verrez que la nouvelle révision déployée ne diffuse aucune annonce. Vous pouvez alors cliquer sur le bouton en forme de kebab (⋮) et sélectionner Gérer le trafic.

Dans la fenêtre pop-up qui s'affiche, vous pouvez modifier le pourcentage de trafic dirigé vers les révisions.

Après un certain temps, le trafic sera réparti proportionnellement en fonction des configurations de pourcentage. Ainsi, nous pouvons facilement revenir aux révisions précédentes en cas de problème avec la nouvelle version.

8. Traçage ADK

Les agents créés avec ADK sont déjà compatibles avec le traçage à l'aide de l'intégration OpenTelemetry. Nous disposons de Cloud Trace pour capturer et visualiser ces traces. Examinons le fichier server.py pour voir comment l'activer dans le service que nous avons déployé précédemment.

# server.py

from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export

...

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

...

Ici, nous initialisons le traceur et l'exportateur. Vous pouvez consulter les détails de l'exportateur sur tracing.py . Ici, nous créons un exportateur personnalisé, car il existe une limite de données de trace pouvant être exportées vers Cloud Trace. Pour cette fonctionnalité de traçage, nous utilisons une implémentation de https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html.

Essayez d'accéder à l'interface utilisateur Web de votre service et discutez avec l'agent. Ensuite, accédez à la barre de recherche de la console Cloud, saisissez "explorateur Trace", puis sélectionnez le produit Explorateur Trace.

Sur la page de l'explorateur de traces, vous verrez que la trace de notre conversation avec l'agent a été envoyée. Vous pouvez le voir dans la section Nom de la portée et filtrer la portée spécifique à notre agent ( nommée agent_run [weather_agent]).

Lorsque les portées sont déjà filtrées, vous pouvez également inspecter chaque trace directement. Elle indique la durée détaillée de chaque action effectuée par l'agent. Par exemple, regardez les images ci-dessous.

Dans chaque section, vous pouvez inspecter les détails dans les attributs, comme indiqué ci-dessous.

Voilà, nous disposons maintenant d'une bonne observabilité et d'informations sur chaque interaction de notre agent avec l'utilisateur pour nous aider à résoudre les problèmes. N'hésitez pas à essayer différents outils ou workflows.

9. Défi

Essayez les workflows multi-agents ou agentiques pour voir comment ils se comportent sous charge et à quoi ressemble la trace.

10. Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cet atelier de programmation soient facturées sur votre compte Google Cloud :

Dans la console Google Cloud, accédez à la page Gérer les ressources.
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.
Vous pouvez également accéder à Cloud Run dans la console, sélectionner le service que vous venez de déployer, puis le supprimer.