Créer et déployer des agents d'IA avec Gemini et le serveur MCP BigQuery dans Cloud Run

1. Introduction

Points abordés

• Créer un agent IA à l'aide d'Agent Development Kit (ADK) avec Gemini dans Agent Platform.
• Accorder aux agents IA l'accès à des données structurées dans BigQuery à l'aide du serveur BigQuery MCP

Cloud Run est une plate-forme de calcul sans serveur entièrement gérée qui vous permet d'exécuter des applications et des services conteneurisés sans avoir à gérer l'infrastructure sous-jacente.

Agent Development Kit (ADK) est un framework de développement d'agents Open Source qui vous permet de créer, de déboguer et de déployer des agents IA fiables à l'échelle de l'entreprise.

BigQuery est un entrepôt de données d'entreprise sans serveur entièrement géré qui vous permet de stocker, d'interroger et d'analyser des ensembles de données volumineux.

Le Model Context Protocol (MCP) standardise la façon dont les grands modèles de langage (LLM) et les applications ou agents IA se connectent à des sources de données externes. Les serveurs MCP vous permettent d'utiliser leurs outils, leurs ressources et leurs prompts pour effectuer des actions et obtenir des données mises à jour à partir de leur service de backend. Le serveur BigQuery MCP offre à vos agents IA un moyen direct et sécurisé d'analyser les données dans BigQuery. Ce serveur MCP entièrement géré élimine la surcharge de gestion, ce qui vous permet de vous concentrer sur le développement d'agents intelligents.

2. Préparation

L'ensemble de cet atelier peut être exécuté sur la ligne de commande. Vous pouvez utiliser Cloud Shell (cliquez sur l'icône d'invite en haut à droite de la console) pour démarrer l'environnement.

Commencez par définir le projet par défaut et la région Cloud Run :

# set the project
gcloud config set project YOUR_PROJECT_ID

Remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud.

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

Remplacez CLOUD-RUN-REGION par l'une des régions compatibles avec Cloud Run.

Voici les variables d'environnement qui seront utilisées tout au long de cet atelier de programmation. Vous pouvez les enregistrer dans un fichier d'environnement et les "sourcer". Veillez à définir correctement la valeur de l'ID de votre projet et, éventuellement, de la région.

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

Remarque : Il est utile d'enregistrer cet extrait en tant que fichier de script et de le réutiliser à l'avenir, lorsque la session Cloud Shell est réinitialisée. Enregistrez-le sous le nom env.sh et exécutez source env.sh pour définir les variables d'environnement lors des étapes suivantes. N'effectuez pas de commit env.sh dans les systèmes de contrôle des versions.

Activez les API nécessaires pour cet atelier de programmation. La prise en compte des modifications apportées à l'API peut prendre deux à trois minutes.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Créer un agent de données à l'aide d'Agent Development Kit

Écrire le code de l'agent

Depuis le terminal Cloud Shell ou votre terminal local, créez un répertoire racine pour votre application d'agent :

mkdir data_agent

Ouvrez l'éditeur Cloud Shell ou un autre éditeur de texte, puis créez agent.py dans le répertoire data_agent :

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

ADK nécessite également __init__.py et requirements.txt pour le déploiement :

• __init__.py doit comporter une importation pour l'agent.
• requirements.txt liste les dépendances Python : google-adk pour Agent Development Kit et mcp pour le client Model Context Protocol.

Ces commandes vous aident à créer __init__.py et requirements.txt :

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

La structure finale des dossiers doit ressembler à ceci :

data_agent/
    __init__.py
    agent.py
    requirements.txt

Essayer l'agent en local

Agent Development Kit est fourni avec l'outil CLI adk, une interface de terminal interactive permettant de tester vos agents. Cela est utile pour les tests rapides, les interactions scriptées et les pipelines CI/CD. L'une des fonctionnalités qu'il fournit est adk web (interface Web ADK), un moyen simple de développer et de déboguer vos agents de manière interactive. ADK Web n'est pas destiné à être utilisé dans les déploiements en production, mais il permet d'essayer l'agent très facilement.

Remarque : Avant d'exécuter cette commande, assurez-vous que votre répertoire actuel contient le répertoire data_agent (avec la commande ls).

Cette commande lance adk web, qui démarre un serveur Web local sur le port 8080.

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

Une fois le service démarré, ouvrez la page Web ADK locale : http://localhost:8080/.

Si vous utilisez Google Cloud Shell, cliquez sur le bouton Aperçu sur le Web , puis sélectionnez l'élément de menu "Prévisualiser sur le port 8080".

Dans l'UI Web ADK, demandez à l'agent les données auxquelles il a accès :

What data do you have?

L'agent utilisera les outils BigQuery MCP pour explorer l'ensemble de données citibike. Il vous donnera un aperçu des tables et des champs disponibles dans l'ensemble de données Citibike.

4. Déployer l'agent sur Cloud Run

Cette commande déploiera l'agent sur Cloud Run à l'aide de la CLI ADK.

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

Essayer l'agent

Nous avons utilisé l'option --with_ui pour le déploiement de notre agent. Il a déployé l'agent avec l'interface Web ADK.

1. Ouvrez l'URL de l'agent dans le navigateur Web. La commande adk deploy l'a renvoyée, et vous pouvez également la récupérer en exécutant la commande gcloud run services :

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

2. Demandez à l'agent de raisonner sur les données Citibike disponibles :

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

L'agent doit explorer l'ensemble de données Citibike à l'aide du serveur BigQuery MCP, exécuter quelques requêtes SQL et renvoyer une liste de trois stations citibike.

5. Félicitations !

Bravo ! Vous avez terminé cet atelier de programmation.

Nous vous recommandons de consulter la documentation Cloud Run.

Points abordés

• Créer un agent IA avec Agent Development Kit et Gemini
• Connecter l'agent au serveur BigQuery MCP
• Déployer l'agent sur Cloud Run

6. Libérer de l'espace

Pour éviter que les ressources utilisées lors de ce tutoriel continuent d'être facturées sur votre compte Google Cloud, supprimez le projet ou les ressources individuelles.

Option 1 : Supprimer le service

Supprimer le service Cloud Run

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

Option 2 : Supprimer le projet

Pour supprimer l'ensemble du projet, accédez à Gérer les ressources, sélectionnez le projet que vous avez créé à l'étape 2, puis choisissez Supprimer. Si vous supprimez le projet, vous devrez modifier les projets dans votre Cloud SDK. Vous pouvez afficher la liste de tous les projets disponibles en exécutant gcloud projects list. Si vous souhaitez rester sur la ligne de commande, vous pouvez également utiliser cette commande :

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}