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

Les agents IA peuvent raisonner, mais ils ne disposent d'aucune connaissance sur votre entreprise. Imaginez que vous demandiez à un agent : "Quel est notre chiffre d'affaires au premier trimestre ?" Sans indication, l'agent peut choisir parmi des dizaines de tables nommées "chiffre d'affaires" dans vos bases de données, allant des rapports officiels aux données de test désordonnées. Si l'agent choisit la table dont le nom est le plus proche, il peut renvoyer des réponses fausses convaincantes basées sur des sources non vérifiées.

L'enrichissement des métadonnées est la solution à ce problème de contexte. Dans ce tutoriel, vous configurez des aspects qui fournissent ce contexte et utilisez la CLI Antigravity pour tester le contexte des données et vérifier qu'un agent peut baser ses réponses avec précision sur des données fiables et certifiées.

Objectifs

  • Déployer un lac de données réaliste à plusieurs niveaux pour les tests
  • Concevoir et enregistrer 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érifier les règles de gouvernance des données à l'aide de la CLI Antigravity (agy)

Avant de commencer

Avant de commencer, assurez-vous d'effectuer les opérations suivantes :

Pour suivre ce tutoriel, vous devez également avoir une compréhension de base de BigQuery et de 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 Google Cloud console, cliquez sur Activer Cloud Shell en haut à droite de la barre d'outils. 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 commandes futures ciblent votre projet spécifique Google Cloud .

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

  3. Activez les services nécessaires Google Cloud .

    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 Google Cloud dépôt DevRel Demos.

    Téléchargez le code d'infrastructure et les scripts depuis GitHub. Utilisez un checkout sparse 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

Créer un exemple de lac de données

Les environnements de données réels sont rarement propres. Pour simuler la réalité, vous avez besoin d'un mélange de data marts "officiels" et de tables "bac à sable" non fiables.

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. Cela 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 géré. Pour un agent IA, toutes les tables se ressemblent.

Créer le modèle de gouvernance des données (type d'aspect)

Vous définissez maintenant 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 fortement typé et réutilisable.

Dans cette section, vous enregistrez ce modèle à l'aide de la CLI gcloud afin de 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 comment 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 un bool pour is_certified. Cela garantit 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 data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

Appliquer la gouvernance des données

Il s'agit de l'étape d'ingénierie critique. 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. Il s'agit simplement d'objets avec des colonnes.

Pour les distinguer, vous appliquez des aspects, qui associent des libellés de métadonnées certifiés à ces tables afin de les différencier. Dans une entreprise réelle, vous automatisez ce processus avec des pipelines CI/CD. Dans ce tutoriel, vous simulez cette automatisation avec des scripts.

Générer des charges utiles de gouvernance des données

Les clés d'aspect Knowledge Catalog doivent être globalement uniques (avec le préfixe de votre ID de 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

Cela 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).

Appliquer des aspects à l'aide de la CLI

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

  2. Exécutez le script d'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 métadonnées

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

  1. Ouvrez la page Knowledge Catalog dans la Google Cloud console. 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 la 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 les tables BigQuery techniquement identiques (fin_monthly_closing_internal et tmp_data_dump_v2_final_real) sont logiquement différenciées par des métadonnées lisibles par machine.

Tester le contexte de vos données avec la CLI Antigravity

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

Installer le plug-in de service

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 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 des 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 des 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 (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 construire des instructions SQL. Cette logique de recherche d'abord empêche l'agent de deviner les noms de tables ou de générer des réponses à partir de sources non vérifiées.

Démarrer la CLI Antigravity et tester des scénarios

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

Dans l'invite de la CLI Antigravity, vérifiez que le plug-in est actif. Saisissez /mcp pour afficher la liste des 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

Essayer

Il est maintenant temps de voir le contexte de vos données en action. Collez ces invites dans la session de la CLI Antigravity une par une.

Scénario 1 : Rechercher des données de référence "Gold"

Vérifiez 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, elle fait correspondre votre demande de données "finalisées" et "confidentielles" aux tags GOLD_CRITICAL et INTERNAL_ONLY que vous avez appliqués précédemment.

Scénario 2 : Divulgation publique

Imaginez que vous souhaitez partager des données en externe. Vous voulez vous assurer que la CLI ne divulgue 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. Elle doit vous rediriger vers fin_quarterly_public_report, car il s'agit de la seule table taguée comme EXTERNAL_READY.

Scénario 3 : Besoins opérationnels en temps réel

Les data scientists ont souvent besoin des dernières informations. Vérifiez 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. Elle identifie la fréquence de mise à jour REALTIME_STREAMING dans les métadonnées.

Scénario 4 : Exploration du bac à sable

Parfois, "suffisamment bien" vaut mieux que "parfait". Vérifiez si la CLI Antigravity peut trouver les données brutes du bac à sable pour certains travaux de ML expérimentaux :

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. Elle 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

Libérer de l'espace

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

  1. Si vous êtes dans la session de la CLI Antigravity, quittez la session 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 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

Conclusion

Vous avez créé une base de données solide, appliqué un contexte strict à l'aide de métadonnées et vérifié que tout fonctionne localement à l'aide de la CLI Antigravity.

Étape suivante