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

Analyser l'exécution de l'agent ADK avec le plug-in BigQuery Agent Analytics

1. Introduction

Dans cet atelier de programmation, vous allez créer un système multi-agents à l'aide de l'Agent Development Kit (ADK) et activer l'observabilité des agents à l'aide du plug-in BigQuery Agent Analytics.Vous allez poser une série de questions à l'agent, puis utiliser BigQuery pour analyser les traces de conversation et l'utilisation des outils de l'agent.

Objectifs de l'atelier

Créer un assistant commercial multi-agents à l'aide d'ADK
Initialisez le plug-in BigQuery Agent Analytics pour capturer et stocker les données de trace concernant l'exécution de cet agent dans BigQuery.
Analyser les données du journal de l'agent dans BigQuery

Prérequis

Un navigateur Web tel que Chrome
Un projet Google Cloud avec facturation activée
un compte Gmail ; La section suivante vous expliquera comment bénéficier d'un crédit de 5 $sans frais pour cet atelier de programmation et comment configurer un nouveau projet.

Cet atelier de programmation s'adresse aux développeurs de tous niveaux, y compris aux débutants. Vous utiliserez l'interface de ligne de commande dans Google Cloud Shell et le code Python pour le développement ADK. Vous n'avez pas besoin d'être un expert en Python, mais une compréhension de base de la lecture de code vous aidera à comprendre les concepts.

2. Avant de commencer

Créer un projet Google Cloud

Dans la console Google Cloud, sur la page de sélection du 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.

Démarrer Cloud Shell

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud et fourni avec les outils nécessaires.

Cliquez sur Activer Cloud Shell en haut de la console Google Cloud :

Une fois connecté à Cloud Shell, exécutez la commande suivante pour vérifier votre authentification dans Cloud Shell :

gcloud auth list

Exécutez la commande suivante pour vérifier que votre projet est configuré pour être utilisé avec gcloud :

gcloud config get project

Si votre projet n'est pas configuré comme prévu, utilisez la commande suivante pour le définir :

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Activer les API

Exécutez cette commande pour activer toutes les API et tous les services requis :

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

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

L'opération "operations/..." a bien été effectuée.

3. Installation et configuration

Revenez à Cloud Shell et assurez-vous d'être dans votre répertoire d'accueil.

Exécutez la commande suivante dans Cloud Shell pour créer un ensemble de données appelé "adk_logs" dans BigQuery :

bq mk --dataset --location=US adk_logs

À présent, créons un environnement Python virtuel et installons les packages requis.

Ouvrez un nouvel onglet de terminal dans Cloud Shell et exécutez cette commande pour créer un dossier nommé adk-agent-observability et y accéder :

mkdir adk-agent-observability
cd adk-agent-observability

Créez un environnement virtuel Python :

python -m venv .venv

Activez l'environnement virtuel :

source .venv/bin/activate

Installez ADK :

pip install --upgrade google-adk

4. Créer une application ADK

À présent, créons notre agent d'assistance pour le commerce. Cet agent sera conçu pour…

Exécutez la commande de l'utilitaire adk create pour créer une application d'agent avec les dossiers et fichiers nécessaires :

adk create retail_assistant_app

Suivez les instructions :

Choisissez le modèle gemini-2.5-flash.
Choisissez Vertex AI pour le backend.
Confirmez l'ID et la région de votre projet Google Cloud par défaut.

Voici un exemple d'interaction :

Cliquez sur le bouton "Ouvrir l'éditeur" dans Cloud Shell pour ouvrir l'éditeur Cloud Shell et afficher les dossiers et fichiers nouvellement créés :

Notez les fichiers générés :

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env

init.py: : marque le dossier comme module Python.
agent.py: : contient la définition initiale de l'agent.
.env : vous devrez peut-être cliquer sur Afficher > Activer/Désactiver les fichiers cachés pour afficher ce fichier.

Le fichier .env contient les variables d'environnement de votre projet. Mettez à jour toutes les variables qui n'ont pas été correctement définies à partir des invites :

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Définir votre agent

Définissons maintenant un système multi-agent hiérarchique.

Agent de tendances en temps réel : utilise la recherche Google pour trouver les tendances de mode actuelles.
Agent de données d'inventaire : utilise l'ensemble d'outils BigQuery pour interroger l'ensemble de données public thelook_ecommerce et trouver les produits disponibles.
Agent assistant commercial (racine) : orchestre le workflow en demandant conseil à l'agent Tendances et en demandant à l'agent Inventaire de trouver des produits correspondants.

Remplacez l'intégralité du contenu de retail_assistant_app/agent.py par le code suivant.

import os
import uuid
import asyncio
import google.auth
import dotenv
from google.genai import types
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.adk.tools import AgentTool, google_search
from google.adk.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

dotenv.load_dotenv()

# --- Configuration ---

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
DATASET_ID = "adk_logs"
TABLE_ID = "retail_assistant_agent_logs"
APP_NAME = "retail_assistant_agent"
USER_ID = "test_user"

# --- Toolsets ---

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

# --- Agents ---

# 1. Trend Spotter
real_time_agent = Agent(
   name="real_time_agent",
   model="gemini-2.5-flash",
    description="Researches external factors like weather, local events, and current fashion trends.",
   instruction="""
       You are a real-time research agent.
       Use Google Search to find real-time information relevant to the user's request,
       such as the current weather in their location or trending styles.
   """,
   tools=[google_search]
)

# 2. Inventory Manager
inventory_data_agent = Agent(
   name="inventory_data_agent",
   model="gemini-2.5-flash",
   description="Oversees product inventory in the BigQuery `thelook_ecommerce` dataset to find available items and prices.",
   instruction=f"""
   You manage the inventory. You have access to the `bigquery-public-data.thelook_ecommerce` dataset via the BigQuery toolset.
   Run all BigQuery queries the project id of: '{PROJECT_ID}'
  
   Your workflow:
   1. Look at the products table.
   2. Find items that match the requirements, factor in the results from the trend_setter agent if there are any.
   3. Return with a user friendly response, including the list of specific products and prices.
   """,
   tools=[bigquery_toolset]
)

# 3. Root Orchestrator
root_agent = Agent(
   name="retail_assistant",
   model="gemini-2.5-flash",   
   description="The primary orchestrator, responsible for handling user input, delegating to sub-agents, and synthesizing the final product recommendation.",
   instruction="""
   You are a Retail Assistant.   
   You can ask the 'real_time_agent' agent for any realtime information needed, or style advice, include any information provided by the user.
   You should ask the 'inventory_data_agent' agent to find a maximum of 3 available items matching that style.
   Combine the results into a recommendation.
   """,
   tools=[AgentTool(agent=real_time_agent)],
   sub_agents=[inventory_data_agent]
)

6. Générer des journaux avec le plug-in BigQuery Agent Analytics

Nous allons maintenant configurer le plug-in BigQuery Agent Analytics pour capturer les données d'exécution.

Pour ce faire, vous allez créer une instance de la classe App. Cette classe sert de conteneur d'exécution pour votre agent. Elle gère la boucle de conversation, l'état de l'utilisateur et orchestre tous les plug-ins associés (comme notre enregistreur d'analyse de l'agent).

Le code ci-dessous :

Initialise le plug-in de journalisation : crée BigQueryAgentAnalyticsPlugin avec les informations de connexion requises.
Intégration du plug-in : transmet le plug-in BigQuery initialisé au constructeur App, ce qui garantit que les événements d'exécution de l'agent sont automatiquement capturés et enregistrés.
Exécution et journaux de l'agent : exécute le flux de conversation via runner.run_async, tandis que le plug-in collecte et envoie simultanément toute la séquence d'événements à BigQuery avant de fermer ses ressources.

Copiez et collez ce code sous les définitions d'agent dans le fichier agent.py :

async def main(prompt: str):
    """Runs a conversation with the BigQuery agent using the ADK Runner."""
    bq_logger_plugin = BigQueryAgentAnalyticsPlugin(
        project_id=PROJECT_ID, dataset_id=DATASET_ID, table_id=TABLE_ID
    )
    app = App(name=APP_NAME, root_agent=root_agent, plugins=[bq_logger_plugin])
    runner = InMemoryRunner(app=app)

    try:
        session_id = f"{USER_ID}_{uuid.uuid4().hex[:8]}"

        my_session = await runner.session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID, session_id=session_id
        )

        async for event in runner.run_async(
            user_id=USER_ID,
            new_message=types.Content(
                role="user", parts=[types.Part.from_text(text=prompt)]
            ),
            session_id=my_session.id,
        ):
            if event.content.parts and event.content.parts[0].text:
                print(f"** {event.author}: {event.content.parts[0].text}")

    except Exception as e:
        print(f"Error in main: {e}")
    finally:
        print("Closing BQ Plugin...")
        await bq_logger_plugin.close()
        print("BQ Plugin closed.")

if __name__ == "__main__":
   prompts = [
       "what outfits do you have available that are suitable for the weather in london this week?",      
       "You are such a cool agent! I need a gift idea for my friend who likes yoga.",       
       "I'd like to complain - the products sold here are not very good quality!"
   ]
   for prompt, prompt in enumerate(prompts):
       asyncio.run(main(prompt))

