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 per i 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 a QueryData il contesto mirato alla tua applicazione aziendale, fornisci le regole aziendali precise di cui il sistema ha bisogno per risolvere l'intento dell'utente con sfumature.

Agente di context engineering

L'agente di context engineering automatizza questo workflow di ottimizzazione. Puoi conversare con l'agente per gestire attività ad hoc per 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, ragiona sulla lacuna e consiglia di aggiungere un elemento di contesto appropriato, ad esempio una query di ricerca di valori.
  • Prompt di esempio per i suggerimenti contestuali: "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.
  • Esempio di prompt 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 nelle 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 dei dati di fatto.
  • 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 iniziale 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 sistematico di hill climbing:

Flusso di lavoro per la creazione iterativa del contesto.

Prima di iniziare

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

Attiva i servizi richiesti

Abilita i seguenti servizi per il tuo progetto:

Prepara un cluster, un'istanza e un database AlloyDB per PostgreSQL

Assicurati di avere accesso a un cluster e a un'istanza AlloyDB esistenti o creane di nuovi.
Questo tutorial richiede un database nell'istanza AlloyDB. Per saperne di più, consulta Crea un database.

Ruoli e autorizzazioni richiesti

  • Aggiungi un utente o un account di servizio Identity and Access Management (IAM) al cluster a livello di database. Per saperne di più, consulta Gestisci gli utenti del database.
  • Concedi i ruoli alloydb.databaseUser, serviceusage.serviceUsageConsumer e geminidataanalytics.queryDataUser all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi l'associazione delle policy IAM per un progetto.
  • Per creare, caricare e gestire i set di contesto, concedi il ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) all'utente IAM a livello di progetto. Per saperne di più, consulta Autorizzazioni dei set di contesto.

Concedi l'autorizzazione executesql all'istanza AlloyDB per PostgreSQL

Per concedere l'autorizzazione executesql all'istanza AlloyDB per PostgreSQL e impostare l'impostazione dell'istanza data_api_access sul valore ALLOW_DATA_API, utilizza il seguente comando curl: 
   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'
Sostituisci quanto segue:
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la regione in cui si trova il cluster AlloyDB.
  • CLUSTER_ID: l'ID del tuo cluster AlloyDB.
  • INSTANCE_ID: l'ID dell'istanza AlloyDB.
Per eseguire i passaggi di questo tutorial, accedi a Google Cloud, quindi esegui l'autenticazione nel database utilizzando l'autenticazione IAM.

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
  • Configura 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 context engineering nell'harness dell'agente selezionato, ad esempio l'interfaccia a riga di comando Antigravity, Claude Code o l'interfaccia a riga di comando Gemini.

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 Antigravity, segui questi passaggi:

  1. Installa Antigravity CLI. Consulta la sezione Inizia a utilizzare l'interfaccia a riga di comando di Antigravity.
  2. Installa il plug-in dell'agente di context engineering, che include i workflow per la generazione del contesto. Sostituisci VERSION con la versione di release richiesta: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Avvia Antigravity CLI: 
    agy

Per aggiornare il plug-in all'ultima versione, esegui questo comando. Sostituisci VERSION con la versione di release richiesta:

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

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 Inizia a utilizzare Gemini CLI.
  2. Installa l'estensione: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Aggiorna l'estensione: 
    gemini extensions update google-cloud-db-context-engineering

Configura la connessione al database

L'agente richiede una connessione al database per recuperare gli schemi e la capacità 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 accedere alle risorse Google Cloud dall'agente di context engineering:

  • 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 questo comando nel terminale per eseguire 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, supportata da MCP Toolbox e definita 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.

Genera e ottimizza 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 base di riferimento, misurare l'efficacia e applicare i miglioramenti in modo iterativo. Tuttavia, puoi iniziare in qualsiasi fase del flusso di lavoro:

  • Se hai già un set di contesto, puoi procedere direttamente alla valutazione.
  • Se hai query con errori che vuoi correggere, puoi procedere direttamente all'analisi dei gap.

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. Il context engineering senza un set di dati golden, che consiste in domande degli utenti abbinate all'SQL previsto, manca 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 di domande-SQL candidate in base allo schema del database.
  • Espansione di un piccolo set di dati di seed utilizzando varianti 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:

json [ { "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 istruire l'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 le query eseguite."

Genera un set di contesti di riferimento

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 del database.

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

  • "Genera un set 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 AlloyDB Studio, segui le istruzioni dopo che l'agente ha generato il file JSON.

Valuta 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 per i 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 d'oro e l'ID del set di contesto. Per scoprire come trovare l'ID del set di contesto, consulta Trova 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 --experiment_config=autoctx/experiments/my-experiment/eval_configs/run_config.yaml

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 delle lacune 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 dei gap: l'agente legge i risultati della valutazione e il set di contesto per raggruppare gli errori simili e consigliare aggiunte di contesto mirate, come modelli, facet 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 accanto al contesto di base, 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 delle correzioni."
  • "Ottimizza questo set di contesti rispetto a golden.json."

Per prepararti all'iterazione successiva, carica il contesto migliorato nel set di contesti di destinazione utilizzando AlloyDB 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: uno stakeholder ti fornisce una nuova coppia domanda-SQL che vuole supportare o noti un aspetto mancante durante una revisione del codice. Non è necessario configurare un esperimento o eseguire una valutazione per correggerlo: descrivi ciò che 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 il sovraccarico del 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 gli 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 istruire l'agente:

  • "Continuo a scrivere il filtro departure_time BETWEEN '00:00:00' AND '06:00:00' in molte query. Qual è il modo migliore per acquisirlo?"
  • "Gli utenti descrivono lo stato del volo in testo libero e voglio abbinarli a flights.status. Che tipo di ricerca di valore 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 istruire l'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". Leave unrelated items alone."

Passaggi successivi