Creare prodotti di dati con le skill degli agenti

Panoramica

Questa guida descrive come utilizzare le skill degli agenti di Cortex Framework specializzate, fornite direttamente da Cortex Framework 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.

Cortex Framework fornisce skill degli agenti specializzate per estendere le sue funzionalità, consentendo all'assistente AI di guidarti nella creazione di prodotti di dati 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 di consumo dei conti passivi per ottenere insight sul totale dovuto, sugli importi scaduti e sul 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 open source leggero per estendere le funzionalità degli agenti AI con conoscenze e workflow specializzati. Fondamentalmente, 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 impacchettano la conoscenza procedurale e il contesto in cartelle portatili che gli agenti caricano su richiesta, fornendo competenze di dominio e workflow ripetibili. Le skill di Cortex Framework sono archiviate nella directory .agent.

Skill degli agenti di Cortex Framework

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 indichi all'assistente AI di 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 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 skill degli agenti è un processo iterativo. Puoi iniziare con gli obiettivi iniziali, esaminare il piano di implementazione proposto dall'agente, inclusi i diagrammi e gli 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 skill 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 automatizzata:

  1. Google Cloud SDK (gcloud) : installa ed esegui l'autenticazione della CLI (gcloud) con il tuo account utente. Per ulteriori informazioni, 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 ulteriori informazioni, consulta la sezione 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 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 ulteriori informazioni, consulta la documentazione.

Configurazione dell'IDE e dell'installazione

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 ulteriori informazioni, consulta la sezione Artefatti di installazione.

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

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

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

    Quali skill 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 skill dalla directory .agents/skills/.

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

    Leggi la skill create-data-product all'interno della directory .agents/skills/ e crea lo scaffolding...

Creare un prodotto di dati personalizzato

I seguenti passaggi descrivono il workflow di sviluppo strutturato per l'utilizzo delle skill 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 sui conti passivi 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 dei conti passivi 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 Markdown o in altri formati strutturati) forniscono all'agente un contesto fondamentale, ad esempio:

  • Contesto e dominio aziendale: obiettivi dettagliati, user story 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 garanzia 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ù skill, ad esempio la skill 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 skill per assicurarsi 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 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 skill 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 ulteriori informazioni 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 lo scaffolding delle asserzioni utilizzando la skill 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 skill 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.

Aggiornare 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 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 custom_finance AP. 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 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 la percentuale di successo fornendo istruzioni più piccole e atomiche (ad esempio, indica 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).