Utilizza Data Engineering Agent per creare e modificare pipeline di dati

Questo documento mostra come utilizzare l'agente Data Engineering in BigQuery e Dataform per creare e modificare pipeline di dati.

L'agente di data engineering ti consente di creare, modificare e gestire pipeline di dati per caricare ed elaborare i dati in BigQuery. Con Data Engineering Agent, puoi utilizzare prompt in linguaggio naturale per generare pipeline di dati da varie origini dati o adattare le pipeline di dati esistenti in base alle tue esigenze di data engineering.

L'agente genera e organizza il codice della pipeline di dati direttamente all'interno dei repository Dataform. L'agente opera nello spazio di lavoro di Dataform, quindi le pipeline di Dataform sono automaticamente disponibili per l'agente.

Per altri esempi di prompt che puoi utilizzare con il Data Engineering Agent, consulta Prompt di esempio.

Puoi anche utilizzare l'API Data Engineering Agent, che utilizza il protocollo A2A, per interagire con l'agente.

Limitazioni

Data Engineering Agent presenta le seguenti limitazioni:

• Data Engineering Agent non supporta i comandi in linguaggio naturale per i seguenti tipi di file:
  • Notebook
  • Preparazione dei dati
• Il Data Engineering Agent non può eseguire pipeline. Devi esaminare ed eseguire o pianificare le pipeline.
• Il Data Engineering Agent non può eseguire ricerche in link web o URL forniti tramite istruzioni o prompt diretti.
• Quando importi file in un file di istruzioni dell'agente, la sintassi di importazione @ supporta solo i percorsi che iniziano con ./, / o una lettera.
• La funzionalità di anteprima dei dati è supportata solo per tabelle, dichiarazioni o query con il flag hasOutput impostato su true.
• Data Engineering Agent è soggetto alle limitazioni generali della tecnologia AI.
• Quando crei pipeline su tabelle esterne Apache Iceberg gestite dal catalogo di runtime Lakehouse (in precedenza metastore BigLake), si applicano tutte le limitazioni del catalogo di runtime Lakehouse. In particolare, l'agente non può generare mutazioni di scrittura (come INSERT, UPDATE, DELETE o MERGE) o istruzioni DDL (come CREATE TABLE o DROP TABLE) sulle tabelle Iceberg. Per saperne di più, consulta Concetti relativi agli endpoint del catalogo REST Apache Iceberg.

Prima di iniziare

Prima di utilizzare Data Engineering Agent, esegui i passaggi descritti in questa sezione.

Abilita Gemini in BigQuery

Assicurati che Gemini in BigQuery sia abilitato per il tuo progettoGoogle Cloud . Per saperne di più, consulta Configura Gemini in BigQuery.

Abilita le API richieste

Nota: se non hai l'autorizzazione per abilitare le API, chiedi all'amministratore del progetto di abilitarle per te dalla dashboard API e servizi. In alternativa, l'amministratore del progetto può concederti il ruolo Service Usage Admin (roles/serviceusage.serviceUsageAdmin), che ti consente di gestire le API per il progetto corrente.

console

Abilita le seguenti API nella console Google Cloud per il progetto Google Cloudche utilizzi con l'API Conversational Analytics, se non sono già abilitate.

Abilita l'API Gemini Data Analytics

Abilita l'API Gemini for Google Cloud

Abilita l'API BigQuery

Suggerimento: dopo aver abilitato un'API, aggiorna la pagina della console Google Cloud per confermare che sia abilitata.

gcloud

Per abilitare l'API Gemini Data Analytics, l'API Gemini for Google Cloud e l'API BigQuery, se non sono già abilitate, utilizza Google Cloud CLI ed esegui i seguenti comandi gcloud services enable:

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

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Ruoli obbligatori

Per ottenere l'autorizzazione necessaria per utilizzare l'agente di data engineering, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione geminidataanalytics.locations.useDataEngineeringAgent, necessaria per utilizzare l'agente di data engineering.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per informazioni dettagliate sui ruoli richiesti per eseguire query sulle tabelle Apache Iceberg, consulta Ruoli richiesti per il supporto di Lakehouse Apache Iceberg.

Prerequisiti per l'integrazione di Knowledge Catalog

Per ottenere l'autorizzazione necessaria per integrare l'agente di data engineering con Knowledge Catalog, chiedi all'amministratore di concederti il ruolo IAM Dataplex Catalog Editor (roles/dataplex.catalogEditor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione geminidataanalytics.locations.useDataEngineeringAgent, necessaria per integrare l'agente di data engineering con Knowledge Catalog.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Se utilizzi un account di servizio personalizzato per eseguire le pipeline, devi concedere il ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) al progetto o al gruppo di voci @bigquery. Inoltre, devi abilitare l'API Dataplex.

