Crea prodotti di dati con le competenze degli agenti

Panoramica

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

Cortex Framework fornisce competenze specializzate per gli agenti per estendere le sue funzionalità, consentendo all'assistente AI di guidarti nel processo di creazione di prodotti di dati che seguono 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 di consumo per la contabilità fornitori per ottenere insight 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, pronto per l'esecuzione.

Skill dell'agente

Le skill degli agenti sono un formato aperto e leggero per estendere le funzionalità degli agenti AI con conoscenze e workflow specializzati. In sostanza, una skill è una cartella contenente un file SKILL.md (che include metadati e istruzioni) insieme a script, riferimenti e asset facoltativi che indicano a un agente come eseguire un'attività specifica. Le skill raggruppano conoscenze procedurali e contesto in cartelle portatili che gli agenti caricano on demand, fornendo competenze di dominio e workflow ripetibili. Le skill di Cortex Framework sono archiviate nella directory .agent.

Skill dell'agente Cortex Framework

Il generatore di prodotti di dati basato su agenti automatizza il ciclo di vita di sviluppo end-to-end dei prodotti di dati all'interno di Cortex Framework. Se chiedi all'assistente AI di eseguire workflow di sviluppo strutturati, non dovrai più creare manualmente strutture di file, navigare in schemi SAP complessi, configurare livelli di base, gestire 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 sviluppo e modellazione dei dati attuabile.
  • Ricerca dello schema in tempo reale: esegue script che eseguono query sulle tabelle replicate del dizionario dati (DDIC) SAP per fornire informazioni di 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.
  • Quality gate 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 gli asset della documentazione, inclusa la visualizzazione dei diagrammi entità-relazione (ER) e delle chiavi primarie del modulo del prodotto di dati.

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

Prerequisiti

Prima di utilizzare le competenze degli agenti, verifica che il tuo ambiente di sviluppo soddisfi i seguenti requisiti per abilitare le query di schema in tempo reale, la compilazione dei dati e la convalida automatizzata:

  1. SDKGoogle Cloud (gcloud): installa ed esegui l'autenticazione dell'interfaccia a riga di comando (gcloud) con il tuo account utente. Per saperne di più, consulta la documentazione relativa al deployment

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

  3. Tabelle DDIC (SAP Data Dictionary) replicate: per consentire all'agente di eseguire controlli dello schema senza distinzione tra maiuscole e minuscole e 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 della tabella)
    • DD04T (Data Element Texts)
    • DD08L (Relazioni tra tabelle)
    • DD01L (Domini)
    • DD07L (Domain Values - optional)
    • DD07T (Domain Value Texts - optional)

  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 delle unità funzionino correttamente. Per saperne di più, consulta la documentazione.

Configurazione e configurazione dell'IDE

Prima di iniziare, consulta la documentazione dell'assistente di coding 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 Artefatti di installazione.

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

Google Cloud Cortex Framework espone le sue capacità agentiche tramite un insieme di skill specializzate situate 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 skill di Workspace all'avvio. Non occorrono ulteriori configurazioni. Per verificare, chiedi all'assistente:

    Quali skill hai a disposizione?

  • VSCode con Gemini Code Assist:

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

  • Altri strumenti di AI CLI: fai riferimento alla directory delle competenze in modo nativo nei prompt di istruzioni. Ad esempio:

    Leggi la skill create-data-product nella directory .agents/skills/ e crea lo scaffolding…

Crea un prodotto di dati personalizzato

I passaggi seguenti descrivono il flusso di lavoro strutturato per gli sviluppatori 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 coding AI, fornisci un prompt che descriva i tuoi requisiti specifici per i dati. Ad esempio:

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

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

  • Contesto e dominio aziendali: obiettivi dettagliati, storie degli utenti e consumatori target.
  • Specifiche dei dati di input: elenco delle tabelle di origine (ad es. LFA1, BSIK, BSEG, Z...), dettagli sul 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 di base, filtro dei clienti (mandt), eliminazioni temporanee (loekz), gestione delle mappature degli indicatori di blocco dei pagamenti (zlspr) e regole di riconciliazione (ad esempio, esclusione delle transazioni dei fornitori interaziendali per evitare tassi di turnover distorti).
  • Integrità dei dati e asserzioni di test: scenari di verifica (ad esempio, verifica dell'unicità della granularità e controllo 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, assicurando che i tipi di campo e le relazioni siano accurati. L'agente può anche richiamare altre skill per garantire che i tuoi 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 da esaminare. Questo piano include le tabelle di origine identificate, le mappature e la struttura architettonica proposta del prodotto 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 skill create-data-product per creare la struttura della 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 skill generate-er-diagram o di creare asserzioni di scaffolding utilizzando la skill create-python-tests.

Passaggio 4: esegui i quality gate 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 questo processo, l'agente genera report dettagliati sullo stato in modo che tu possa esaminare i risultati:

  1. Convalida della build: esegue uv run cortex-build --config config/config.yaml per garantire 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 sull'esecuzione del test che verifica la logica di business e le asserzioni principali.
  3. Linter e audit: sfrutta la skill validate-data-product per eseguire controlli rigorosi sulla parità dei campi e verificare la conformità alle convenzioni di denominazione, concludendo con un report dettagliato sull'idoneità.

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: invia le definizioni dei prodotti di dati compilati al tuo workspace Dataform configurato eseguendo lo script di deployment localmente (ad esempio, uv run cortex-deploy --config config/config.yaml).
  • Materializza i dati: completa il flusso di lavoro finale post-deployment per eseguire le pipeline Dataform generate, materializzando le nuove tabelle e viste direttamente in BigQuery.
  • Fornisci insight: una volta materializzato, il tuo prodotto di dati personalizzato è completamente pronto per essere connesso ad app di analisi downstream, come Gemini Enterprise, per fornire risposte intelligenti e utili alle tue domande aziendali originali.

Aggiorna un prodotto di dati esistente

Una volta creato il prodotto di dati personalizzato, non è necessario ricominciare da capo per apportare modifiche. Puoi sfruttare la skill update-data-product per aggiungere in modo iterativo nuovi campi, modificare la logica di business o integrare tabelle di origine completamente nuove. Ad esempio:

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

L'agente individuerà la configurazione, eseguirà una query sul DDIC di 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 delle 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 dispongano del ruolo IAM Visualizzatore dati BigQuery per il set di dati non elaborati 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 elemento in un prompt separato e successivo).