Crea prodotti di dati con le competenze degli agenti

Questa guida descrive come utilizzare le competenze degli agenti di Cortex Framework specializzate, fornite direttamente nel repository GitHub, con un assistente di codifica AI (come Gemini abbinato al framework di sviluppo degli agenti Antigravity) per creare prodotti di dati personalizzati che seguano le best practice di Cortex Framework.

Con queste funzionalità, puoi utilizzare il linguaggio naturale per richiedere un nuovo prodotto di dati in base a requisiti aziendali specifici. Ad esempio, puoi richiedere un prodotto di dati sui consumi di contabilità fornitori per ottenere informazioni su importo totale dovuto, importi scaduti e fatturato. Il risultato è un prodotto di dati Cortex Framework completamente integrato, creato in base ai requisiti e ai dati specifici del cliente e pronto per l'esecuzione.

Panoramica

Il generatore di prodotti di dati degli agenti automatizza il ciclo di vita di sviluppo end-to-end dei prodotti di dati all'interno di Cortex Framework. Se istruisci l'assistente AI a eseguire workflow di sviluppo strutturati, non dovrai più creare manualmente le strutture dei file, navigare in schemi SAP complessi, configurare i livelli di base, gestire gli spazi dei nomi personalizzati e scrivere codice SQLX Dataform boilerplate.

L'assistente AI gestisce le seguenti attività principali:

  • Pianificazione e mappatura dei requisiti: traduce i requisiti aziendali concreti in un piano di modellazione e sviluppo dei dati pratico.
  • Ricerca dello schema live: esegue script che eseguono query sulle tabelle del dizionario dei dati SAP (DDIC) replicate per fornire informazioni sul contesto specifiche del cliente, come i campi Z personalizzati.
  • Scaffolding boilerplate: genera automaticamente tutti i file di configurazione, i metadati e gli artefatti di codice SQLX o JavaScript richiesti.
  • Gate di qualità dei dati: convalida i prodotti di dati eseguendo build locali, compilando codice SQL, eseguendo test di unità e di integrazione e verificando la conformità agli standard di denominazione.
  • Creazione della documentazione: crea automaticamente asset di documentazione, inclusa la visualizzazione dei diagrammi delle relazioni tra entità (ER) e delle chiavi primarie del modulo del prodotto di dati.

Lo sviluppo di prodotti di dati con queste competenze degli agenti è un processo iterativo. Puoi iniziare con gli obiettivi iniziali, esaminare il piano di implementazione proposto dall'agente, inclusi diagrammi e schemi ER, e chiedere all'assistente AI di perfezionare la logica in modo conversazionale man mano che procedi. Sebbene l'agente acceleri lo sviluppo, hai il pieno controllo per esaminare e approvare tutto il codice generato prima di eseguirne il commit nel repository. Inoltre, poiché questi script degli agenti vengono eseguiti localmente utilizzando le credenziali autenticate, rispettano intrinsecamente i limiti di accesso esistenti di Google Cloud e BigQuery.

Prerequisiti

Prima di utilizzare le competenze degli agenti, verifica che l'ambiente di sviluppo soddisfi i seguenti requisiti per abilitare le query dello schema live, la compilazione dei dati e la convalida automatica:

  1. Google Cloud SDK (gcloud) : installa e autentica l'interfaccia a riga di comando (gcloud) con il tuo account utente. Per saperne di più, consulta la documentazione sul deployment

  2. Credenziali predefinite dell'applicazione (ADC): configura le ADC locali e le destinazioni del progetto in modo che gli strumenti di compilazione locali e le suite pytest possano comunicare con BigQuery. Per saperne di più, consulta la pagina Preparare il progetto predefinito Google Cloud

  3. Tabelle del dizionario dei dati SAP (DDIC) replicate: per consentire all'agente di eseguire controlli dello schema senza distinzione tra maiuscole e minuscole e di verificare con precisione le lunghezze dei campi, replica le seguenti tabelle di metadati SAP nel set di dati BigQuery di destinazione non elaborato:

    • DD03L (Campi tabella)
    • DD04T (Testi degli elementi di dati)
    • DD08L (Relazioni tra tabelle)
    • DD01L (Domini)
    • DD07L (Valori di dominio - facoltativo)
    • DD07T (Testi dei valori di dominio - facoltativo)

  4. Ambiente Python locale: installa le dipendenze locali ed esegui lo strumento di sincronizzazione utilizzando uv per assicurarti che le librerie di convalida e i test di unità funzionino correttamente. Per saperne di più, consulta la documentazione.