Cripta i dati con le chiavi di Cloud Key Management Service

Puoi criptare i dati a livello di set di dati o di progetto con le chiavi Cloud Key Management Service predefinite gestite dal cliente in BigQuery. Per saperne di più, consulta Imposta una chiave predefinita per il set di dati e Imposta una chiave predefinita per il progetto.

Puoi criptare il codice della pipeline a livello di progetto impostando una chiave predefinita di Cloud Key Management Service per Dataform.

Configura i perimetri dei Controlli di servizio VPC

Se utilizzi i Controlli di servizio VPC, devi configurare il perimetro per proteggere Dataform, BigQuery e l'API Conversational Analytics. Per saperne di più, consulta Dataform, BigQuery e l'API Conversational Analytics.

Genera una pipeline di dati con Data Engineering Agent

Per utilizzare l'agente di data engineering in BigQuery, seleziona una delle seguenti opzioni:

Pipeline BigQuery

Puoi utilizzare l'agente di data engineering nell'interfaccia delle pipeline di BigQuery seguendo questi passaggi:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, fai clic su arrow_drop_down Crea nuova > Pipeline.

3. Nell'interfaccia della pipeline, fai clic su Chiedi all'agente.

4. Nel campo Chiedi all'agente, inserisci un prompt in linguaggio naturale per generare una pipeline di dati, ad esempio:

     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.
   

   Dopo aver inserito un prompt, fai clic su Invia.

5. Il Data Engineering Agent genera una pipeline di dati in base al tuo prompt.

Il Data Engineering Agent genera una bozza proposta di una pipeline di dati. Puoi fare clic su un nodo della pipeline per esaminare la query SQLX generata. Per applicare la pipeline di dati suggerita dall'agente, fai clic su Applica.

Dataform

Puoi utilizzare il Data Engineering Agent in Dataform procedendo nel seguente modo:

1. Vai a Dataform.

   Vai a Dataform

2. Seleziona un repository.

3. Seleziona o crea un'area di lavoro di sviluppo.

4. Nell'area di lavoro, fai clic su Chiedi all'agente.

5. Nel prompt Chiedi all'agente visualizzato, inserisci un prompt in linguaggio naturale per generare una pipeline di dati, ad esempio:

     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.
   

   Dopo aver inserito un prompt, fai clic su Invia.

Dopo l'invio del prompt, Data Engineering Agent genera una pipeline di dati e modifica i file SQLX di Dataform in base al prompt. L'agente applica queste modifiche direttamente ai file del tuo workspace.

Modifica una pipeline di dati

Per modificare la pipeline di dati, fai clic su Chiedi all'agente, quindi inserisci un prompt che suggerisca una modifica alla pipeline di dati.

Esamina le modifiche proposte dal Data Engineering Agent, quindi fai clic su Applica per applicarle.

Puoi anche modificare manualmente una query SQLX selezionando un nodo della pipeline e poi facendo clic su Apri.

Esamina una pipeline di dati

Puoi fare clic su un nodo della pipeline in una pipeline di dati generata dall'agente di data engineering per esaminarlo.

• La scheda Configurazione mostra la query SQLX generata associata al nodo.
• La scheda Anteprima dati mostra la tabella di input e output del file. Puoi visualizzare l'anteprima della trasformazione dei dati tramite questo nodo facendo clic su Esegui attività per eseguire l'attività con o senza dipendenze.

Risolvi gli errori della pipeline di dati

Se si verificano errori durante la generazione della pipeline di dati, completa tutti i prerequisiti per eseguire l'agente di data engineering.

Gli errori nella pipeline vengono visualizzati come esecuzioni non riuscite nella scheda Esecuzioni. Per utilizzare il Data Engineering Agent per eseguire un'analisi delle cause principali e ottenere suggerimenti per la risoluzione dei problemi, segui questi passaggi:

1. Nella scheda Esecuzioni, fai clic sullo stato di un'esecuzione non riuscita, quindi su Esamina.

   

   Si apre il riquadro Chiedi all'agente con una richiesta che invita l'agente a eseguire un'analisi delle cause principali dell'esecuzione non riuscita.

2. Esamina il report sulla risoluzione dei problemi dell'agente.

Il report sulla risoluzione dei problemi include ulteriori informazioni sugli errori nel processo di generazione della pipeline. Puoi chiedere all'agente di correggere questi errori della pipeline in base al report.

Crea istruzioni per l'agente

Le istruzioni per l'agente sono istruzioni in linguaggio naturale per il Data Engineering Agent che ti consentono di archiviare istruzioni persistenti in modo che l'agente segua un insieme di regole personalizzate e predefinite. Utilizza le istruzioni dell'agente se vuoi che i risultati dell'agente siano coerenti in tutta l'organizzazione, ad esempio con le convenzioni di denominazione o per applicare una guida di stile.

