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 de manière dynamique 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
- Activer et utiliser des serveurs MCP gérés pour BigQuery
- Créer un agent qui utilise des outils MCP
- Exécuter l'agent localement pour le tester
- Déployer l'agent sur Google Cloud Run
Ce dont vous avez besoin
- Un projet Google Cloud avec facturation activée
- Un navigateur Web (par exemple, Chrome)
- Python 3.11 ou version ultérieure
Cet atelier de programmation s'adresse aux développeurs intermédiaires qui connaissent 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
- 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 pour un projet.
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 exploitant Cloud IAM pour l'authentification au lieu d'une GEMINI_API_KEY.
Authentifier et configurer gcloud
Connectez-vous à votre compte Google, définissez votre projet actif et configurez les identifiants par défaut de l'application.
gcloud auth login
gcloud auth application-default login
Remarque : gcloud auth login authentifie les commandes de la CLI gcloud, tandis que gcloud auth application-default login authentifie le code de l'application locale.
Définissez le projet Google Cloud :
gcloud config set project ${GOOGLE_CLOUD_PROJECT}
Activer les API requises
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
Vous devez activer explicitement les serveurs MCP gérés pour votre projet.
gcloud beta services mcp enable bigquery.googleapis.com
Créer un dossier pour le 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
Ensuite, créez un fichier nommé google_trends/agent.py et collez 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 ordinateur (ou 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[mcp]
Nous allons utiliser ADK Web pour tester notre nouvel agent.
Pour le développement et les tests locaux, 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 plus simple adk run google_trends pour tester l'agent.
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 MCP BigQuery.
# 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}-compute@developer.gserviceaccount.com" \
--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}-compute@developer.gserviceaccount.com" \
--role="roles/mcp.toolUser"
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--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 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 conteneurisé et déployé sur Cloud Run.
gcloud run deploy google-trends-agent \
--source . \
--region us-west1 \
--allow-unauthenticated \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"
Vérification rapide
Une fois le déploiement terminé, la console affiche une URL de service. Ouvrez cette URL dans votre navigateur. Vous verrez la même interface utilisateur interactive que celle que vous avez vue localement, mais elle s'exécute désormais dans le cloud.
Vous pouvez également surveiller les journaux pour vous assurer que tout se passe bien :
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 continus, supprimez les ressources créées lors de 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 liés à cet atelier de programmation :
deactivate
cd ..
rm -rf google-trends-agent
7. Félicitations
Félicitations ! Vous avez créé et déployé un agent d'analyse Google Trends.
Connaissances acquises
- Utiliser MCP pour étendre les capacités de l'agent de manière dynamique
- 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.