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 dell'agente dati. L'agente di ingegneria del contesto ti aiuta a creare, valutare e migliorare i set di contesto automatizzando la loro creazione e ottimizzazione.

Per scoprire di più sui set di contesto e su QueryData, vedi Panoramica dei set di contesto e Panoramica di QueryData.

Per creare applicazioni di dati di livello aziendale, l'accuratezza del modello text-to-SQL in genere deve raggiungere una qualità quasi del 100%. Risultati di query errati influiscono sull'usabilità complessiva dell'applicazione e sull'esperienza utente. Per ottenere risposte spiegabili e pertinenti per l'attività con elevata precisione è necessaria l'ingegneria del contesto, ovvero il processo di creazione e ottimizzazione iterativa del contesto per ottenere una precisione 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.

Agente di context engineering

L'agente di ingegneria del contesto automatizza questo workflow di ottimizzazione. Puoi conversare con l'agente per gestire attività ad hoc per ottimizzare il contesto. L'elenco seguente fornisce esempi di prompt in linguaggio naturale che puoi utilizzare per dare istruzioni all'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.
  • Prompt di esempio 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 gli elementi di contesto 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 affidabile 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 nelle varie iterazioni.

La procedura di salita sistematica

Nella ricerca in salita sistematica, l'agente migliora in modo iterativo un insieme di contesti tramite la valutazione del set di dati di riferimento, l'analisi delle lacune e gli aggiornamenti per aumentare la precisione fino a quasi il 100%.

  • Genera automaticamente il contesto di base: crea un insieme di contesto iniziale derivato dallo schema del database e dagli artefatti dell'applicazione.
  • Workflow di ottimizzazione hill climbing: consente all'agente di valutare l'accuratezza di QueryData, eseguire l'analisi delle lacune in caso di 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 ingegneria del contesto.

Attiva i servizi richiesti

Attiva 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 Cloud SQL Data, 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 Google Cloud progetto.
  • 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.

Preparare il database per le ricerche di valori

Per utilizzare le ricerche di valori semantici e 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 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 di 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 di ingegneria del contesto
  • Configura la connessione al database

Installa l'agente di ingegneria del contesto

L'agente di ingegneria 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 Installare 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'infrastruttura agentica selezionata, ad esempio Antigravity CLI, Claude Code o Gemini CLI.

A seconda del cablaggio dell'agente selezionato, segui i passaggi di installazione corrispondenti:

Antigravity CLI

Per installare l'agente di ingegneria contestuale nella CLI Antigravity:

  1. Installa Antigravity CLI. Consulta la Guida introduttiva all'interfaccia a riga di comando di Antigravity.
  2. Installa il plug-in dell'agente di ingegneria del contesto, che include workflow per la generazione del contesto. Sostituisci VERSION con la versione rilasciata richiesta: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Avvia l'interfaccia a riga di comando Antigravity: 
    agy
  4. Facoltativo. Aggiorna il plug-in: 
    agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION

Claude Code

Per installare l'agente di ingegneria contestuale in Claude Code:

  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. Facoltativo. Aggiorna il plug-in: 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (ritirata)

Per installare l'agente di ingegneria contestuale nella Gemini CLI:

  1. Installa Gemini CLI. Consulta la sezione Inizia a utilizzare Gemini CLI.
  2. Installa l'estensione: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Facoltativo. 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 ingegneria del contesto viene fornito con le competenze 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 chiedi "aiutami a configurare la connessione al database". Segui le istruzioni dell'agente per creare il file di configurazione nella directory di lavoro attuale come autoctx/tools.yaml.

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

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

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 ingegneria del contesto fornisce un insieme di competenze dell'agente e strumenti MCP per migliorare la capacità di ingegneria del contesto dell'agente di codifica. Puoi utilizzare questi strumenti insieme per generare una base di riferimento, misurare l'efficacia e applicare miglioramenti in modo iterativo. Tuttavia, puoi iniziare da qualsiasi fase del flusso di lavoro:

  • 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 invocazione dell'agente.

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

Creare ed espandere 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 dataset di riferimento, ogni modifica è un miglioramento misurabile che puoi convalidare rispetto ai dati di riferimento.

La creazione manuale di un dataset di riferimento rappresentativo richiede molto tempo e i dataset 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 essere aggiunte 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 del tuo spazio di lavoro, dove sono pronte per la valutazione. Puoi fornire un file esistente o scrivere alcuni esempi di valutazione in linea per l'agente da 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 iniziale e un codice SQL: espandilo in un set di dati più ampio e verifica che le query vengano eseguite."

Genera un set di contesti di base

Per evitare di creare il contesto da zero, puoi consentire all'agente di derivare un insieme 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 dare istruzioni all'agente:

  • "Genera un insieme di contesti 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 creato un insieme di contesto e un golden dataset, puoi consentire all'agente di misurare il rendimento del contesto eseguendo query sull'API QueryData dell'agente di dati con ogni domanda di riferimento. L'agente confronta l'SQL generato e i relativi risultati di esecuzione con la risposta prevista utilizzando Evalbench per gestire il confronto.

L'esecuzione di una valutazione fornisce quanto segue:

  • Metriche quantitative, come risultati superati e non superati e 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 golden dataset e l'ID del set di contesto. Per scoprire come trovare l'ID del contesto impostato, consulta Trovare l'ID contesto dell'agente.

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

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

Per eseguire di nuovo una configurazione di valutazione generata in precedenza senza configurarla di nuovo, chiedi all'agente o richiama direttamente la CLI:

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 l'analisi del divario e proporre miglioramenti

Per risolvere gli errori delle query, devi identificarne 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 baseline: l'agente scrive i miglioramenti in un nuovo file JSON insieme al contesto di base, conservando i file originali.

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

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

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

Elementi di contesto specifici dell'autore on demand

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

Puoi utilizzare questa funzionalità anche per aggiornamenti ad hoc, ad esempio quando devi supportare un nuovo pattern di query o risolvere un problema relativo a 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 dare istruzioni all'agente:

  • "Crea un modello per: 'Quali aeroporti si trovano in California?' con SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Crea una sfaccettatura per il filtro departure_time BETWEEN '00:00:00' AND '06:00:00' etichettato come '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'aumento del contesto e le regressioni delle query del database. Ad esempio, l'utilizzo di un modello anziché di una sfaccettatura può causare regole duplicate, mentre le ricerche di valori introdotte laddove un modello è sufficiente 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 formato libero e voglio associarli a flights.status. Che tipo di ricerca di valori devo configurare?"
  • "Qual è la differenza tra un modello e un aspetto e quando devo utilizzare ciascuno?"

Applicare operazioni collettive a un insieme di contesti

L'agente supporta gli aggiornamenti collettivi per gestire in modo coerente grandi set di contesto. Se devi aggiornare più elementi di contesto contemporaneamente, ad esempio quando viene rinominata una colonna del database, il formato di un valore di codice cambia o i modelli fanno riferimento a una tabella ritirata, 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