Puoi creare un file di contesto GEMINI.MD come file di istruzioni per l'agente di data engineering. Puoi creare file di istruzioni dell'agente da utilizzare nel tuo workspace locale o utilizzare gli stessi file di istruzioni in più pipeline di dati con un repository esterno.

Per creare le istruzioni dell'agente:

1. In Chiedi all'agente, fai clic su Istruzioni della pipeline.
2. Nel riquadro Istruzioni per la pipeline, fai clic su Crea file di istruzioni.

3. Nel file GEMINI.MD visualizzato, inserisci le istruzioni in linguaggio naturale.

   L'esempio seguente mostra un file di istruzioni dell'agente con diverse regole:

     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. Fai clic su Salva.

Per informazioni su come strutturare al meglio i file di istruzioni dell'agente, consulta Best practice per i file di istruzioni dell'agente.

Carica le istruzioni dell'agente da un repository esterno

Per riutilizzare un insieme di istruzioni dell'agente in più pipeline di dati, collega un repository esterno:

1. In Chiedi all'agente, fai clic su Istruzioni della pipeline.
2. In Repository esterno, seleziona Usa le istruzioni del repository esterno.
3. Nei campi forniti, specifica un repository che contiene le istruzioni dell'agente che vuoi utilizzare con la pipeline di dati.
4. Fai clic su Salva.

Prompt di esempio

Le sezioni seguenti forniscono esempi di prompt che puoi utilizzare con l'agente di data engineering per sviluppare la tua pipeline di dati.

Aggrega i dati esistenti in una nuova tabella

Con questo prompt, l'agente di data engineering utilizza lo schema e gli esempi per dedurre il raggruppamento dei dati per chiave. In genere, l'agente configura una nuova tabella con descrizioni di tabelle e colonne.

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

Crea una nuova colonna derivata e aggiungi controlli della qualità dei dati alla nuova tabella

Questo prompt mostra come aggiungere una tabella e una colonna e specificare contemporaneamente i controlli di qualità per la tabella:

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

Crea funzioni definite dall'utente nell'ambito della definizione del modello

L'agente di data engineering può anche configurare il DDL per creare funzioni definite dall'utente (UDF). Anche se l'agente non creerà effettivamente la funzione definita dall'utente, puoi crearla eseguendo la pipeline di dati. Queste funzioni definite dall'utente possono essere utilizzate nelle definizioni dei modelli nella pipeline di dati.

  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 practice

Per migliorare i risultati quando utilizzi l'agente di data engineering e Dataform, ti consigliamo di seguire questi passaggi:

Utilizza le istruzioni dell'agente per le richieste comuni. Se applichi comunemente determinate tecniche o se apporti spesso le stesse correzioni all'agente, utilizza le istruzioni dell'agente come posizione centralizzata per archiviare istruzioni e richieste comuni.

Utilizza i piani degli agenti. I piani degli agenti possono essere utili per suddividere le attività complesse della pipeline. I piani dell'agente possono anche mostrare le ipotesi e le intenzioni dell'agente, quindi ti consigliamo di esaminarli per assicurarti che all'agente venga fornito il contesto corretto.

Dopo aver esaminato un piano, puoi modificarlo fornendo all'agente di data engineering feedback e modifiche. Ad esempio:

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

In alcuni casi, può essere utile chiedere all'agente di generare un piano che non richiede la tua approvazione esplicita. L'atto di far pianificare l'agente costringe il Data Engineering Agent a suddividere le sue azioni, il che spesso porta a risultati migliori. Puoi forzare l'agente a generare un piano ed eseguirlo automaticamente. Ad esempio:

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.

Scrivi in modo chiaro. Formula la tua richiesta in modo chiaro ed evita di essere vago. Se possibile, fornisci le origini dati di origine e di destinazione quando esegui il prompt, come mostrato nell'esempio seguente:

  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.

Fornisci richieste dirette e mirate. Fai una domanda alla volta e utilizza prompt concisi. Per i prompt con più di una domanda, elenca ogni parte distinta della domanda per migliorare la chiarezza, come mostrato nell'esempio seguente:

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

Fornisci istruzioni esplicite ed enfatizza i termini chiave. Puoi enfatizzare i termini o i concetti chiave nei prompt ed etichettare determinati requisiti come importanti, come mostrato nell'esempio seguente:

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

Specifica l'ordine delle operazioni. Per le attività ordinate, struttura il prompt in elenchi, in cui gli elementi elencati sono suddivisi in passaggi piccoli e mirati, come mostrato nell'esempio seguente:

  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.

Perfeziona ed esegui l'iterazione. Continua a provare diverse frasi e approcci per vedere cosa produce i risultati migliori. Se l'agente genera SQL non valido o altri errori, guidalo con esempi o documentazione pubblica.

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