Configurazione e configurazione dell'IDE

Prima di iniziare, consulta la documentazione dell'assistente di codifica AI che preferisci per le istruzioni di installazione e configurazione (ad esempio, Antigravity).

  1. Raccogli gli artefatti di installazione richiesti e clona il repository. Per saperne di più, consulta la sezione Artefatti di installazione.

  2. Apri l'impronta del codice sorgente di Google Cloud Cortex Framework clonata nell'assistente di codifica AI designato.

Google Cloud Cortex Framework espone le sue capacità agentiche tramite un insieme di competenze specializzate che si trovano nella directory .agents/skills/ del repository. Puoi utilizzare queste competenze in più ambienti di sviluppo:

  • Framework Antigravity: Antigravity rileva, indicizza e attiva automaticamente tutte le competenze dell'area di lavoro all'avvio. Non è richiesta alcuna configurazione aggiuntiva. Per verificare, chiedi all'assistente:

    "Quali competenze hai a disposizione?"

  • VSCode con Gemini Code Assist:

    1. Installa l'estensione Gemini Code Assist da VS Code Marketplace.
    2. Apri la cartella cortex-framework-core come area di lavoro. L'assistente esegue automaticamente la scansione e carica le competenze dalla directory .agents/skills/.

  • **Altri strumenti AI CLI **: fai riferimento alla directory delle competenze in modo nativo nei prompt delle istruzioni. Ad esempio, > "Leggi la competenza create-data-product all'interno della directory .agents/skills/ e crea lo scaffolding...".

Crea un prodotto di dati personalizzato

I seguenti passaggi descrivono il workflow di sviluppo strutturato per l'utilizzo delle competenze degli agenti per creare un prodotto di dati personalizzato.

Passaggio 1: fornisci requisiti e contesto

Utilizzando l'interfaccia di chat dell'assistente di codifica AI, fornisci un prompt che descriva i tuoi requisiti di dati specifici. Ad esempio:

Crea un prodotto di dati Cortex Framework per gli insight sulla contabilità fornitori destinato a SAP S/4HANA ed ECC. Utilizza lo spazio dei nomi: custom_finance. Il requisito aziendale principale è tenere traccia degli importi totali dovuti e scaduti dei nostri fornitori e calcolare il tasso di rotazione della contabilità fornitori per codice società.

Tieni presente che puoi anche fare riferimento ai documenti di requisiti o specifiche esistenti direttamente nel prompt. Questi documenti (che possono essere in formato Markdown o in altri formati strutturati) forniscono all'agente un contesto fondamentale, ad esempio:

  • Contesto e dominio aziendale: obiettivi dettagliati, storie utente e consumatori target.
  • Specifiche dei dati di input: elenco delle tabelle di origine (ad es. LFA1, BSIK, BSEG ,Z...), dettagli del controllo delle versioni (ECC rispetto a S/4HANA), regole di esclusione, campi personalizzati e altro ancora.
  • Logica di trasformazione e regole aziendali: vincoli di mappatura principali, filtro client (mandt), eliminazioni temporanee (loekz), gestione delle mappature dell'indicatore del blocco di pagamento (zlspr) e regole di riconciliazione (ad esempio, esclusione delle transazioni tra società del gruppo per evitare tassi di rotazione distorti).
  • Integrità dei dati e asserzioni di test: scenari di verifica (ad esempio, verifica dell'unicità della granularità e verifica che la somma degli importi delle fatture da pagare nell'output finale corrisponda esattamente alle tabelle di origine non elaborate).

Passaggio 2: esamina il piano di implementazione

Dopo aver delineato i requisiti, l'agente utilizza più competenze, ad esempio la competenza query-sap-ddic per eseguire query sulle tabelle di metadati DDIC BigQuery non elaborate. In questo modo, l'agente può identificare e convalidare le tabelle di origine richieste, assicurandosi che i tipi di campi e le relazioni siano accurati. L'agente può anche richiamare altre competenze per assicurarsi che i requisiti siano perfettamente in linea con le best practice di Cortex Framework.

Prima di iniziare l'implementazione, l'agente fornisce un breve piano di implementazione per la tua revisione. Questo piano include le tabelle di origine, le mappature e la struttura architetturale proposta del prodotto di dati. Esamina questo piano e richiedi eventuali modifiche prima di confermare.

