Antigravity CLI zum Testen des Datenkontexts verwenden

KI-Agents können Schlussfolgerungen ziehen, haben aber zu Beginn kein Wissen über Ihr Unternehmen. Stellen Sie sich vor, Sie fragen einen Kundenservicemitarbeiter: „Wie hoch war 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, die von offiziellen Berichten bis hin zu unübersichtlichen Testdaten reichen. Wenn der Agent die Tabelle mit dem ähnlichsten Namen auswählt, kann er überzeugend falsche Antworten auf Grundlage nicht überprüfter Quellen zurückgeben.

Die Lösung für dieses Kontextproblem ist die Metadatenanreicherung. In diesem Tutorial 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 auf vertrauenswürdige, zertifizierte Daten stützen kann.

Ziele

  • Stellen Sie einen realistischen, mehrstufigen Data Lake für Tests bereit.
  • Entwerfen und registrieren Sie benutzerdefinierte Metadatenvorlagen (Aspekttypen) im Knowledge Catalog, um offizielle Datenprodukte von Rohdaten-Sandbox-Tabellen zu unterscheiden.
  • Überprüfen Sie die Data Governance-Regeln mit der Antigravity CLI (agy).

Hinweis

Führen Sie zuerst folgende Schritte aus:

Für diese Anleitung sollten Sie auch ein grundlegendes Verständnis von BigQuery und Knowledge Catalog haben.

Umgebung vorbereiten

In dieser Anleitung wird die 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 Console 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 so fest, dass 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 einen Sparse Checkout, 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

Beispieldata Lake erstellen

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.

Sie verwenden ein Setupscript, um die BigQuery-Datasets und ‑Tabellen bereitzustellen.

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 gleich aus.

Data-Governance-Vorlage (Aspekttyp) erstellen

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

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

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

In diesem Schema werden strenge Datentypen erzwungen, 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 registrieren

Führen Sie den folgenden gcloud-Befehl aus, um diese Vorlage in Ihrem Knowledge Catalog-Register 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"

Data Governance anwenden

Dies ist der entscheidende technische Schritt. Derzeit sehen die Tabellen finance_mart.fin_monthly_closing_internal und analyst_sandbox.tmp_data_dump_v2_final_real für einen KI-Agenten identisch aus. Es handelt sich lediglich um Objekte mit Spalten.

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

Data-Governance-Nutzlasten generieren

Aspektschlüssel für den Knowledge Catalog müssen global eindeutig sein und mit Ihrer Projekt-ID beginnen. Das Skript ./generate_payloads.sh generiert die YAML-Metadatendateien dynamisch:

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

Dadurch wird ein aspect_payloads/-Verzeichnis erstellt, das vier YAML-Dateien enthält, in denen verschiedene Szenarien für die Datenverwaltung definiert sind (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Aspekte mit der Befehlszeile anwenden

  1. Sehen Sie sich vor dem Ausführen des Skripts 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 aufzurufen:

    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

    Hier wird der geschäftliche Kontext explizit definiert, 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 hängt mit dem Befehl gcloud dataplex entries update Ihre Metadaten-Nutzlasten an jede Tabelle an:

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

Metadaten überprüfen

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

  1. Öffnen Sie in der Google Cloud Console die Seite Knowledge Catalog. Sie können die Suchleiste oben verwenden, um danach zu suchen.
  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) durch maschinenlesbare Metadaten logisch 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-Skill.

Dienst-Plug-in installieren

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

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Agent-Fähigkeit prüfen

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

Sehen Sie sich die Datei SKILL.md an, um die Einrichtung des Skills zu prüfen und zu verstehen, wie der Datenkontext funktioniert:

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

Das Modell wird angewiesen, die Schleifen für Phase 1 (Metadatenüberprüfung) und Phase 2 (Abfrageausführung) strikt einzuhalten. Das Modell muss Metadaten ermitteln und bestätigen, bevor es SQL-Anweisungen erstellt. Diese Logik, bei der zuerst gesucht wird, verhindert, dass der Agent Tabellennamen errät oder Antworten aus nicht überprüften Quellen erfindet.

Antigravity CLI starten und Szenarien testen

Starten Sie die Antigravity CLI-Sitzung. Da Sie sich im Projektordner befinden, wird der Skill automatisch von der CLI erkannt und aus dem Verzeichnis .agents/skills geladen:

agy

Installation prüfen

Bestätigen Sie in der Antigravity CLI-Eingabeaufforderung, dass 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

Testen

Sehen wir uns nun an, wie der Datenkontext in der Praxis aussieht. Fügen Sie diese Prompts einzeln in die Antigravity-Befehlszeilensitzung ein.

Szenario 1: Goldstandard-Daten finden

Sehen Sie sich an, 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 Befehlszeile sollte die Rohdaten überspringen und fin_monthly_closing_internal finden. Dazu wird Ihre Anfrage nach „finalen“ und „vertraulichen“ Daten mit den Tags GOLD_CRITICAL und INTERNAL_ONLY abgeglichen, die Sie zuvor angewendet haben.

Szenario 2: Öffentliche Offenlegung

Stellen Sie sich vor, Sie möchten Daten extern freigeben. Sie möchten sichergehen, dass die CLI keine internen Secrets 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 sollten auf fin_quarterly_public_report verwiesen werden, da dies die einzige Tabelle ist, die mit EXTERNAL_READY gekennzeichnet ist.

Szenario 3: Echtzeit-Betriebsanforderungen

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. Gibt die REALTIME_STREAMING-Updatehäufigkeit in den Metadaten an.

Szenario 4: Sandbox-Erkundung

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. Das ist die richtige Wahl, weil 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

So vermeiden Sie wiederkehrende Gebühren:

  1. Wenn Sie sich in der Antigravity CLI-Sitzung befinden, beenden Sie die Sitzung, indem Sie zweimal Ctrl+C 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

Fazit

Sie haben eine solide Datengrundlage geschaffen, mithilfe von Metadaten einen strengen Kontext angewendet und mit der Antigravity CLI überprüft, ob alles lokal funktioniert.

Nächste Schritte