Antigravity CLI zum Testen des Datenkontexts verwenden

KI-Agents können Schlussfolgerungen ziehen, aber sie haben keine Kenntnisse über Ihr Unternehmen. Stellen Sie sich vor, Sie fragen einen Agenten: „Wie hoch ist unser Umsatz im ersten Quartal?“ Ohne Anleitung wählt der Agent möglicherweise aus Dutzenden von Tabellen mit dem Namen „Umsatz“ in Ihren Datenbanken aus, von offiziellen Berichten bis hin zu unübersichtlichen Testdaten. Wenn der Agent die Tabelle mit dem ähnlichsten Namen auswählt, kann er überzeugend falsche Antworten auf der Grundlage nicht überprüfter Quellen zurückgeben.

Die Metadatenanreicherung ist die Lösung für dieses Kontextproblem. In dieser Anleitung richten Sie Aspekte ein, die diesen Kontext liefern, und verwenden die Antigravity CLI, um den Datenkontext zu testen und zu prüfen, ob ein Agent seine Antworten genau auf vertrauenswürdige, zertifizierte Daten stützen kann.

Ziele

  • Bereitstellung eines realistischen, mehrstufigen Data Lake in BigQuery zum Testen.
  • Benutzerdefinierte Metadatenvorlagen (Aspekttypen) in Knowledge Catalog entwerfen und registrieren, um offizielle Datenprodukte von Sandbox-Tabellen zu unterscheiden.
  • Data-Governance-Regeln und KI-Agent-Grundlagen mit der Antigravity CLI (agy) überprüfen.

Hinweis

Bevor Sie beginnen, müssen Sie Folgendes tun:

Für diese Anleitung sollten Sie außerdem grundlegende Kenntnisse in BigQuery und Knowledge Catalog haben.

Umgebung vorbereiten

In dieser Anleitung wird Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird. Die Antigravity CLI (agy) ist in Google Cloud Shell vorinstalliert.

  1. Klicken Sie in der Google Cloud Konsole in der Symbolleiste rechts oben auf Cloud Shell aktivieren. Die Bereitstellung und Verbindung mit der Umgebung dauert einen kleinen Moment.

  2. Legen Sie in Cloud Shell die Variablen PROJECT_ID und REGION fest, damit alle zukünftigen Befehle auf Ihr spezifisches Google Cloud Projekt ausgerichtet sind.

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

  3. Aktivieren Sie die erforderlichen Google Cloud Dienste.

    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. Klonen Sie das Google Cloud DevRel Demos-Repository.

    Laden Sie den Infrastrukturcode und die Skripts von GitHub herunter. Verwenden Sie eine Sparse-Auscheckung, um nur den Ordner abzurufen, den Sie für diese Anleitung benötigen.

    # 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

Beispiel-Data Lake in BigQuery bereitstellen

Datenumgebungen in der Praxis sind selten sauber. Um die Realität zu simulieren, benötigen Sie eine Mischung aus „offiziellen“ Data Marts und nicht vertrauenswürdigen „Sandbox“-Tabellen.

Mit einem Setupscript stellen Sie die BigQuery-Datasets und -Tabellen bereit.

Machen Sie das Setupscript ausführbar und führen Sie es aus. Dadurch werden drei BigQuery-Datasets (finance_mart, marketing_prod, analyst_sandbox) erstellt und ihre Tabellen mit Beispieldaten gefüllt:

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

Sie haben jetzt einen vollständig gefüllten, aber nicht verwalteten Data Lake. Für einen KI-Agenten sieht jede Tabelle genau gleich aus.

Benutzerdefinierten Aspekttyp in Knowledge Catalog definieren

Jetzt definieren Sie die Regeln für Ihre Data Governance. Dazu erstellen Sie in Knowledge Catalog einen Aspekttyp, eine wiederverwendbare, stark typisierte Metadatenvorlage.

In diesem Abschnitt registrieren Sie diese Vorlage mit der gcloud CLI, damit Sie sehen können, wie sie definiert ist.

Aspektvorlagenschema prüfen

Geben Sie den Inhalt von aspect_template.json aus, um die Schemadefinition zu sehen:

cat aspect_template.json

Es wird die folgende JSON-Struktur angezeigt:

{
  "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",
      "...": "..."
    }
  ]
}

Beachten Sie, dass dieses Schema strenge Datentypen erzwingt, z. B. enum für die Kritikalitätsstufe (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) und bool für is_certified. So bleiben die Metadaten strukturiert und maschinenlesbar.

Aspekttyp in Knowledge Catalog registrieren

Führen Sie den folgenden gcloud-Befehl aus, um diese Vorlage in Ihrer Knowledge Catalog-Registrierung zu registrieren:

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"

Governance-Aspekte an Data Lake-Tabellen anhängen

Dies ist der entscheidende technische Schritt. Derzeit sehen die Tabelle finance_mart.fin_monthly_closing_internal und analyst_sandbox.tmp_data_dump_v2_final_real für einen KI-Agenten identisch aus. Es sind nur Objekte mit Spalten.

Um sie zu unterscheiden, wenden Sie Aspekte an, die zertifizierte Metadatenlabels an diese Tabellen anhängen. In einem echten Unternehmen würden Sie dies mit CI/CD-Pipelines automatisieren. In dieser Anleitung simulieren Sie diese Automatisierung mit Skripts.

Nutzlasten für Aspektmetadaten generieren

Aspektschlüssel von Knowledge Catalog müssen global eindeutig sein (mit Ihrer Projekt-ID als Präfix). Das Skript ./generate_payloads.sh generiert dynamisch die YAML-Metadatendateien:

chmod +x ./generate_payloads.sh
./generate_payloads.sh

