Utiliser l'interface de ligne de commande Antigravity pour tester le contexte des données

L'enrichissement des métadonnées dans Knowledge Catalog (anciennement Dataplex Universal Catalog) vous permet de fournir un contexte de données structurées afin que les agents IA puissent ancrer leurs réponses dans des sources fiables et certifiées. Dans ce tutoriel, vous allez associer des aspects personnalisés à des exemples de tables BigQuery et utiliser la CLI Antigravity pour tester la façon dont un agent IA applique vos règles de gouvernance.

Objectifs

  • Déployez un lac de données réaliste à plusieurs niveaux dans BigQuery pour le tester.
  • 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 brutes du bac à sable.
  • Vérifiez les règles de gouvernance des données et l'ancrage de l'agent IA à l'aide de la CLI Antigravity (agy).

Avant de commencer

Avant de commencer, veillez à effectuer les opérations suivantes :

Pour suivre ce tutoriel, vous devez également posséder des connaissances de base sur BigQuery et Knowledge Catalog.

Préparer votre environnement

Ce tutoriel utilise Google Cloud Shell, un environnement de ligne de commande qui s'exécute dans le cloud. La CLI Antigravity (agy) est préinstallée dans Google Cloud Shell.

  1. Dans la console Google Cloud , cliquez sur Activer Cloud Shell dans la barre d'outils en haut à droite. Le provisionnement et la connexion à l'environnement prennent quelques instants.

  2. Dans Cloud Shell, définissez vos variables PROJECT_ID et REGION afin que toutes les futures commandes ciblent votre projet Google Cloud spécifique.

    export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

  3. Activez les services Google Cloud nécessaires.

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

  4. Clonez le dépôt de démonstrations DevRelGoogle Cloud .

    Téléchargez le code et les scripts d'infrastructure depuis GitHub. Utilisez un Sparse Checkout pour n'extraire que le dossier spécifique dont vous avez besoin pour ce tutoriel.

    # 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 you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

Déployer un exemple de lac de données dans BigQuery

Les environnements de données réels sont rarement propres. Les agents IA peuvent raisonner, mais ils ne connaissent rien de votre entreprise au départ. Imaginez que vous demandiez à un agent : "Quel est notre chiffre d'affaires du premier trimestre ?" Sans instructions, l'agent peut choisir parmi des dizaines de tables nommées "revenus" dans vos bases de données, allant des rapports officiels aux données de test brutes. Si l'agent choisit la table dont le nom est le plus proche, il peut renvoyer des réponses erronées, mais convaincantes, basées sur des sources non vérifiées.

Pour simuler ce scénario, vous avez besoin d'une combinaison de magasins de données "officiels" et de tables de "bac à sable" non approuvées. Vous utilisez 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. Cette opération crée trois ensembles de données BigQuery (finance_mart, marketing_prod, analyst_sandbox) et remplit leurs tables avec des exemples de données :

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

Vous disposez maintenant d'un lac de données entièrement rempli, mais non gouverné. Pour un agent IA, toutes les tables se ressemblent.

Définir un type d'aspect personnalisé dans Knowledge Catalog

Vous allez maintenant définir les règles de gouvernance de vos données. Pour ce faire, dans Knowledge Catalog, vous créez un type d'aspect, qui est un modèle de métadonnées réutilisable et fortement typé.

Dans cette section, vous allez enregistrer ce modèle à l'aide de la CLI gcloud pour voir comment il est défini.

Inspecter le schéma du modèle 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 dans Knowledge Catalog

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 data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

Associer des aspects de gouvernance aux tables de lacs de données

C'est l'étape d'ingénierie essentielle. Pour le moment, les tables finance_mart.fin_monthly_closing_internal et analyst_sandbox.tmp_data_dump_v2_final_real sont identiques pour un agent IA. Ce sont simplement des objets avec des colonnes.

Pour les distinguer, vous appliquez des aspects, qui associent des libellés de métadonnées certifiés à ces tables pour les différencier. Dans une vraie entreprise, vous automatiseriez cette opération avec des pipelines CI/CD. Dans ce tutoriel, vous allez simuler cette automatisation à l'aide de scripts.

Générer les charges utiles des métadonnées d'aspect

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

