1. Introduction
Les modèles d'IA générative sont de puissants outils de raisonnement, mais ils manquent de contexte institutionnel. Si un dirigeant demande à un agent IA "Quel est notre chiffre d'affaires du premier trimestre ?", l'agent peut trouver des dizaines de tables nommées "chiffre d'affaires" dans votre lac de données. Certains sont des rapports financiers rigoureux, d'autres sont des estimations marketing en temps réel, et beaucoup sont probablement des bacs à sable obsolètes.
Sans ancrage explicite, un agent IA sélectionnera une table en fonction d'une simple similarité de nom, ce qui entraînera des réponses "fausses, mais convaincantes" dérivées de données non vérifiées.
Cet atelier de programmation fait partie d'une série en deux parties qui explique comment créer un agent IA respectueux de la gouvernance.
Dans cette première partie, vous allez créer une infrastructure de données. Vous allez configurer un lac de données réaliste et "désordonné" dans BigQuery, appliquer des tags de métadonnées rigides (aspects Knowledge Catalog) pour différencier les données valides du bruit, et utiliser la CLI Antigravity (AGY) pour tester localement si l'agent respecte strictement vos règles de gouvernance des données.
Vous pouvez lire la deuxième partie de cette série, qui explique comment déployer le prototype d'agent local dans une application Web sécurisée de niveau entreprise à l'aide du protocole MCP (Model Context Protocol) et de Cloud Run. 👉 Lire la partie 2
Points abordés
- Déployer un lac de données réaliste à plusieurs niveaux à l'aide d'un script de configuration
- Concevez et enregistrez des modèles de métadonnées personnalisés (types d'aspects) dans Knowledge Catalog pour distinguer les produits de données officiels des tables de bac à sable brutes.
- Vérifiez les règles de gouvernance des données localement à l'aide de la CLI AGY avant d'écrire du code d'application.
Prérequis
- Un projet Google Cloud avec facturation activée.
- Accès à Google Cloud Shell (la CLI AGY est préinstallée dans Cloud Shell).
- Compréhension de base et connaissance de BigQuery et de Knowledge Catalog.
Concepts clés
- Knowledge Catalog : service de gestion unifiée des métadonnées. Nous l'utilisons pour enrichir les métadonnées techniques (schémas) avec un contexte métier (gouvernance).
- Type d'aspect : modèle de métadonnées structurées. Contrairement aux tags en texte libre, les aspects appliquent un typage fort (énumérations, booléens), ce qui les rend fiables pour l'évaluation par les machines.
2. Préparation
Démarrer Cloud Shell
Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Google Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.
Dans la console Google Cloud, cliquez sur l'icône Cloud Shell dans la barre d'outils supérieure :
Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :
Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez effectuer toutes les tâches de cet atelier de programmation dans un navigateur. Vous n'avez rien à installer.
Initialiser l'environnement
Ouvrez Cloud Shell et définissez vos variables de projet pour vous assurer que toutes les commandes ciblent la bonne infrastructure.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
Activer les API
Activez les services Google Cloud nécessaires pour exécuter l'instruction suivante.
gcloud services enable \
bigquery.googleapis.com \
dataplex.googleapis.com
Cloner le dépôt
Récupérez le code d'infrastructure et les scripts d'automatisation à partir du dépôt GitHub. Pour économiser de l'espace disque dans Cloud Shell, nous ne téléchargerons que le dossier spécifique nécessaire à cet atelier.
# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
Créer le lac de données "désordonné"
Les environnements de données réels sont rarement propres. Pour simuler la réalité, nous avons besoin d'un mélange de magasins de données "officiels" et de tables "sandbox" non fiables.
Nous allons utiliser un script de configuration pour déployer les ensembles de données et les tables BigQuery.
- Rendez le script de configuration exécutable et exécutez-le. Cela créera trois ensembles de données BigQuery (
finance_mart,marketing_prod,analyst_sandbox) et remplira leurs tables avec des exemples de données.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
Point de contrôle : vous disposez désormais d'un lac de données entièrement rempli, mais sans aucune gouvernance. Pour une IA, toutes les tables se ressemblent.
3. Créer le modèle de gouvernance des données (type d'aspect)
Nous allons maintenant définir des règles de gouvernance des données. Dans Knowledge Catalog, cela se fait en créant un type d'aspect, qui est un modèle de métadonnées réutilisable et fortement typé.
Nous allons enregistrer ce modèle à l'aide de la CLI gcloud pour que vous puissiez voir comment il est défini.
Inspecter le schéma d'aspect
Affichez le contenu de aspect_template.json pour voir la définition du schéma.
cat aspect_template.json
La structure JSON suivante s'affiche :
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
...
}
]
}
Notez que ce schéma applique des types de données stricts, tels que enum pour le niveau de criticité (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) et bool pour is_certified. Cela permet de s'assurer que les métadonnées restent structurées et lisibles par machine.
Enregistrer le type d'aspect
Exécutez la commande gcloud suivante pour enregistrer ce modèle dans votre registre Knowledge Catalog.
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
4. Appliquer la gouvernance
Il s'agit de l'étape d'ingénierie essentielle. Actuellement, les tables finance_mart.fin_monthly_closing_internal et analyst_sandbox.tmp_data_dump_v2_final_real sont identiques pour un LLM. Il s'agit simplement d'objets avec des colonnes.
En tant qu'ingénieur en gouvernance, vous devez associer un aspect (une étiquette de métadonnées certifiée) à ces tables pour les différencier. Dans une véritable entreprise, vous automatiseriez cette opération via des pipelines CI/CD. Nous allons simuler cette automatisation à l'aide de scripts.
Générer des charges utiles de gouvernance
Les clés d'aspect Knowledge Catalog doivent être uniques (préfixées par l'ID de votre projet). Le script ./generate_payloads.sh génère dynamiquement les fichiers de métadonnées YAML.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
Résultat :
Un dossier "./aspect_payloads" est alors créé. Il contient quatre fichiers YAML définissant les scénarios de gouvernance (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox).
Appliquer des aspects avec la CLI
Avant d'exécuter le script, examinons ce que nous appliquons réellement pour démystifier le processus. Exécutez la commande suivante pour afficher la structure de la charge utile financière interne :
cat aspect_payloads/fin_internal.yaml
Le contenu suivant s'affiche.
your-project-id.us-central1.official-data-product-spec:
data:
product_tier: GOLD_CRITICAL
data_domain: FINANCE
usage_scope: INTERNAL_ONLY
update_frequency: DAILY_BATCH
is_certified: true
Notez que ce fichier YAML définit explicitement le contexte métier, par exemple en définissant l'indicateur is_certified: true et en attribuant le niveau GOLD_CRITICAL. Fournir au LLM des règles claires et structurées à évaluer au lieu de le laisser deviner en fonction des noms de tables.
Exécutez maintenant le script de l'application. Cette opération parcourt les tables BigQuery et exécute la commande gcloud dataplex entries update pour associer ces métadonnées rigides.
chmod +x ./apply_governance.sh
./apply_governance.sh
Validation (facultatif)
Avant de continuer, vérifiez que les métadonnées ont été correctement appliquées dans la console.
- Ouvrez la page Catalogue de connaissances dans la console Google Cloud. Si vous ne voyez pas "Knowledge Catalog" dans le menu de navigation de gauche, utilisez la barre de recherche en haut de la fenêtre de la console Google Cloud, saisissez "Knowledge Catalog", puis sélectionnez le résultat sous "Meilleurs résultats" ou "Produits et pages".
- Recherchez
fin_monthly_closing_internal. La table BigQuery devrait s'afficher dans les résultats. Cliquez sur le nom de la table pour accéder à sa page d'informations.
- Sur la page d'informations de la table, recherchez la section Tags et aspects facultatifs en bas de la page.
- Vous trouverez l'aspect
official-data-product-spec. Vérifiez que les valeurs correspondent au scénario "Gold Internal" que nous avons appliqué.
Vous avez maintenant confirmé que des tables BigQuery techniquement identiques (fin_monthly_closing_internal et tmp_data_dump_v2_final_real) sont différenciées de manière logique par des métadonnées lisibles par machine.
5. Configurer et prototyper l'agent
Avant de créer une application (ce que nous ferons dans la partie 2), nous allons vérifier notre logique de gouvernance des données localement. Nous devons installer le plug-in Knowledge Catalog et configurer la compétence de l'agent.
Installer l'extension
Dans Cloud Shell, installez le plug-in Knowledge Catalog. Il vous demandera de confirmer et de fournir les détails de votre configuration.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
Inspecter la compétence de l'agent
La compétence de l'agent est un fichier de définition statique et réutilisable situé dans .agents/skills/knowledge_catalog_governance/SKILL.md. Il contient la logique qui traduit les règles humaines abstraites (par exemple, "J'ai besoin de données sécurisées") en recherches techniques strictes.
Inspectez le fichier pour comprendre l'algorithme que nous enseignons à l'IA :
cat .agents/skills/knowledge_catalog_governance/SKILL.md
Notez qu'il indique explicitement au modèle de suivre une boucle stricte de phase 1 (vérification des métadonnées) et de phase 2 (exécution de la requête). Le modèle doit découvrir et vérifier les métadonnées avant de créer une requête SQL.
Démarrer l'agent et tester des scénarios
Démarrez la session de la CLI AGY. Il détectera et chargera automatiquement la compétence à partir du répertoire .agents/skills.
agy
Remarque : Plusieurs fichiers de contexte peuvent être chargés. Ceci est normal. La CLI charge la compétence locale pour les règles spécifiques de ce projet, ainsi que les instructions par défaut pour le plug-in Knowledge Catalog lui-même.
Vérifier l'installation
Saisissez /mcp pour confirmer que le plug-in Knowledge Catalog est actif. knowledge-catalog doit s'afficher en tant que plug-in actif avec ses outils disponibles.
/mcp
Résultat attendu :
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
Scénarios de test (prototypage)
Collez les prompts suivants un par un dans la session de l'agent en cours d'exécution pour vérifier qu'il respecte vos règles.
- Scénario A (certifier les données du CFO) :
"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"
Résultat attendu : l'agent découvre automatiquement votre projet et votre région actifs à partir de ses outils, interroge fin_monthly_closing_internal, car il correspond sémantiquement à GOLD_CRITICAL (précis) et INTERNAL_ONLY (réunion du conseil d'administration) dans son aspect, et le recommande.
- Scénario B (divulgation publique) :
"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"
Attendu : L'agent doit ignorer le tableau interne mensuel et sélectionner strictement fin_quarterly_public_report, car il s'agit du seul élément tagué EXTERNAL_READY.
- Scénario C (besoins opérationnels) :
"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"
Résultat attendu : l'agent sélectionne mkt_realtime_campaign_performance, car il identifie la fréquence de mise à jour REALTIME_STREAMING, en la priorisant par rapport au niveau GOLD_CRITICAL des données financières.
- Scénario D (tests en bac à sable) :
"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."
Résultat attendu : l'agent sélectionne tmp_data_dump_v2_final_real, car il correspond sémantiquement à BRONZE_ADHOC (données brutes) et is_certified: false (environnement de bac à sable) dans son aspect.
(Pour quitter la session AGY, saisissez /exit ou /quit)
6. Félicitations ! Étape suivante
Vous avez créé une base de données gouvernée et prouvé qu'une IA peut suivre strictement vos règles de métadonnées à l'aide d'un prototype de CLI local.
Vous avez atteint un point de contrôle. Veuillez choisir l'étape suivante :
Option A : Je souhaite passer à la partie 2 dès maintenant.
Si vous êtes prêt à transformer ce prototype local en une application Web sécurisée de qualité production à l'aide du MCP (Model Context Protocol) et de Cloud Run :
👉 Lien vers la partie 2 de l'atelier de programmation
Option B : Je ferai la partie 2 plus tard ou je voulais seulement terminer la partie 1.
Si vous souhaitez vous arrêter là pour aujourd'hui et éviter des frais liés au cloud, vous devez nettoyer vos ressources.
Pas de panique ! Dans la partie 2, nous vous fournirons un "script d'accélération" qui reconstruira complètement l'environnement de la partie 1 en seulement deux minutes, afin que vous puissiez reprendre exactement là où vous vous étiez arrêté.
👉 Passez à la section "Nettoyage".
7. Nettoyage (pour l'option B uniquement)
Si vous vous arrêtez ici, détruisez les ressources pour éviter que des frais ne vous soient facturés.
Supprimer le lac de données
Si vous êtes actuellement dans la session de la CLI AGY, quittez-la en appuyant deux fois sur Ctrl+C ou en saisissant /quit. Exécutez ensuite les commandes suivantes :
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
Désinstaller le plug-in de la CLI AGY et supprimer les fichiers locaux
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos