Creare set di contesti utilizzando l'agente di ingegneria del contesto

Questo documento descrive come creare e ottimizzare i set di contesti che aiutano a ottenere un'elevata accuratezza delle query QueryData nelle applicazioni degli agenti di dati. L'agente di context engineering ti aiuta a creare, valutare e migliorare i set di contesto automatizzandone la creazione e l'ottimizzazione.

Per scoprire di più sui set di contesti e su QueryData, consulta Panoramica dei set di contesti e Panoramica di QueryData.

Per creare applicazioni di dati di livello enterprise, l'accuratezza del modello text-to-query deve in genere raggiungere una qualità vicina al 100%. L'SQL generato in modo errato influisce sull'usabilità complessiva dell'applicazione e sull'esperienza utente. Per ottenere risposte spiegabili e pertinenti per l'attività con un'elevata accuratezza, è necessario il context engineering, ovvero il processo di creazione e ottimizzazione iterativa del contesto per ottenere un'accuratezza ottimale.

Fornendo QueryData con il contesto mirato alla tua applicazione aziendale, fornisci le regole aziendali precise di cui il sistema ha bisogno per risolvere l'intento dell'utente sfumato.

Agente di context engineering

L'agente di context engineering automatizza questo workflow di ottimizzazione. Puoi conversare con l'agente per gestire attività ad hoc e ottimizzare il contesto. Il seguente elenco fornisce esempi di prompt in linguaggio naturale che puoi utilizzare per istruire l'agente, insieme a una descrizione di come risponde l'agente. Utilizza questi esempi per creare e ottimizzare il contesto:

  • Esempio di prompt per l'analisi degli errori: "Aggiorna il contesto in modo da identificare correttamente l'aeroporto per query come 'voli per Disney World'". L'agente analizza l'errore, valuta il problema e consiglia di aggiungere un elemento di contesto appropriato, ad esempio una query di ricerca di valori.
  • Esempio di prompt per il suggerimento di contesto: "Leggi il codice della mia app e suggerisci un contesto da aggiungere." L'agente analizza il codice, ragiona sul dominio della tua applicazione e suggerisce quali elementi di contesto sarebbero pertinenti.
  • Prompt di esempio per l'elaborazione collettiva: "Ecco 10 esempi di domande e query SQL. Trasformali in modelli." L'agente elabora in blocco i tuoi input e aggiorna il set di contesto.

Importanza del set di dati di riferimento

Per ottimizzare il contesto, devi prima creare un set di dati che corrisponda agli input in linguaggio naturale della tua applicazione. L'agente può aiutarti a creare questo set di dati di riferimento, che consiste in domande degli utenti e nelle query del database previste. Un set di dati di riferimento ti consente di:

  • Stabilisci una base di riferimento per le prestazioni delle query.
  • Convalida gli aggiornamenti rispetto alle query del database di dati empirici reali.
  • Misura i miglioramenti dell'accuratezza tra le iterazioni.

Il processo sistematico di hill climbing

Nell'hill climbing sistematico, l'agente migliora in modo iterativo un set di contesto tramite la valutazione del set di dati di riferimento, l'analisi dei gap e gli aggiornamenti per aumentare l'accuratezza fino a quasi il 100%.

  • Genera automaticamente il contesto di base: crea un set di contesto di partenza derivato dallo schema del database e dagli artefatti dell'applicazione.
  • Workflow di ottimizzazione hill climbing: consenti all'agente di valutare l'accuratezza di QueryData, eseguire l'analisi dei gap sugli errori e proporre automaticamente miglioramenti per aumentare l'accuratezza.

Il seguente diagramma mostra il flusso di lavoro di hill climbing sistematico:

Flusso di lavoro per creare il contesto in modo iterativo.

Prima di iniziare

Completa i seguenti prerequisiti prima di utilizzare l'agente di progettazione del contesto.

Abilita i servizi richiesti

Abilita i seguenti servizi per il tuo progetto:

Prepara un'istanza Cloud SQL

Ruoli e autorizzazioni richiesti

Concedi l'autorizzazione executesql all'istanza Cloud SQL

Per concedere l'autorizzazione executesql all'istanza Cloud SQL e abilitare l'API di dati Cloud SQL, esegui questo comando: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Sostituisci quanto segue:
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • INSTANCE_ID: l'ID dell'istanza Cloud SQL.
Per eseguire i passaggi di questo tutorial, accedi a Google Cloud, quindi autenticati al database utilizzando l'autenticazione IAM.

Prepara il database per le ricerche di valori

Per utilizzare le ricerche semantiche e di valori trigrammi, devi configurare l'istanza Cloud SQL per MySQL in modo che supporti gli incorporamenti vettoriali e l'indicizzazione n-grammi.

  1. Per consentire all'istanza Cloud SQL per MySQL di eseguire ricerche di valori semantici, attiva i seguenti flag.

    1. Attiva il flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Abilita il flag enable-google-ml-integration per consentire all'istanza Cloud SQL per MySQL di integrarsi con Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Crea una colonna vettoriale per archiviare gli embedding delle città

      ALTER TABLE `airports`
ADD COLUMN `city_embedding` VECTOR(768);

    4. Generare e archiviare i vector embedding per i nomi delle città

      UPDATE `airports`
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`)
WHERE `city` IS NOT NULL;

  2. Per consentire all'istanza Cloud SQL per MySQL di eseguire ricerche di valori di trigrammi, segui questi passaggi:

    1. Attiva il flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Crea un indice FULLTEXT per la corrispondenza dei trigrammi sul nome dell'aeroporto:

      CREATE FULLTEXT INDEX `idx_ngram_airports_name`
ON `airports`(`name`) 
WITH PARSER ngram;

prepara l'ambiente

Puoi creare file di set di contesto da qualsiasi ambiente di sviluppo locale o IDE. Per preparare l'ambiente, completa i seguenti passaggi:

  • Installa l'agente del motore contestuale
  • Configurare la connessione al database

Installa l'agente del motore contestuale

L'agente di progettazione del contesto esegue il server Model Context Protocol (MCP) che richiede uv per gestire i pacchetti Python sottostanti.

  1. Installa uv seguendo le istruzioni riportate in Installa uv.

  2. Verifica che uv sia installato e accessibile dalla riga di comando:

    uv --version

Per preparare l'ambiente, installa l'agente di ingegneria del contesto nell'imbracatura dell'agente selezionata, ad esempio Antigravity CLI, Claude Code o Gemini CLI.

A seconda dell'infrastruttura agentica selezionata, segui i passaggi di installazione corrispondenti:

Antigravity CLI

Per installare l'agente di context engineering nell'interfaccia a riga di comando di Antigravity, segui questi passaggi:

  1. Installa Antigravity CLI. Consulta Introduzione all'interfaccia a riga di comando di Antigravity.
  2. Installa il plugin agenti di context engineering, che include i workflow per la generazione del contesto: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Avvia Antigravity CLI: 
    agy

Per aggiornare il plug-in all'ultima versione:

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

Claude Code

Per installare l'agente di context engineering in Claude Code, segui questi passaggi:

  1. Aggiungi il marketplace dei plug-in: 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Installa il plug-in: 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Ricarica i plug-in per attivare le modifiche: 
    /reload-plugins
  4. Aggiorna il plug-in: 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (deprecato)

Per installare l'agente di context engineering nell'interfaccia a riga di comando di Gemini, segui questi passaggi:

  1. Installa Gemini CLI. Consulta la sezione Guida introduttiva a Gemini CLI.
  2. Installa l'estensione: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Aggiorna l'estensione: 
    gemini extensions update mcp-db-context-enrichment

Configura la connessione al database

L'agente richiede una connessione al database per recuperare gli schemi e la possibilità di convalidare la sintassi del contesto SQL generato. Per consentire all'agente di interagire con il tuo database, configura le credenziali di autenticazione e definisci la configurazione della connessione al database.

Configura le credenziali predefinite dell'applicazione

Configura le Credenziali predefinite dell'applicazione (ADC) per fornire le credenziali utente per l'accesso alle risorse Google Cloud dall'agente di ingegneria del contesto:

  • Server MCP Toolbox: utilizza le credenziali per connettersi al database, recuperare gli schemi ed eseguire SQL per la convalida.
  • Evalbench: utilizza le credenziali per richiamare QueryData per la valutazione.

Esegui questi comandi nel terminale per l'autenticazione:

gcloud auth application-default login

Configura il file di connessione al database

L'agente richiede una connessione al database per la generazione del contesto, che MCP Toolbox supporta e definisce all'interno di un file di configurazione.

Il file di configurazione specifica l'origine del database e gli strumenti necessari per recuperare gli schemi o eseguire SQL. L'agente di progettazione del contesto è dotato di skill dell'agente preinstallate per aiutarti a generare la configurazione.

  1. Avvia l'ambiente dell'agente.

  2. Chiedi all'agente di aiutarti a configurare la connessione al database, ad esempio con il prompt "aiutami a configurare la connessione al database". Segui le istruzioni dell'agente per creare il file di configurazione nella directory di lavoro corrente come autoctx/tools.yaml.

  3. Per applicare la nuova configurazione di tools.yaml, ricarica la connessione:

    • Nella Antigravity CLI, esegui /mcp e seleziona toolbox per riavviare.
    • In Gemini CLI, esegui /mcp reload.
    • In Claude Code, esegui /mcp, seleziona toolbox e seleziona Reconnect.

Per ulteriori informazioni sulla configurazione manuale del file di configurazione del database, consulta Configurazione di MCP Toolbox.

Generare e ottimizzare il contesto

L'agente di context engineering fornisce un insieme di skill dell'agente e strumenti MCP per migliorare la funzionalità di context engineering dell'agente di programmazione. Puoi utilizzare questi strumenti insieme per generare una baseline, misurare l'efficacia e applicare miglioramenti in modo iterativo. Tuttavia, puoi iniziare in qualsiasi fase del workflow:

  • Se hai già impostato un contesto, puoi procedere direttamente alla valutazione.
  • Se hai query non riuscite che vuoi correggere, puoi procedere direttamente all'analisi delle lacune.

Ogni funzionalità descrive le azioni, i casi d'uso e i comandi di chiamata dell'agente.

I prompt di esempio mostrano come puoi eseguire query sull'agente in linguaggio naturale. Se l'agente richiede ulteriori dettagli per completare una richiesta, ti chiede chiarimenti.

Crea ed espandi i set di dati di valutazione

Per migliorare il rendimento, devi prima misurarlo. L'ingegneria del contesto senza un set di dati di riferimento, costituito da domande degli utenti abbinate al codice SQL previsto, non dispone di una verifica sistematica. Con un set di dati d'oro, ogni modifica è un miglioramento misurabile che puoi convalidare rispetto ai dati di fatto.

La creazione manuale di un set di dati d'oro rappresentativo richiede tempo e i set di dati di piccole dimensioni potrebbero non includere le variazioni nella formulazione degli utenti. L'agente risolve il problema:

  • Generazione di coppie domanda-SQL candidate in base allo schema del database.
  • Espandere un piccolo set di dati iniziali utilizzando variazioni di filtri, sinonimi e riformulazioni.

Facoltativamente, puoi consentire all'agente di eseguire l'SQL generato sul tuo database. Questa verifica conferma che le query vengono eseguite correttamente prima di aggiungerle al set di dati.

Il set di dati è un file JSON contenente coppie domanda-SQL:

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

Le coppie approvate vengono inserite nel file autoctx/golden.json nel tuo workspace, dove sono pronte per la valutazione. Puoi fornire un file esistente o scrivere alcuni esempi di valutazione in linea che l'agente può espandere.

Puoi utilizzare i seguenti prompt di esempio per dare istruzioni all'agente:

  • "Genera un set di dati di valutazione dal mio schema".
  • "Ecco una domanda di partenza e l'SQL. Espandilo in un set di dati più ampio e verifica le query eseguite."

Genera un set di contesti di base

Per evitare di creare il contesto da zero, puoi consentire all'agente di derivare un set di contesto iniziale dallo schema del database e dagli artefatti dell'applicazione, come regole aziendali, query di esempio o file README. Anche se questo contesto di base non è definitivo, fornisce un punto di partenza convalidato basato sul modello di database.

Puoi utilizzare i seguenti prompt di esempio per istruire l'agente:

  • "Genera un set di contesto dal mio schema."
  • "Genera il contesto iniziale utilizzando questi schemi e le regole aziendali in requirements.md."

L'agente ti chiede di assegnare un nome all'esperimento, che organizza gli artefatti generati, e potrebbe chiederti di restringere l'ambito se lo schema del database è di grandi dimensioni. Per caricare il contesto utilizzando Cloud SQL Studio, segui le istruzioni dopo che l'agente genera il file JSON.

Valutare l'efficacia del contesto

Dopo aver stabilito un set di contesti e un set di dati golden, puoi consentire all'agente di misurare le prestazioni del contesto eseguendo query sull'API QueryData dell'agente di dati con ogni domanda golden. L'agente confronta l'SQL generato e i risultati della sua esecuzione con la risposta prevista utilizzando Evalbench per gestire il confronto.

L'esecuzione di una valutazione fornisce quanto segue:

  • Metriche quantitative, come i risultati di superamento e mancato superamento e i punteggi aggregati, per monitorare i progressi nelle iterazioni del contesto.
  • Un riepilogo della conversazione in linea e report CSV dettagliati scritti nella directory eval_reports/ della cartella dell'esperimento.

Per avviare una valutazione, fornisci il percorso del set di dati di riferimento e l'ID del set di contesto. Per scoprire come trovare l'ID del contesto, consulta la sezione Trovare l'ID contesto dell'agente.

Puoi utilizzare i seguenti prompt di esempio per istruire l'agente:

  • "Valuta il mio contesto rispetto a golden.json".
  • "Esegui di nuovo la valutazione utilizzando la configurazione del mio ultimo esperimento."

Per eseguire nuovamente una configurazione di valutazione generata in precedenza senza configurarla di nuovo, chiedi all'agente o richiama direttamente l'interfaccia a riga di comando:

uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

Per informazioni dettagliate sullo schema di configurazione della valutazione e su come personalizzare le esecuzioni della valutazione, consulta la documentazione di Evalbench.

Eseguire un'analisi dei gap e proporre miglioramenti

Per risolvere gli errori delle query, devi identificare le cause principali, ad esempio colonne errate, join di tabelle mancanti o termini fuzzy non risolti. L'identificazione manuale di questi problemi richiede un'analisi approfondita dei report di valutazione.

L'agente automatizza questo ciclo di analisi e correzione:

  • Analisi delle lacune: l'agente legge i risultati della valutazione e il contesto impostato per raggruppare errori simili e consigliare aggiunte di contesto mirate, ad esempio modelli, sfaccettature o ricerche di valori.
  • Correzioni proposte: l'agente propone modifiche concrete e, facoltativamente, testa l'SQL sul tuo database per verificare la risoluzione.
  • Conservazione della base di riferimento: l'agente scrive i miglioramenti in un nuovo file JSON insieme al contesto della base di riferimento, conservando i file originali.

Puoi utilizzare i seguenti prompt di esempio per istruire l'agente:

  • "Esegui l'analisi delle lacune sulla mia ultima valutazione e proponi correzioni".
  • "Ottimizza questo set di contesto rispetto a golden.json."

Per prepararti all'iterazione successiva, carica il contesto migliorato nel set di contesti di destinazione utilizzando Data Agents Studio, segui le istruzioni.

Crea elementi di contesto specifici on demand

Se conosci già il contesto richiesto, ad esempio un template per una domanda specifica, un facet per un filtro ripetuto o una ricerca di valori per una colonna specifica, la scrittura manuale del JSON del contesto può introdurre errori di serializzazione nei nomi dei parametri, nei metadati dei tipi o nella sintassi dei frammenti. L'agente gestisce la formattazione JSON per consentirti di concentrarti sull'intent aziendale.

Puoi utilizzare questa funzionalità anche per aggiornamenti ad hoc, ad esempio quando devi supportare un nuovo pattern di query o risolvere un dettaglio dello schema mancante. Per ottenere il JSON, descrivi il contesto richiesto all'agente senza eseguire una valutazione o configurare un esperimento.

Questa è anche la funzionalità giusta da utilizzare quando ti viene assegnata un'attività una tantum: un stakeholder ti fornisce una nuova coppia domanda-SQL che vuole supportare oppure noti una sfaccettatura mancante durante una revisione del codice. Non è necessario configurare un esperimento o eseguire una valutazione per risolvere il problema: descrivi cosa vuoi e l'agente produce il JSON.

Puoi utilizzare i seguenti prompt di esempio per istruire l'agente:

  • "Crea un template per: 'Quali aeroporti si trovano in California?' con SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Crea un facet per il filtro departure_time BETWEEN '00:00:00' AND '06:00:00' con l'etichetta 'occhi rossi'."
  • "Crea una ricerca di valori per airports.iata."

Motivo della selezione del tipo di contesto

La selezione del tipo di contesto corretto, indipendentemente dal fatto che si tratti di una ricerca di modelli, facet o valori, aiuta a evitare l'eccesso di contesto e le regressioni delle query del database. Ad esempio, l'utilizzo di un template anziché di un facet può causare regole duplicate, mentre le ricerche di valori introdotte dove è sufficiente un template possono aumentare la latenza delle query. Per trovare il formato dello schema corretto, chiedi all'agente di consigliare un tipo in base alla struttura della query o alle colonne del database prima di creare elementi di contesto. L'agente spiega il suo ragionamento per aiutarti a comprendere le opzioni di contesto.

Puoi utilizzare i seguenti prompt di esempio per dare istruzioni all'agente:

  • "Continuo a scrivere il filtro departure_time BETWEEN '00:00:00' AND '06:00:00' in molte query. Qual è il modo migliore per acquisire questo dato?"
  • "Gli utenti descrivono lo stato del volo in testo libero e voglio abbinarli a flights.status. Che tipo di ricerca di valori devo configurare?"
  • "Qual è la differenza tra un modello e un facet e quando devo utilizzare l'uno o l'altro?"

Applica operazioni collettive a un set di contesti

L'agente supporta gli aggiornamenti collettivi per gestire in modo coerente set di contesti di grandi dimensioni. Se devi aggiornare più elementi di contesto contemporaneamente, ad esempio quando una colonna del database viene rinominata, un valore di codice cambia formato o i modelli fanno riferimento a una tabella deprecata, l'agente può applicare la modifica a ogni elemento interessato senza alterare le voci non correlate.

Puoi utilizzare i seguenti prompt di esempio per dare istruzioni all'agente:

  • "Leggi golden.txt e trasforma tutte le coppie in modelli."
  • "In context_set.json, sostituisci airline = 'UA' con airline = 'United Airlines' per qualsiasi elemento che faccia riferimento a "United". Lascia stare gli elementi non correlati."

Passaggi successivi