Creare contesti utilizzando Gemini CLI

MySQL   |  PostgreSQL   |  SQL Server

Anteprima — Data agents

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specificie ai Termini aggiuntivi per i prodotti in anteprima dell'AI generativa. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Per informazioni sull'accesso a questa versione, consulta la pagina di richiesta di accesso.

Questo documento descrive come utilizzare la CLI Gemini e la casella degli strumenti MCP per creare file di contesto dell'agente. Questi file contengono modelli e sfaccettature che forniscono il contesto per la generazione di query SQL dal linguaggio naturale. Utilizzerai anche il server MCP per l'arricchimento del contesto DB.

Per scoprire di più sugli agenti dati, consulta Panoramica degli agenti dati.

Per creare il contesto dell'agente, segui questi passaggi di alto livello:

• prepara l'ambiente
• Generare modelli mirati
• Generare sfaccettature mirate
• Facoltativo. Generare modelli collettivi

Prima di iniziare

Completa i seguenti prerequisiti prima di creare un agente.

Prepara un'istanza Cloud SQL

• Assicurati di avere accesso a un'istanza Cloud SQL esistente o creane una nuova. Per saperne di più, consulta Crea istanze per Cloud SQL.
• Popola il database con i dati e lo schema a cui l'utente finale vuole accedere.

Ruoli e autorizzazioni richiesti

• Aggiungi un utente IAM o un account di servizio al cluster a livello di istanza. Per maggiori informazioni, consulta Gestire gli utenti con l'autenticazione IAM dei database.
• Concedi i ruoli cloudsql.studioUser e cloudsql.instanceUser all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungere l'associazione di policy IAM per un progetto.
Devi inoltre concedere i privilegi del database a un utente IAM o a un account di servizio. Per maggiori informazioni, vedi Concedere privilegi di database a un singolo utente IAM o service account.

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 beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

Sostituisci INSTANCE_ID con l'ID dell'istanza Cloud SQL.

prepara l'ambiente

Puoi creare file di contesto dell'agente da qualsiasi ambiente di sviluppo locale o IDE. Per preparare l'ambiente, segui questi passaggi:

• Installare Gemini CLI
• Installare e configurare il toolbox MCP
• Installa e configura il server MCP per l'arricchimento del contesto DB

Installare Gemini CLI

Per installare Gemini CLI, vedi Inizia a utilizzare Gemini CLI. Assicurati di installare Gemini CLI in una directory separata, utilizzata anche per installare il toolkit MCP e il server MCP di arricchimento del contesto del database.

Installare e configurare il toolbox MCP

1. Nella stessa directory in cui hai installato Gemini CLI, installa l'estensione Gemini CLI di MCP Toolbox:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. Crea un file di configurazione tools.yaml nella stessa directory in cui hai installato la toolbox MCP per configurare la connessione al database:

     sources:
       my-cloud-sql-mysql-source:
         kind: cloud-sql-mysql
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto Google Cloud .
   • REGION_ID: la regione dell'istanza Cloud SQL (ad es. us-central1).
   • INSTANCE_ID: l'ID dell'istanza Cloud SQL.
   • DATABASE_ID: il nome del database a cui connettersi.
   • USER_NAME: l'utente del database. Per saperne di più su come impostare questo valore, consulta Fonti nella casella degli strumenti MCP.
   • PASSWORD: la password dell'utente del database. Per saperne di più su come impostare questo valore, consulta Fonti nella casella degli strumenti MCP.

3. Verifica che il file tools.yaml sia configurato correttamente:

   ./toolbox --tools-file "tools.yaml"

Installa il server MCP per l'arricchimento del contesto DB

Il server MCP di arricchimento del contesto del database fornisce un flusso di lavoro guidato e interattivo per generare modelli NL2SQL strutturati dagli schemi del database. Si basa sull'estensione MCP Toolbox per la connettività del database. Per ulteriori informazioni sull'installazione del server MCP per l'arricchimento del contesto DB, vedi Server MCP per l'arricchimento del contesto DB.

Per installare il server MCP di arricchimento del contesto DB:

1. Nella stessa directory in cui hai installato Gemini CLI, installa il programma di installazione del pacchetto Python uv.

     pip install --user pipx
     pipx ensurepath
     pipx install uv

2. Installa il server MCP per l'arricchimento del contesto del database.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Il server utilizza l'API Gemini per la generazione. Assicurati di esportare la chiave API come variabile di ambiente. Per saperne di più su come trovare la chiave API, consulta Utilizzo delle chiavi API Gemini.

Per esportare la chiave API Gemini, esegui questo comando:

export GEMINI_API_KEY="YOUR_API_KEY"

Sostituisci YOUR_API_KEY con la tua chiave API Gemini.

Generare modelli mirati

Se vuoi aggiungere una coppia di query specifica come modello di query al contesto dell'agente, puoi utilizzare il comando /generate_targeted_templates. Per saperne di più sui modelli, consulta la panoramica degli agenti di dati.

Per aggiungere un modello di query al contesto dell'agente, segui questi passaggi:

1. Nella stessa directory in cui hai installato Gemini CLI, avvia Gemini:

   gemini

2. Completa la configurazione dell'autenticazione Gemini CLI.

3. Verifica che la casella degli strumenti MCP e l'estensione per l'arricchimento del database siano pronte all'uso:

   /mcp list

4. Esegui il comando /generate_targeted_templates:

   /generate_targeted_templates

5. Inserisci la query in linguaggio naturale che vuoi aggiungere al modello di query.

6. Inserisci la query SQL corrispondente nel modello di query.

7. Esamina il modello di query generato. Puoi salvare il modello di query come file di contesto dell'agente o aggiungerlo a un file di contesto esistente.

Il file di contesto dell'agente simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sul file di contesto e sul modello di query, vedi Contesto dell'agente.

Generare sfaccettature mirate

Se vuoi aggiungere una coppia di query specifica come sfaccettatura al file di contesto dell'agente, puoi utilizzare il comando /generate_targeted_fragments. Per ulteriori informazioni sui facet, consulta la panoramica degli agenti di dati.

Per aggiungere un aspetto al contesto dell'agente:

1. Esegui il comando /generate_targeted_fragments:

   /generate_targeted_fragments

2. Inserisci la query in linguaggio naturale che vuoi aggiungere al modello di query.

3. Inserisci la query SQL corrispondente nel modello di query.

4. Esamina la sfaccettatura generata. Puoi salvare la sfaccettatura in un file di contesto dell'agente o aggiungerla a un file di contesto esistente.

Il file di contesto dell'agente simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sul file di contesto e sulle sfaccettature, vedi Contesto dell'agente.

(Facoltativo) Genera modelli collettivi

Se vuoi generare automaticamente il file di contesto dell'agente in base allo schema e ai dati del database, puoi utilizzare il comando /generate_bulk_templates.

Per generare automaticamente modelli collettivi:

1. Esegui il comando /generate_bulk_templates:

   /generate_bulk_templates

2. In base allo schema del database, la generazione di SQL basata su modelli ti guida attraverso una serie di domande relative alla verifica delle informazioni del database e alla concessione delle autorizzazioni per accedere allo schema del database.

3. Esamina il modello di query generato. Puoi approvare il modello o aggiornare una coppia di query che vuoi rivedere.

4. Inserisci la query in linguaggio naturale che vuoi aggiungere al modello di query.

5. Inserisci la query SQL corrispondente nel modello di query.

6. Esamina il modello di query generato. Puoi salvare il modello di query come file di contesto dell'agente o aggiungerlo a un file di contesto esistente.

7. Dopo aver approvato il modello di query, puoi creare un nuovo file modello o aggiungere le coppie di query a un file modello esistente. Il modello di query viene salvato come file JSON nella directory locale.

Il file di contesto dell'agente simile a my-cluster-psc-primary_postgres_templates_20251104111122.json viene salvato nella directory in cui hai eseguito i comandi.

Per saperne di più sul file di contesto dell'agente, vedi Contesto dell'agente.

Passaggi successivi

• Scopri di più sugli agenti di dati.
• Scopri come creare o eliminare un agente dati in Cloud SQL Studio.
• Scopri come ispezionare e chiamare un agente dati.