Passaggio 3: genera il prodotto di dati

Dopo aver confermato il piano di implementazione, l'agente utilizza la competenza create-data-product per creare lo scaffolding della struttura delle directory. In questo modo, i nuovi sviluppi personalizzati vengono isolati dagli aggiornamenti della piattaforma principale nello spazio dei nomi personalizzato designato:

src/data_modules/<custom_namespace>/products/<dataproductname>/
├── manifest.yaml
├── table_settings.default.yaml
├── README.md
├── definitions/
│   └── [ecc|s4]/
│       └── <product_name>.js
└── annotations/
    └── [ecc|s4]/
        └── <product_name>.yaml

Per saperne di più sulla struttura delle cartelle e sui singoli file, consulta la documentazione della Guida all'estensibilità.

Durante questa fase, puoi anche chiedere all'agente di visualizzare automaticamente le relazioni utilizzando la competenza generate-er-diagram o di creare lo scaffolding delle asserzioni utilizzando la competenza create-python-tests.

Passaggio 4: esegui i gate di qualità e verifica i dati

A seconda delle autorizzazioni concesse, l'agente eseguirà automaticamente i seguenti gate di convalida obbligatori o ti chiederà di eseguirli. Durante questa procedura, l'agente genera report sullo stato granulari in modo che tu possa esaminare i risultati:

  1. Convalida della build: esegue uv run cortex-build --config config/config.yaml per assicurarsi che tutti i modelli SQL generati vengano compilati correttamente, producendo un riepilogo della build.
  2. Esecuzione di Pytest: esegue la suite completa di test delle unità Python, generando un report di esecuzione dei test che verifica la logica di business e le asserzioni principali.
  3. Linter e audit: utilizza la competenza validate-data-product per eseguire controlli rigorosi di parità dei campi e verificare la conformità alle convenzioni di denominazione, concludendo con un report di preparazione dettagliato.

Passaggio 5: esegui il deployment e l'esecuzione

Dopo aver esaminato i report di convalida e approvato il codice generato, puoi eseguire il deployment degli asset del prodotto di dati.

  • Esegui il deployment degli asset: esegui il push delle definizioni del prodotto di dati compilate nell'area di lavoro Dataform configurata eseguendo lo script di deployment localmente (ad esempio, uv run cortex-deploy --config config/config.yaml).
  • Materializza i dati: completa il workflow finale post-deployment per eseguire le pipeline Dataform generate, materializzando le nuove tabelle e visualizzazioni direttamente in BigQuery.
  • Fornisci insight: una volta materializzato, il prodotto di dati personalizzato è completamente pronto per essere collegato alle app di analisi downstream, come Gemini Enterprise, per fornire risposte intelligenti e pratiche alle domande aziendali originali.

Aggiorna un prodotto di dati esistente

Una volta creato il prodotto di dati personalizzato, non devi ricominciare da zero per apportare modifiche. Puoi utilizzare la skill update-data-product per iterare l'aggiunta di nuovi campi, regolare la logica di business o integrare tabelle di origine completamente nuove. Ad esempio:

Aggiorna il mio prodotto di dati di contabilità fornitori custom_finance. Aggiungi il campo dei termini di pagamento (ZTERM) dalla tabella di origine LFA1 e assicurati che sia mappato correttamente alla visualizzazione dell'output finale. Al termine, esegui la convalida della build.

L'agente individuerà la configurazione, eseguirà una query sul DDIC BigQuery per i requisiti esatti dei campi, aggiornerà il codice Dataform ed eseguirà i controlli di build necessari per verificare la modifica.

Best practice e limitazioni

  • Errori di query dello schema: se l'agente non riesce a recuperare gli schemi dei metadati SAP, verifica che le credenziali predefinite dell'applicazione (ADC) locali siano attive e che abbiano il ruolo IAM Visualizzatore dati BigQuery per il set di dati non elaborato di destinazione.
  • Limiti di contesto: se stai creando un prodotto di dati eccezionalmente grande che coinvolge decine di tabelle, l'agente potrebbe perdere il contesto. Aumenta il tasso di successo fornendo istruzioni più piccole e atomiche (ad esempio, chiedi all'agente di creare prima le dimensioni a livello di intestazione e poi di aggiungere i fatti a livello di articolo in un prompt di follow-up separato).