Dadurch wird ein Verzeichnis aspect_payloads/ erstellt, das vier YAML-Dateien enthält, die verschiedene Data-Governance-Szenarien definieren (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Aspekte an BigQuery-Tabellen anhängen

  1. Bevor Sie das Skript ausführen, sehen Sie sich die Daten an, die Sie an die Tabellen anhängen. Führen Sie den folgenden Befehl aus, um die Metadaten für Ihre internen Finanzdaten zu sehen:

    cat aspect_payloads/fin_internal.yaml

    Die YAML-Datei definiert den geschäftlichen Kontext für die Tabelle:

    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

    Beachten Sie, dass hier der geschäftliche Kontext explizit definiert wird, z. B. durch Festlegen von is_certified: true und Zuweisen der Stufe GOLD_CRITICAL. So erhält der KI-Agent klare, strukturierte Regeln für die Auswertung, anstatt anhand von Tabellennamen zu raten.

  2. Führen Sie das Anwendungsskript aus. Dieses Skript durchläuft Ihre BigQuery-Tabellen und verwendet den Befehl gcloud dataplex entries update, um die Metadatennutzlasten an jede Tabelle anzuhängen:

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

Angewendete Aspekte in der Google Cloud Konsole prüfen

Bevor Sie fortfahren, prüfen Sie, ob das Skript die Aspekte in der Google Cloud Konsole korrekt angewendet hat:

  1. Öffnen Sie in der Google Cloud Konsole die Seite Knowledge Catalog. Sie können die Suchleiste oben verwenden, um sie zu finden.
  2. Suchen Sie nach fin_monthly_closing_internal. Wählen Sie in den Ergebnissen den Namen der BigQuery-Tabelle aus, um die Detailseite zu öffnen.
  3. Suchen Sie unten im Bereich Optionale Tags und Aspekte nach dem Aspekt official-data-product-spec. Prüfen Sie, ob die Werte mit dem angewendeten Szenario „Gold Internal“ übereinstimmen.

Sie haben jetzt bestätigt, dass technisch identische BigQuery-Tabellen (fin_monthly_closing_internal und tmp_data_dump_v2_final_real) logisch durch maschinenlesbare Metadaten unterschieden werden.

Datenkontext mit der Antigravity CLI testen

Bevor Sie eine Anwendung erstellen, können Sie Ihre Data-Governance-Logik lokal mit der Antigravity CLI überprüfen. Dazu installieren Sie das Knowledge Catalog-Plug-in und konfigurieren die Agent-Fähigkeit.

Knowledge Catalog-Plug-in installieren

Installieren Sie in Cloud Shell das Dienst-Plug-in:

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Definition der Agent-Fähigkeit prüfen

Die Agent-Fähigkeit ist eine statische, wiederverwendbare Definitionsdatei in .agents/skills/knowledge-catalog-governance/SKILL.md. Sie enthält die Logik, die abstrakte menschliche Regeln wie „Ich brauche sichere Daten“ in strukturierte technische Suchvorgänge übersetzt.

Prüfen Sie die Einrichtung der Fähigkeit und verstehen Sie, wie der Datenkontext funktioniert, indem Sie die Datei SKILL.md untersuchen:

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

Beachten Sie, dass das Modell angewiesen wird, strikte Schleifen für Phase 1 (Metadatenprüfung) und Phase 2 (Abfrageausführung) zu befolgen. Das Modell muss Metadaten ermitteln und prüfen, bevor SQL-Anweisungen erstellt werden. Diese „Suche zuerst“-Logik verhindert, dass der Agent Tabellennamen errät oder Antworten aus nicht überprüften Quellen halluziniert.

Antigravity CLI-Sitzung starten

Starten Sie die Antigravity CLI-Sitzung. Da Sie sich im Projektordner befinden, erkennt und lädt die CLI die Fähigkeit automatisch aus dem Verzeichnis .agents/skills:

agy

Plug-in-Installation in der CLI prüfen

Prüfen Sie in der Antigravity CLI-Eingabeaufforderung, ob das Plug-in aktiv ist. Geben Sie /mcp ein, um die konfigurierten Tools und Plug-ins aufzulisten:

/mcp

In der Ausgabe sollte knowledge-catalog als aktives Plug-in mit den verfügbaren Tools aufgeführt sein:

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

Szenarien zur Überprüfung des Datenkontexts ausführen

Jetzt ist es an der Zeit, Ihren Datenkontext in Aktion zu sehen. Fügen Sie diese Prompts einzeln in die Antigravity CLI-Sitzung ein.

Szenario 1: Zertifizierte Daten der Stufe „Gold“ abrufen

Prüfen Sie, ob die Antigravity CLI die vertrauenswürdigsten Daten für eine wichtige Vorstandssitzung finden kann:

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?

Die CLI sollte die Rohdaten überspringen und fin_monthly_closing_internal finden. Dazu werden Ihre Anfrage nach „finalisierten“ und „vertraulichen“ Daten mit den Tags GOLD_CRITICAL und INTERNAL_ONLY abgeglichen, die Sie zuvor angewendet haben.

Szenario 2: Abruf auf extern genehmigte Daten beschränken

Angenommen, Sie möchten Daten extern freigeben. Sie möchten sicherstellen, dass die CLI keine internen Geheimnisse preisgibt:

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?

Obwohl die interne Tabelle die meisten Details enthält, muss die CLI sie umgehen. Sie sollte Sie auf fin_quarterly_public_report verweisen, da dies die einzige Tabelle ist, die mit EXTERNAL_READY getaggt ist.

Szenario 3: Streamingdaten in Echtzeit abrufen

Data Scientists benötigen oft die neuesten Informationen. Prüfen Sie, ob die Antigravity CLI den Unterschied zwischen einem täglichen Batch und einem Livestream versteht:

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?

Die CLI sollte mkt_realtime_campaign_performance finden. Sie erkennt die Aktualisierungshäufigkeit REALTIME_STREAMING in den Metadaten.

Szenario 4: Nicht zertifizierte Sandbox-Daten untersuchen

Manchmal ist „gut genug“ besser als „perfekt“. Prüfen Sie, ob die Antigravity CLI die Rohdaten der Sandbox für einige experimentelle ML-Aufgaben finden kann:

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.

Die CLI sollte tmp_data_dump_v2_final_real finden. Sie weiß, dass dies die richtige Wahl ist, da sie der Stufe BRONZE_ADHOC entspricht und explizit mit is_certified: false gekennzeichnet ist.

Wenn Sie mit dem Testen fertig sind, können Sie die CLI-Sitzung beenden:

/quit

Bereinigen

Führen Sie die folgenden Schritte aus, um wiederkehrende Kosten zu vermeiden:

  1. Wenn Sie sich in der Antigravity CLI-Sitzung befinden, beenden Sie sie, indem Sie Ctrl+C zweimal drücken oder /quit eingeben.

  2. Führen Sie das Bereinigungsskript aus, um die in dieser Anleitung erstellten BigQuery-Tabellen, -Datasets und Knowledge Catalog-Aspekttypen zu löschen:

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

  3. Deinstallieren Sie das Dienst-Plug-in und entfernen Sie Ihre lokalen Demodateien:

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

Nächste Schritte