Data-Engineering-Agenten zum Erstellen und Ändern von Datenpipelines verwenden

In diesem Dokument wird beschrieben, wie Sie den Data-Engineering-Agenten in BigQuery und Dataform verwenden, um Datenpipelines zu erstellen und zu ändern.

Mit dem Data-Engineering-Agenten können Sie Datenpipelines erstellen, ändern und verwalten, um Daten in BigQuery zu laden und zu verarbeiten. Mit dem Data-Engineering-Agenten können Sie Prompts in natürlicher Sprache verwenden, um Datenpipelines aus verschiedenen Datenquellen zu generieren oder vorhandene Datenpipelines an Ihre Data-Engineering-Anforderungen anzupassen.

Der Agent generiert und organisiert Datenpipeline-Code direkt in Dataform-Repositories. Der KI-Agent wird im Dataform-Arbeitsbereich ausgeführt, sodass Dataform-Pipelines automatisch für den KI-Agenten verfügbar sind.

Weitere Beispiele für Prompts, die Sie mit dem Data-Engineering-Agenten verwenden können, finden Sie unter Beispiel-Prompts.

Sie können auch die Data Engineering Agent API verwenden, die das A2A-Protokoll nutzt, um mit dem Agenten zu interagieren.

Beschränkungen

Für den Data Engineering-Agenten gelten die folgenden Einschränkungen:

• Der Data-Engineering-Agent unterstützt keine Befehle in natürlicher Sprache für die folgenden Dateitypen:
  • Notebooks
  • Datenvorbereitung
• Der Data Engineering-Agent kann keine Pipelines ausführen. Sie müssen Pipelines prüfen und ausführen oder planen.
• Der Data Engineering-Agent kann keine Weblinks oder URLs durchsuchen, die über Anweisungen oder direkte Prompts bereitgestellt werden.
• Beim Importieren von Dateien in einer Agent-Anweisungsdatei unterstützt die @-Importsyntax nur Pfade, die mit ./, / oder einem Buchstaben beginnen.
• Die Datenvorschau wird nur für Tabellen, Deklarationen oder Abfragen unterstützt, bei denen das Flag hasOutput auf true gesetzt ist.
• Der Data Engineering Agent unterliegt den allgemeinen Einschränkungen der KI-Technologie.
• Wenn Sie Pipelines über externe Apache Iceberg-Tabellen erstellen, die vom Lakehouse-Laufzeitkatalog (ehemals BigLake Metastore) verwaltet werden, gelten alle Einschränkungen des Lakehouse-Laufzeitkatalogs. Insbesondere kann der Agent keine Schreibmutationen (wie INSERT, UPDATE, DELETE oder MERGE) oder DDL-Anweisungen (wie CREATE TABLE oder DROP TABLE) für Iceberg-Tabellen generieren. Weitere Informationen finden Sie unter Konzepte für Apache Iceberg REST-Katalogendpunkte.

Hinweis

Führen Sie die Schritte in diesem Abschnitt aus, bevor Sie den Data Engineering-Agenten verwenden.

Gemini in BigQuery aktivieren

Achten Sie darauf, dass Gemini in BigQuery für Ihr Projekt inGoogle Cloud aktiviert ist. Weitere Informationen finden Sie unter Gemini in BigQuery einrichten.

Erforderliche APIs aktivieren

Hinweis: Wenn Sie nicht berechtigt sind, die APIs zu aktivieren, bitten Sie Ihren Projektadministrator, die APIs für Sie über das Dashboard „APIs und Dienste“ zu aktivieren. Alternativ kann Ihr Projektadministrator Ihnen die Rolle Service Usage Admin (roles/serviceusage.serviceUsageAdmin) zuweisen. Damit können Sie APIs für das aktuelle Projekt verwalten.

Console

Aktivieren Sie die folgenden APIs in der Google Cloud Console für das Projekt in Google Cloud, das Sie mit der Conversational Analytics API verwenden, falls sie noch nicht aktiviert sind.

Gemini Data Analytics API aktivieren

Gemini für Google Cloud API aktivieren

BigQuery API aktivieren

Tipp: Nachdem Sie eine API aktiviert haben, aktualisieren Sie die Seite der Google Cloud Console, um zu bestätigen, dass sie aktiviert wurde.

gcloud

Wenn Sie die Gemini Data Analytics API, die Gemini for Google CloudAPI und die BigQuery API aktivieren möchten, falls sie noch nicht aktiviert sind, verwenden Sie die Google Cloud CLI und führen Sie die folgenden gcloud services enable-Befehle aus:

gcloud services enable geminidataanalytics.googleapis.com --project=PROJECT_ID
gcloud services enable cloudaicompanion.googleapis.com --project=PROJECT_ID
gcloud services enable bigquery.googleapis.com --project=PROJECT_ID

Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung des Data Engineering-Agenten benötigen:

• Dataform-Code-Editor (roles/dataform.codeEditor)
• BigQuery Job User (roles/bigquery.jobUser)
• Gemini Data Analytics Stateless Chat User (roles/geminidataanalytics.dataAgentStatelessUser)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung geminidataanalytics.locations.useDataEngineeringAgent, die für die Verwendung des Data Engineering-Agenten erforderlich ist.

Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen zu den erforderlichen Rollen zum Abfragen von Apache Iceberg-Tabellen finden Sie unter Erforderliche Rollen für die Unterstützung von Lakehouse Apache Iceberg.

Voraussetzungen für die Knowledge Catalog-Einbindung

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Dataplex Catalog Editor (roles/dataplex.catalogEditor) für das Projekt zuzuweisen, um die Berechtigung zu erhalten, die Sie zum Einbinden des Data Engineering-Agents in Knowledge Catalog benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung geminidataanalytics.locations.useDataEngineeringAgent, die erforderlich ist, um den Data Engineering-Agent in Knowledge Catalog einzubinden.

Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Wenn Sie ein benutzerdefiniertes Dienstkonto zum Ausführen von Pipelines verwenden, müssen Sie die Rolle Dataplex Catalog Editor (roles/dataplex.catalogEditor) für das Projekt oder die Eintragsgruppe @bigquery zuweisen. Außerdem müssen Sie die Dataplex API aktivieren.

Daten mit Cloud Key Management Service-Schlüsseln verschlüsseln

Sie können Daten auf Dataset- oder Projektebene mit den standardmäßigen vom Kunden verwalteten Cloud Key Management Service-Schlüsseln in BigQuery verschlüsseln. Weitere Informationen finden Sie unter Dataset-Standardschlüssel festlegen und Projekt-Standardschlüssel festlegen.

Sie können Pipelinecode auf Projektebene verschlüsseln, indem Sie einen Cloud Key Management Service-Standardschlüssel für Dataform festlegen.

VPC Service Controls-Perimeter konfigurieren

Wenn Sie VPC Service Controls verwenden, müssen Sie den Perimeter so konfigurieren, dass Dataform, BigQuery und die Conversational Analytics API geschützt sind. Weitere Informationen finden Sie unter Dataform, BigQuery und Conversational Analytics API.

Datenpipeline mit dem Data Engineering Agent generieren

Wenn Sie den Data-Engineering-Agenten in BigQuery verwenden möchten, wählen Sie eine der folgenden Optionen aus:

BigQuery-Pipelines

So verwenden Sie den Data Engineering-Agenten in der BigQuery-Pipeline-Oberfläche:

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Klicken Sie im Abfrageeditor auf arrow_drop_down Neu erstellen > Pipeline.

3. Klicken Sie in der Pipeline-Oberfläche auf Agent fragen.

4. Geben Sie im Feld Agent fragen einen Prompt in natürlicher Sprache ein, um eine Datenpipeline zu generieren. Beispiel:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Nachdem Sie einen Prompt eingegeben haben, klicken Sie auf Senden.

5. Der Data-Engineering-Agent generiert eine Datenpipeline basierend auf Ihrem Prompt.

Der Data Engineering-Agent generiert einen Entwurf für eine Datenpipeline. Sie können auf einen Pipelineknoten klicken, um die generierte SQLX-Abfrage zu prüfen. Klicken Sie auf Anwenden, um die vom Agenten vorgeschlagene Datenpipeline anzuwenden.

Dataform

So können Sie den Data Engineering-Agenten in Dataform verwenden:

1. Rufen Sie Dataform auf.

   Zu Dataform

2. Wählen Sie ein Repository aus.

3. Wählen Sie einen Entwicklungsarbeitsbereich aus oder erstellen Sie einen.

4. Klicken Sie im Arbeitsbereich auf Agent fragen.

5. Geben Sie im angezeigten Prompt Agent fragen einen Prompt in natürlicher Sprache ein, um eine Datenpipeline zu generieren. Beispiel:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Nachdem Sie einen Prompt eingegeben haben, klicken Sie auf Senden.

Nachdem Ihr Prompt gesendet wurde, generiert der Data Engineering Agent eine Datenpipeline und ändert Dataform-SQLX-Dateien basierend auf Ihrem Prompt. Der KI-Agent wendet diese Änderungen direkt auf Ihre Arbeitsbereichsdateien an.