Cette opération crée un répertoire aspect_payloads/ contenant quatre fichiers YAML qui définissent différents scénarios de gouvernance des données (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Associer des aspects à des tables BigQuery

  1. Avant d'exécuter le script, examinez les données que vous associez aux tables. Exécutez la commande suivante pour afficher les métadonnées de vos données financières internes :

    cat aspect_payloads/fin_internal.yaml

    Le fichier YAML définit le contexte métier de la table :

    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 cela définit explicitement le contexte métier, par exemple en définissant is_certified: true et en attribuant le niveau GOLD_CRITICAL. L'agent IA dispose ainsi de règles claires et structurées à évaluer, au lieu de deviner en fonction des noms de tables.

  2. Exécutez le script de l'application. Ce script parcourt vos tables BigQuery et utilise la commande gcloud dataplex entries update pour associer vos charges utiles de métadonnées à chaque table :

    chmod +x ./apply_governance.sh
./apply_governance.sh

Vérifier les aspects appliqués dans la console Google Cloud

Avant de continuer, vérifiez que le script a correctement appliqué les aspects dans la console Google Cloud  :

  1. Ouvrez la page Knowledge Catalog dans la console Google Cloud . Vous pouvez utiliser la barre de recherche en haut de la page pour trouver l'outil.
  2. Recherchez fin_monthly_closing_internal. Sélectionnez le nom de la table BigQuery dans les résultats pour ouvrir sa page d'informations.
  3. Dans la section Tags et aspects facultatifs en bas de la page, recherchez l'aspect official-data-product-spec. Vérifiez que les valeurs correspondent au scénario "Gold Internal" que vous avez 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.

Tester votre contexte de données avec la CLI Antigravity

Avant de créer une application, vous pouvez vérifier votre logique de gouvernance des données localement avec la CLI Antigravity. Pour ce faire, vous allez installer le plug-in Knowledge Catalog et configurer la compétence de l'agent.

Installer le plug-in Knowledge Catalog

Dans Cloud Shell, installez le plug-in de service :

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

Inspecter la définition de 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 telles que "J'ai besoin de données sécurisées" en recherches techniques structurées.

Pour vérifier la configuration de la compétence et comprendre le fonctionnement du contexte de données, inspectez le fichier SKILL.md :

cat .agents/skills/knowledge-catalog-governance/SKILL.md

Notez qu'il demande au modèle de suivre des boucles strictes de phase 1 (validation 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 des instructions SQL. Cette logique de recherche prioritaire empêche l'agent de deviner les noms des tables ou d'halluciner des réponses à partir de sources non vérifiées.

Démarrer la session de la CLI Antigravity

Démarrez la session de la CLI Antigravity. Comme vous vous trouvez dans le dossier du projet, la CLI détecte et charge automatiquement la compétence à partir du répertoire .agents/skills :

agy

Vérifier l'installation du plug-in dans la CLI

Dans l'invite de la CLI Antigravity, vérifiez que le plug-in est actif. Saisissez /mcp pour lister les outils et plug-ins configurés :

/mcp

Le résultat doit afficher knowledge-catalog comme plug-in actif avec ses outils disponibles :

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

Exécuter des scénarios de vérification du contexte des données

Voyons maintenant comment fonctionne le contexte de données. Collez ces prompts un par un dans la session de la CLI Antigravity.

Scénario 1 : Récupérer des données certifiées de niveau Gold

Voyez si la CLI Antigravity peut trouver les données les plus fiables pour une réunion du conseil d'administration à enjeux élevés :

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?

La CLI doit ignorer les données brutes et trouver fin_monthly_closing_internal. Pour ce faire, il met en correspondance votre requête de données "finalisées" et "confidentielles" avec les tags GOLD_CRITICAL et INTERNAL_ONLY que vous avez appliqués précédemment.

Scénario 2 : Limiter la récupération aux données approuvées en externe

Imaginons que vous souhaitiez partager des données en externe. Vous voulez vous assurer que la CLI ne laisse échapper aucun secret interne :

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?

Même si la table interne contient le plus de détails, la CLI doit la contourner. Il doit vous diriger vers fin_quarterly_public_report, car il s'agit de la seule table taguée comme EXTERNAL_READY.

Scénario 3 : Récupérer des données de flux en temps réel

Les data scientists ont souvent besoin des informations les plus récentes. Voyez si la CLI Antigravity comprend la différence entre un lot quotidien et un flux en direct :

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?

La CLI doit trouver mkt_realtime_campaign_performance. Il identifie la fréquence de mise à jour REALTIME_STREAMING dans les métadonnées.

Scénario 4 : Explorer des données de bac à sable non certifiées

Parfois, "suffisamment bon" est préférable à "parfait". Vérifiez si la CLI Antigravity peut trouver les données brutes du bac à sable pour un travail de ML expérimental :

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.

La CLI doit trouver tmp_data_dump_v2_final_real. Il sait qu'il s'agit du bon choix, car il correspond au niveau BRONZE_ADHOC et est explicitement marqué avec is_certified: false.

Une fois les tests terminés, vous pouvez quitter la session de la CLI :

/quit

Effectuer un nettoyage

Pour éviter des frais récurrents, procédez comme suit :

  1. Si vous êtes dans la session de la CLI Antigravity, quittez-la en appuyant deux fois sur Ctrl+C ou en saisissant /quit.

  2. Exécutez le script de nettoyage pour détruire les tables, les ensembles de données et les types d'aspects Knowledge Catalog BigQuery créés dans ce tutoriel :

    chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

  3. Désinstallez le plug-in de service et supprimez vos fichiers de démonstration locaux :

    agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos

Étapes suivantes