Créer un agent d'analyste Google Trends avec BigQuery MCP

1. Présentation

Dans cet atelier de programmation, vous allez créer un agent d'analyse Google Trends à l'aide du Google ADK. Cet agent exploite le serveur MCP BigQuery pour découvrir et exécuter dynamiquement des outils qui interrogent l'ensemble de données public Google Trends (bigquery-public-data.google_trends).

Points abordés

• Configurer un projet pour le développement ADK
• Découvrez comment activer et utiliser les serveurs MCP gérés pour BigQuery.
• Créer un agent qui utilise les outils MCP
• Comment exécuter l'agent localement pour le tester
• Découvrez comment déployer l'agent sur Google Cloud Run.

Prérequis

• Un projet Google Cloud avec facturation activée
• Un navigateur Web (par exemple, Chrome)
• Python 3.11+

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 15 à 20 minutes.

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.

Nous vous encourageons à utiliser Google Cloud Shell pour cet atelier de programmation. Il fournit un environnement de terminal avec Python et la Google Cloud CLI déjà installés.

Pour activer Cloud Shell, cliquez sur le bouton Activer Cloud Shell en haut de la console Google Cloud.

Définir des variables d'environnement

Définissez les variables d'environnement suivantes.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Remarque : Définir GOOGLE_GENAI_USE_VERTEXAI=1 indique à l'ADK d'utiliser Vertex AI, en tirant parti de Cloud IAM pour l'authentification au lieu d'un GEMINI_API_KEY.

S'authentifier et configurer gcloud

Connectez-vous à votre compte Google, définissez votre projet actif et configurez les identifiants par défaut de l'application.

Vous pouvez ignorer cette étape si vous utilisez Cloud Shell.

gcloud auth login
gcloud auth application-default login

Remarque : gcloud auth login authentifie les commandes CLI gcloud, tandis que gcloud auth application-default login authentifie le code d'application local.

Définissez le projet Google Cloud :

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Activer les API nécessaires

Activez les API Google Cloud requises pour Cloud Run, Artifact Registry, BigQuery et Vertex AI.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

Activer MCP pour BigQuery

Les serveurs MCP gérés doivent être explicitement activés pour votre projet.

gcloud beta services mcp enable bigquery.googleapis.com

Créer un dossier de projet

Commencez par créer un dossier racine pour votre agent et un dossier interne pour l'implémentation de l'agent.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. Créer le code de l'agent

Créez un fichier vide nommé google_trends/__init__.py :

touch google_trends/__init__.py

Créez ensuite un fichier nommé google_trends/agent.py et collez-y le code suivant :

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. Exécuter l'agent

Dans cette étape, vous allez configurer un environnement virtuel Python local, installer les dépendances et exécuter l'agent pour vérifier son comportement sur votre machine (ou dans Google Cloud Shell).

• Accédez au répertoire racine de l'application (google-trends-agent).
• Créez un environnement virtuel :

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Installez les packages Python requis :

pip install google-auth google-adk

Nous allons utiliser ADK Web pour tester notre nouvel agent.

Pour le développement et les tests en local, exécutez la commande suivante :

adk web

Pour le développement et les tests dans Google Cloud Shell, exécutez la commande suivante :

adk web --allow_origins="*"

Le serveur Web ADK démarre. Vous pouvez interagir avec l'agent à l'aide de l'interface Web locale (généralement à l'adresse http://localhost:8000).

Remarque : Vous pouvez également utiliser la commande adk run google_trends, plus simple, pour tester l'agent.

Essayez de poser les requêtes suivantes à votre agent :

• Montre-moi les principales tendances aux États-Unis
• Quelles sont les tendances les plus en vogue en France ce mois-ci ?
• Quelles ont été les trois principales tendances en Californie la semaine dernière ?
• Quelles sont les tables BigQuery auxquelles vous avez accès ?
• Dis-moi tout ce que tu sais sur la table top_trends.

5. Déployer dans Cloud Run

Suivez ces étapes pour déployer l'agent de manière sécurisée sur Google Cloud Run.

Octroyer des autorisations

Cloud Run a besoin d'une autorisation pour accéder à Vertex AI et utiliser les outils BigQuery MCP.

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.dataViewer"

Créer le fichier Dockerfile

À la racine de votre projet (google-trends-agent), créez un fichier nommé Dockerfile et collez-y le contenu suivant :

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

Déployer l'agent

Exécutez la commande suivante à partir du répertoire racine. Votre agent sera alors conteneurisé et déployé sur Cloud Run.

Surveillez le résultat de la commande. Une fois le déploiement terminé, une URL du service est fournie. Vous utiliserez cette URL pour interagir avec votre agent.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

Validation rapide

Une fois le déploiement terminé, la console affiche une URL du service. Ouvrez cette URL dans votre navigateur. Vous devriez voir la même interface utilisateur interactive que celle que vous avez vue localement, mais cette fois-ci exécutée dans le cloud.

Vous pouvez également surveiller les journaux pour vous assurer que tout fonctionne correctement :

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. Effectuer un nettoyage

Pour éviter des frais récurrents, supprimez les ressources créées pendant cet atelier de programmation.

Supprimez le service Cloud Run :

gcloud run services delete google-trends-agent --region us-west1

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

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Vous pouvez également supprimer tous les fichiers associés à cet atelier de programmation :

deactivate
cd ..
rm -rf google-trends-agent

7. Félicitations

Félicitations ! Vous avez réussi à créer et à déployer un agent Google Trends Analyst.

Connaissances acquises

• Utiliser MCP pour étendre dynamiquement les capacités de l'agent
• Créer et diffuser des agents LLM avec Google ADK
• Déployer et mettre à l'échelle des agents sur Cloud Run

Étapes suivantes

• Essayez de modifier l'agent pour interroger différents ensembles de données BigQuery.
• Ajoutez d'autres outils MCP pour étendre les capacités de l'agent.

Documents de référence

• Documentation ADK
• Guide des outils MCP
• BigQuery MCP
• Documentation Cloud Run