Crea e ottimizza i set di contesti con l'agente di progettazione del contesto

Per ottenere un'elevata accuratezza delle query QueryData e una bassa latenza online nelle tue applicazioni di agenti per i dati, puoi utilizzare l'agente di progettazione del contesto per creare, valutare e ottimizzare i set di contesti. Automatizzando la creazione, il caricamento e l'ottimizzazione del contesto, l'agente aiuta le tue applicazioni a restituire risposte rapide, deterministiche e spiegabili alle domande in linguaggio naturale.

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

Fornendo a QueryData un contesto personalizzato per la tua applicazione aziendale, fornisci le regole aziendali precise di cui il sistema ha bisogno per risolvere l'user intent sfumato e fornire una qualità delle query vicina al 100%. Mentre lavori nella CLI o nell'IDE, l'agente di context engineering carica automaticamente i set di contesto su Google Cloud salvando i file locali nell'area di lavoro per il controllo della versione.

Agente di context engineering

L'agente di context engineering funge da assistente in fase di progettazione direttamente nell'interfaccia a riga di comando o nell'IDE. La creazione manuale del contesto richiede la scrittura manuale di pattern di query dettagliati, l'anticipazione di ogni variazione di fraseggio e la diagnosi manuale degli errori delle query nelle varie iterazioni. L'agente di context engineering elimina questo overhead eseguendo il bootstrap del contesto di base, curando i set di dati di valutazione dei dati di fatto, eseguendo l'hill climbing iterativo per correggere i gap di accuratezza e dimostrando che il contesto si generalizza alle nuove domande.

Puoi conversare con l'agente utilizzando il linguaggio naturale per guidare il flusso di lavoro di ottimizzazione. Inizia con un prompt come "Ottimizza il set di contesti in base ai requisiti della mia applicazione".

Prima di iniziare

Prima di utilizzare l'agente di progettazione del contesto, completa i prerequisiti nelle sezioni seguenti. Puoi creare e archiviare set di contesto nelle regioni us-central1, us-east1, europe-west4 e asia-southeast1, anche se l'istanza del database si trova in una regione diversa.

Attiva i servizi richiesti

Abilita i seguenti servizi per il tuo progetto:

Prepara il database

Prepara l'istanza AlloyDB per PostgreSQL e configura l'accesso per l'agente:

  • Crea un cluster e un'istanza AlloyDB e crea un database oppure utilizza un'istanza e un database esistenti.
  • Abilita l'accesso all'API Data sulla tua istanza AlloyDB. Se utilizzi un IP privato, imposta il campo Accesso API di dati (dataApiAccess) su ENABLED nell'istanza principale in modo che l'agente possa ispezionare gli schemi e convalidare le query. Per le istanze create senza l'accesso all'API di dati abilitato, consulta Abilita l'accesso all'API di dati o configuralo nella console Google Cloud .

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per utilizzare l'agente di context engineering e gestire i set di contesto, configura i seguenti ruoli Identity and Access Management (IAM) e privilegi del database:

  • Aggiungi un utente o account di servizio IAM al cluster. Per saperne di più, consulta Gestisci l'autenticazione IAM.
  • Concedi i ruoli roles/alloydb.databaseUser, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser e roles/mcp.toolUser all'utente o al account di servizio IAM a livello di progetto. Per maggiori informazioni, 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 o al account di servizio a livello di progetto. Per saperne di più, consulta Autorizzazioni per i set di contesti.
  • Se utilizzi ricerche di valori semantici (google_ml.embedding), abilita l'API Vertex AI e concedi il ruolo roles/aiplatform.user al account di servizio del cluster AlloyDB.

  • Concedi i privilegi di database di sola lettura all'utente IAM o al account di servizio accedendo come utente con privilegi di super utente, ad esempio l'utente postgres:

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";

    Sostituisci USER_NAME con l'indirizzo email dell'utente (per un account di servizio, ometti il suffisso .). Se le tue tabelle si trovano in uno schema personalizzato diverso da public, esegui anche GRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME"; e GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";. Per saperne di più, consulta Concedi i privilegi del database agli utenti IAM.

prepara l'ambiente

Puoi creare e ottimizzare i set di contesto dal tuo ambiente di sviluppo locale o IDE.

Installa uv

L'agente di progettazione del contesto 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

Installa l'agente del motore contestuale

Installa il plugin agenti di context engineering nel tuo ambiente di sviluppo preferito:

Antigravity CLI

  1. Installa Antigravity CLI. Consulta la sezione Inizia a utilizzare Antigravity CLI.
  2. Installa il plug-in dell'agente di progettazione 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 in un secondo momento, esegui agy plugin uninstall db-context-engineering seguito da agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.

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

Per aggiornare il plug-in in un secondo momento, esegui /plugin update db-context-engineering@db-context-enrichment-marketplace.

Gemini CLI (deprecato)

  1. Installa Gemini CLI. Consulta Inizia a utilizzare Gemini CLI.
  2. Installa l'estensione: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Per aggiornare l'estensione in un secondo momento, esegui gemini extensions update google-cloud-db-context-engineering.

Autenticati con Google Cloud

  1. Configura le Credenziali predefinite dell'applicazione (ADC) per autenticare l'ambiente di sviluppo:

    gcloud auth application-default login

  2. Imposta il progetto di quota per le tue credenziali in modo che gli strumenti Model Context Protocol (MCP) possano utilizzare il tuo progetto Google Cloud :

    gcloud auth application-default set-quota-project PROJECT_ID

    Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Connetti al tuo database

  1. Avvia l'ambiente dell'agente e chiedigli di stabilire la connessione al database (ad esempio, "Aiutami a configurare la connessione al database"). L'agente ti guida nella creazione del file di configurazione .context-engineering/tools.yaml in modo che possa leggere gli schemi e convalidare l'SQL. (Prima della creazione di .context-engineering/tools.yaml, è previsto un avviso iniziale di connessione al server MCP toolbox all'avvio.)

  2. Ricarica la connessione al server MCP per applicare la configurazione .context-engineering/tools.yaml:

    • Antigravity CLI: esegui /mcp e seleziona toolbox (o db-context-engineering_toolbox) per riavviare.
    • Claude Code: esegui /mcp, seleziona toolbox e seleziona Reconnect.
    • Gemini CLI: esegui /mcp refresh (o /mcp reload).

Crea e ottimizza il contesto

L'agente di context engineering guida il set di contesto attraverso un ciclo di vita end-to-end, dal bootstrap iniziale alla generalizzabilità verificata.

Esegui il bootstrap di un set di contesti di riferimento

Per evitare di creare il contesto da una pagina vuota, l'agente esamina lo schema del database insieme a tutti gli artefatti dell'applicazione disponibili, come requisiti aziendali, documentazione o query SQL di esempio. L'agente ricava un set di contesto di riferimento iniziale contenente modelli di query di base e aspetti delle query basati sul modello del database.

Dopo aver generato e convalidato il contesto di riferimento, l'agente lo carica direttamente su Google Cloud e restituisce il nome della risorsa del set di contesto.

Crea set di dati di valutazione e di holdout dagli artefatti dell'applicazione

Per migliorare sistematicamente l'accuratezza, devi disporre di domande di riferimento accoppiate a query SQL verificate. Se non hai già un benchmark di valutazione, l'agente può generarne uno estraendo scenari aziendali dal codice dell'applicazione, dalle query storiche e dallo schema del database.

Durante la generazione del set di dati, l'agente crea due set distinti:

  • Benchmark di addestramento: una raccolta di coppie domanda-SQL rappresentative utilizzate durante l'ottimizzazione iterativa.
  • Set di dati di controllo: un insieme separato di domande simili per dominio al benchmark di addestramento, riservato ai test di generalizzabilità.

Ottimizza l'accuratezza con l'hill climbing

Nell'ottimizzazione hill-climbing, l'agente perfeziona in modo iterativo il set di contesto per portare l'accuratezza di QueryData verso il 100%:

  • Valutazione: l'agente testa il set di contesti attuale rispetto al benchmark di addestramento utilizzando l'API QueryData e assegna un punteggio all'accuratezza.
  • Diagnostica delle lacune: l'agente analizza gli errori delle query, ne identifica le cause principali (ad esempio join di tabelle mancanti, entità private non collegate o condizioni di filtro complesse) e formula correzioni mirate.
  • Perfeziona e carica: l'agente aggiunge o migliora i modelli di query, i facet delle query e le ricerche di valori per risolvere le lacune e carica automaticamente il set di contesto aggiornato su Google Cloud dalla tua interfaccia a riga di comando.
  • Iterazione: l'agente ripete questo ciclo per più round fino a quando l'accuratezza non converge sul punteggio ottimale.

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

Flusso di lavoro per la creazione iterativa del contesto.

Dimostra la generalizzabilità con il set di dati di holdout

Raggiungere un'elevata accuratezza su un benchmark di addestramento è necessario, ma il traffico di produzione include variazioni di frasi e domande composte complesse che non sono mai state viste durante lo sviluppo.

Una volta che l'ottimizzazione hill climbing converge, l'agente testa il set di contesto risultante rispetto al set di dati di holdout. Questo passaggio verifica che il set di contesto si generalizzi in modo pulito ai nuovi input dell'utente senza overfitting rispetto al benchmark iniziale. L'agente genera un report sulla generalizzabilità che mostra l'accuratezza tra varianti di domande non viste e filtri compositi (ad esempio "Trova case vicino a buone scuole a Del Mar per una famiglia con un bambino e vista sull'oceano").

Creazione e ragionamento on demand

Oltre alle esecuzioni di ottimizzazione complete, puoi conversare con l'agente per aggiornamenti mirati man mano che i requisiti aziendali si evolvono:

  • Targeted authoring: descrivi un requisito aziendale specifico in linguaggio naturale e l'agente formatta l'elemento di contesto e lo carica direttamente dalla tua interfaccia a riga di comando senza modifiche manuali:

    • "Crea un modello per: 'Trova case vicino a buone scuole a Del Mar' con SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7."
    • "Crea un facet per il filtro properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 con l'etichetta 'per una famiglia di principianti'."
    • "Crea una ricerca di valori per properties.city."

  • Aggiornamenti in blocco in un set di contesto: se le colonne del database vengono rinominate o le strutture delle tabelle cambiano, l'agente può aggiornare in blocco contemporaneamente tutti gli elementi di contesto interessati senza modificare le voci non correlate:

    • "Nel mio set di contesto, sostituisci properties.property_type = 'SFR' con properties.property_type = 'Single Family Residential' per qualsiasi elemento che faccia riferimento a case unifamiliari. Leave unrelated items alone."

Passaggi successivi