Antigravity CLI zum Testen des Datenkontexts verwenden

Mit der Metadatenanreicherung in Knowledge Catalog (ehemals Dataplex Universal Catalog) können Sie strukturierten Datenkontext bereitstellen, damit KI-Agenten ihre Antworten auf vertrauenswürdigen, zertifizierten Quellen fundieren können. In diesem Tutorial hängen Sie benutzerdefinierte Aspekte an BigQuery-Beispieltabellen an und verwenden die Antigravity-Befehlszeile, um zu testen, wie ein KI-Agent Ihre Governance-Regeln anwendet.

Ziele

  • Stellen Sie einen realistischen, mehrstufigen Data Lake in BigQuery zu Testzwecken bereit.
  • Entwerfen und registrieren Sie benutzerdefinierte Metadatenvorlagen (Aspekttypen) in Knowledge Catalog, um offizielle Datenprodukte von Roh-Sandbox-Tabellen zu unterscheiden.
  • Prüfen Sie die Data-Governance-Regeln und die Fundierung von KI-Agenten mit der Antigravity CLI (agy).

Hinweis

Bevor Sie beginnen, müssen Sie Folgendes tun:

Für diese Anleitung sollten Sie außerdem grundlegende Kenntnisse zu 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 fest, damit alle zukünftigen Befehle auf Ihr spezifisches Google Cloud Projekt abzielen.

    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 spezifischen 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

Reale Datenumgebungen sind selten sauber. KI-Agenten können logisch denken, aber sie haben anfangs kein Wissen über Ihr spezifisches Unternehmen. Stellen Sie sich vor, Sie fragen einen KI-Agenten: „Wie hoch ist unser Umsatz im ersten Quartal?“ Ohne Anleitung könnte der Agent aus Dutzenden von Tabellen mit dem Namen „Umsatz“ in Ihren Datenbanken auswählen, von offiziellen Berichten bis hin zu Rohdaten. Wenn der Agent die Tabelle mit dem am ähnlichsten klingenden Namen auswählt, kann er überzeugend klingende, aber falsche Antworten auf der Grundlage nicht verifizierter Quellen zurückgeben.

Um dieses Szenario 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 die zugehörigen 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-Befehlszeile, um zu sehen, wie sie definiert ist.

Schema der Aspektvorlage 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 in Knowledge Catalog registrieren

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

Das ist der entscheidende Engineering-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. Sie sind nur Objekte mit Spalten.

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

Aspektmetadaten-Nutzlasten generieren

Aspektschlüssel für Knowledge Catalog müssen global eindeutig sein (mit Ihrer Projekt-ID als Präfix). Das Script ./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, 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 aufzurufen:

    cat aspect_payloads/fin_internal.yaml

    In der YAML-Datei wird der Geschäftskontext für die Tabelle definiert:

    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, wie 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, die er auswerten kann, anstatt anhand von Tabellennamen zu raten.

  2. Führen Sie das Anwendungsskript aus. Dieses Script iteriert durch Ihre BigQuery-Tabellen und verwendet den Befehl gcloud dataplex entries update, um die Metadaten-Nutzlasten an jede Tabelle anzuhängen:

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

Angewendete Aspekte in der Google Cloud Console prüfen

Bevor Sie fortfahren, prüfen Sie in der Google Cloud Console, ob das Script die Aspekte 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 von Ihnen angewendeten Szenario „Gold Internal“ übereinstimmen.

Sie haben nun 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 prüfen. Dazu installieren Sie das Knowledge Catalog-Plug-in und konfigurieren die Agentenkompetenz.

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

Der Agentenskill ist eine statische, wiederverwendbare Definitionsdatei, die sich in .agents/skills/knowledge-catalog-governance/SKILL.md befindet. Er enthält die Logik, die abstrakte menschliche Regeln wie „Ich brauche sichere Daten“ in strukturierte technische Suchvorgänge übersetzt.

Prüfen Sie die Datei SKILL.md, um die Skill-Einrichtung zu überprüfen und zu verstehen, wie der Datenkontext funktioniert:

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 erkennen und verifizieren, bevor SQL-Anweisungen erstellt werden. Diese Logik, bei der die Suche an erster Stelle steht, verhindert, dass der KI-Agent Tabellennamen errät oder Antworten aus nicht verifizierten Quellen halluziniert.

Antigravity CLI-Sitzung starten

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

agy

Plug-in-Installation in der Befehlszeile prüfen

Prüfen Sie in der Antigravity CLI, ob das Plug-in aktiv ist. Geben Sie /mcp ein, um konfigurierte 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 nacheinander in die Antigravity-CLI-Sitzung ein.

Szenario 1: Zertifizierte Daten der Gold-Stufe abrufen

Findet die Antigravity CLI die vertrauenswürdigsten Daten für eine wichtige Vorstandssitzung?

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 „finalized“ und „confidential“ Daten mit den Tags GOLD_CRITICAL und INTERNAL_ONLY abgeglichen, die Sie zuvor angewendet haben.

Szenario 2: Abruf auf extern genehmigte Daten beschränken

Stellen Sie sich vor, Sie möchten Daten extern freigeben. Sie möchten sicherstellen, dass die Befehlszeile 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 Befehlszeile sie umgehen. Sie sollten auf fin_quarterly_public_report verwiesen werden, da dies die einzige Tabelle mit dem Tag EXTERNAL_READY ist.

Szenario 3: Echtzeit-Streamingdaten abrufen

Data Scientists benötigen oft die absolut neuesten Informationen. Finden Sie heraus, 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 Befehlszeile sollte mkt_realtime_campaign_performance finden. Sie gibt die Aktualisierungshäufigkeit von REALTIME_STREAMING in den Metadaten an.

Szenario 4: Nicht zertifizierte Sandbox-Daten analysieren

Manchmal ist „gut genug“ besser als „perfekt“. Prüfen Sie, ob die Antigravity CLI die Sandbox-Rohdaten für experimentelle ML-Arbeiten 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 Befehlszeile sollte tmp_data_dump_v2_final_real finden. Es weiß, dass dies die richtige Wahl ist, weil es der BRONZE_ADHOC-Stufe 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

Nächste Schritte