Maintenant que l'instrumentation est en place, il est temps de voir l'agent en action. Exécutez le script pour déclencher le workflow de conversation.

python retail_assistant_app/agent.py

L'assistant commercial devrait orchestrer le workflow :

Il demande à l'agent de tendances en temps réel (real_time_agent) d'identifier la météo à Londres et de rechercher les tendances de mode appropriées.
Il délègue ensuite la requête à l'agent de données d'inventaire (inventory_data_agent) pour interroger l'ensemble de données BigQuery thelook_ecommerce et trouver les produits spécifiques qui correspondent à ces tendances.
Enfin, l'orchestrateur racine synthétise les résultats pour fournir une recommandation finale.

Pendant ce temps, le plug-in diffuse le tracé d'exécution de l'agent vers BigQuery.

7. Analyser les journaux d'agent

Utilisation des outils

Nous pouvons maintenant voir ce que notre agent a fait en arrière-plan. Les données ont été envoyées à BigQuery et sont prêtes à être analysées :

Dans la console Google Cloud, recherchez BigQuery.
Dans le volet Explorateur, localisez votre projet.
Développez l'ensemble de données adk_logs.
Ouvrez la table retail_assitant_agent_logs, puis cliquez sur Requête.

Pour voir les appels d'outil effectués par votre agent et capturer les éventuelles erreurs d'outil, exécutez la requête suivante dans l'éditeur BigQuery :

SELECT
   -- Extract text between "Tool Name: " and the next comma (or end of line)
   REGEXP_EXTRACT(content, r'Tool Name: ([^,]+)') AS tool_name,
   -- Count every time a tool finished (successfully or with an error)
   COUNT(*) AS total_finished_runs,
   -- Count it as a failure if it's an explicit system error OR contains "error" in the text
   COUNTIF(event_type = 'TOOL_ERROR' OR REGEXP_CONTAINS(content, r'(?i)\berror\b')) AS failure_count
FROM
   `.adk_logs.retail_assistant_agent_logs`
WHERE
   event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
   1

Cliquez sur "Visualisation" pour afficher les données sous forme de graphique :

Utilisation des jetons

Pour déduire le coût de vos agents, vous pouvez agréger les jetons d'invite et les jetons candidats consommés par chaque agent distinct :

SELECT
     t.agent,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'prompt:\s*(\d+)') AS INT64)) AS prompt_tokens,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'candidates:\s*(\d+)') AS INT64)) AS candidate_tokens
   FROM
     `adk_logs.retail_assistant_agent_logs` AS t
   WHERE
     t.event_type = 'LLM_RESPONSE'
     AND t.content LIKE '%Token Usage: %'
   GROUP BY 1

Cliquez sur "Visualisation" pour afficher les données sous forme de graphique :

8. [Bonus] Analyser le sentiment des utilisateurs

Analysons maintenant le sentiment de la saisie de l'utilisateur fournie à l'agent.

Créez une connexion à une ressource cloud pour permettre à BigQuery d'interagir avec les services Vertex AI :

bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Vous devriez obtenir une réponse semblable à la suivante :

La connexion 517325854360.us.test_connection a bien été créée

Créez une connexion de ressource Cloud :

export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)

Exécutez cette commande pour vérifier que le compte de service a bien été créé :

echo $SERVICE_ACCOUNT_EMAIL

Votre compte de service devrait s'afficher :

Accordez au compte de service de la connexion à la ressource les autorisations au niveau du projet requises pour interagir avec Vertex AI :

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/bigquery.connectionUser' \
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/aiplatform.user'

Attendez quelques minutes, puis exécutez la fonction BigQuery AI.SCORE pour analyser le sentiment des utilisateurs :

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', content,
   'Use a scale from 1 to 5.'),
 connection_id => 'us.test_connection') AS user_sentiment
FROM
 `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type = 'USER_MESSAGE_RECEIVED'
ORDER BY
 user_sentiment DESC;

La fonction AI.SCORE attribue une valeur de sentiment comprise entre 1 et 5 à chaque saisie utilisateur. Vous devriez obtenir des résultats semblables à ceux ci-dessous :

9. Effectuer un nettoyage

Pour éviter que les ressources créées lors de cet atelier soient facturées en permanence sur votre compte Google Cloud, supprimez-les.

Supprimez l'ensemble de données de journalisation créé par le script :

bq rm -r -f -d $PROJECT_ID:adk_logs

Pour supprimer le répertoire bigquery-adk-codelab et son contenu :

cd .. 
rm -rf adk-agent-observability

10. Félicitations

Félicitations ! Vous avez créé un système multi-agents avec l'Agent Development Kit (ADK) et intégré le plug-in BigQuery Agent Analytics pour suivre et auditer le comportement de votre agent.