Datenpipeline bearbeiten

Wenn Sie Ihre Datenpipeline bearbeiten möchten, klicken Sie auf KI-Agenten fragen und geben Sie dann einen Prompt ein, der eine Änderung an der Datenpipeline vorschlägt.

Prüfen Sie die vom Data-Engineering-Agenten vorgeschlagenen Änderungen und klicken Sie dann auf Anwenden, um die Änderungen zu übernehmen.

Sie können eine SQLX-Abfrage auch manuell bearbeiten. Wählen Sie dazu einen Pipelineknoten aus und klicken Sie dann auf Öffnen.

Datenpipeline prüfen

Sie können auf einen Pipelineknoten in einer vom Data Engineering-Agenten generierten Datenpipeline klicken, um ihn zu prüfen.

• Auf dem Tab Konfiguration wird die generierte SQLX-Abfrage angezeigt, die dem Knoten zugeordnet ist.
• Auf dem Tab Datenvorschau werden die Eingabe- und Ausgabetabelle der Datei angezeigt. Sie können sich eine Vorschau der Datentransformation über diesen Knoten ansehen, indem Sie auf Aufgabe ausführen klicken, um die Aufgabe mit oder ohne Abhängigkeiten auszuführen.

Fehler in Datenpipelines beheben

Wenn beim Generieren der Datenpipeline Fehler auftreten, müssen Sie alle Voraussetzungen für die Ausführung des Data Engineering-Agenten erfüllen.

Fehler in Ihrer Pipeline werden auf dem Tab Ausführungen als fehlgeschlagene Ausführungen angezeigt. So verwenden Sie den Data Engineering-Agent, um eine Ursachenanalyse durchzuführen und Empfehlungen zur Fehlerbehebung zu erhalten:

1. Klicken Sie auf dem Tab Ausführungen auf den Status einer fehlgeschlagenen Ausführung und dann auf Prüfen.

   

   Der Bereich KI-Agent fragen wird mit einer Anfrage geöffnet, in der der KI-Agent aufgefordert wird, eine Ursachenanalyse für die fehlgeschlagene Ausführung durchzuführen.

2. Sehen Sie sich den Bericht zur Fehlerbehebung des KI-Agenten an.

Der Bericht zur Fehlerbehebung enthält weitere Informationen zu den Fehlern bei der Pipelineerstellung. Sie können den KI-Agenten auffordern, diese Pipelinefehler anhand des Berichts zu beheben.

Anweisungen für den KI-Agenten erstellen

Agentenanweisungen sind Anweisungen in natürlicher Sprache für den Data-Engineering-Agenten, mit denen Sie persistente Anweisungen speichern können, damit der Agent eine Reihe von benutzerdefinierten, vordefinierten Regeln befolgt. Verwenden Sie Agentenanweisungen, wenn die Ergebnisse des KI-Agenten in Ihrer Organisation einheitlich sein sollen, z. B. bei Namenskonventionen oder zur Durchsetzung eines Styleguides.

Sie können eine GEMINI.MD-Kontextdatei als Agent-Anweisungsdatei für den Data Engineering-Agenten erstellen. Sie können Dateien mit Agent-Anweisungen erstellen, die Sie in Ihrem lokalen Arbeitsbereich verwenden, oder dieselben Anweisungsdateien über ein externes Repository in mehreren Datenpipelines verwenden.

So erstellen Sie Agent-Anweisungen:

1. Klicken Sie unter Agent fragen auf Pipeline-Anweisungen.
2. Klicken Sie im Bereich Anleitung für Pipeline auf Anleitungsdatei erstellen.

3. Geben Sie in der angezeigten Datei GEMINI.MD Ihre Anweisungen in natürlicher Sprache ein.

   Das folgende Beispiel zeigt eine Datei mit Anweisungen für den KI-Agenten mit mehreren Regeln:

     1. All event-specific tables MUST be prefixed with `cs_event_`.
     2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
     3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.
   

4. Klicken Sie auf Speichern.

Informationen zur optimalen Strukturierung Ihrer Agent-Anweisungsdateien finden Sie unter Best Practices für Agent-Anweisungsdateien.

Anweisungen für den Agenten aus einem externen Repository laden

Wenn Sie einen Satz von Agent-Anweisungen in mehreren Datenpipelines wiederverwenden möchten, verknüpfen Sie ein externes Repository:

1. Klicken Sie unter Agent fragen auf Pipeline-Anweisungen.
2. Wählen Sie unter Externes Repository die Option Anleitungen aus externem Repository verwenden aus.
3. Geben Sie in den entsprechenden Feldern ein Repository an, das Agent-Anweisungen enthält, die Sie mit Ihrer Datenpipeline verwenden möchten.
4. Klicken Sie auf Speichern.

Beispiel-Prompts

In den folgenden Abschnitten finden Sie Beispiel-Prompts, die Sie mit dem Data Engineering-Agenten verwenden können, um Ihre Datenpipeline zu entwickeln.

Vorhandene Daten in einer neuen Tabelle zusammenfassen

Mit diesem Prompt verwendet der Data-Engineering-Agent das Schema und die Beispiele, um die Datengruppierung nach Schlüssel abzuleiten. Der Agent richtet in der Regel eine neue Tabellenkonfiguration mit Tabellen- und Spaltenbeschreibungen ein.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

Neue abgeleitete Spalte erstellen und Datenqualitätsprüfungen zur neuen Tabelle hinzufügen

In diesem Prompt wird gezeigt, wie Sie eine Tabelle und eine Spalte hinzufügen und gleichzeitig Qualitätsprüfungen für die Tabelle angeben:

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

UDFs als Teil der Modelldefinition erstellen

Der Data Engineering Agent kann auch die DDL zum Erstellen benutzerdefinierter Funktionen (UDFs) einrichten. Der Agent erstellt die UDF nicht, aber Sie können die UDF erstellen, indem Sie die Datenpipeline ausführen. Diese UDFs können in Modelldefinitionen in Ihrer Datenpipeline verwendet werden.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

Best Practices

Wenn Sie mit dem Data Engineering-Agenten und Dataform arbeiten, empfehlen wir Folgendes, um die Ergebnisse zu verbessern:

Verwenden Sie Agentenanweisungen für häufige Anfragen. Wenn Sie häufig bestimmte Techniken anwenden oder dieselben Korrekturen am Agent vornehmen, können Sie Agent-Anweisungen als zentralen Ort zum Speichern gängiger Anweisungen und Anfragen verwenden.

Agentenpläne verwenden: Agentenpläne können hilfreich sein, um komplexe Pipeline-Aufgaben aufzuschlüsseln. Agentenpläne können Ihnen auch die Annahmen und Absichten des Agenten zeigen. Wir empfehlen daher, diese Pläne zu prüfen, um sicherzustellen, dass der Agent den richtigen Kontext erhält.

Nachdem Sie einen Plan geprüft haben, können Sie ihn bearbeiten, indem Sie dem Data Engineering-Agenten Feedback und Änderungen mitteilen. Beispiel:

In the plan, ensure that all of the intermediate tables are views.

In einigen Fällen kann es hilfreich sein, den Agenten zu bitten, einen Plan zu erstellen, der nicht Ihre ausdrückliche Genehmigung erfordert. Durch die Planung muss der Data Engineering-Agent seine Aktionen aufschlüsseln, was oft zu besseren Ergebnissen führt. Sie können den Agenten zwingen, einen Plan zu erstellen und automatisch auszuführen. Beispiel:

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

Schreiben Sie deutlich. Formulieren Sie Ihre Anfrage klar und vermeiden Sie vage Formulierungen. Geben Sie nach Möglichkeit Quell- und Zieldatenquellen an, wenn Sie Prompts erstellen, wie im folgenden Beispiel gezeigt:

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

Direkte und eingegrenzte Anfragen stellen. Stellen Sie jeweils nur eine Frage und halten Sie Prompts kurz. Bei Prompts mit mehreren Fragen sollten Sie jeden einzelnen Teil der Frage auflisten, um die Klarheit zu verbessern, wie im folgenden Beispiel gezeigt:

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

Geben Sie explizite Anweisungen und betonen Sie wichtige Begriffe. Sie können wichtige Begriffe oder Konzepte in Ihren Prompts hervorheben und bestimmte Anforderungen als wichtig kennzeichnen, wie im folgenden Beispiel gezeigt:

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

Geben Sie die Reihenfolge der Vorgänge an. Bei geordneten Aufgaben sollten Sie Ihren Prompt in Listen strukturieren, wobei die aufgelisteten Elemente in kleine, fokussierte Schritte unterteilt sind, wie im folgenden Beispiel gezeigt:

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id.
  3. Load the final result into the reporting.customer_orders table.

Optimieren und iterieren: Probieren Sie verschiedene Formulierungen und Ansätze aus, um herauszufinden, was die besten Ergebnisse liefert. Wenn der Agent ungültiges SQL oder andere Fehler generiert, können Sie ihn mit Beispielen oder öffentlicher Dokumentation anleiten.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).