Creare contesti utilizzando Gemini CLI

MySQL   |  PostgreSQL   |  SQL Server

Anteprima : agenti di dati

Queste funzionalità sono soggette ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specifici e 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 della fase di lancio.

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

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

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

Per creare un file di contesto dell'agente, svolgi i seguenti passaggi di alto livello:

• prepara l'ambiente
• genera modelli mirati
• genera aspetti mirati
• (Facoltativo) Genera modelli collettivi Genera modelli collettivi

Prima di iniziare

Completa i seguenti prerequisiti prima di creare un agente.

Abilita i servizi richiesti

Abilita i seguenti servizi per il tuo progetto:

• API Gemini Data Analytics
• API Gemini for Google Cloud

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.
• Assicurati di creare un database nell'istanza in cui creerai le tabelle. Per saperne di più, consulta Crea un database sull' istanza Cloud SQL.

Ruoli e autorizzazioni richiesti

• Aggiungi un utente IAM o un account di servizio a livello di istanza. Per saperne di più, consulta Aggiungi un'associazione di policy IAM a un utente, account di servizio o un gruppo.
• Concedi i ruoli cloudsql.studioUser e cloudsql.instanceUser all'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi un'associazione di policy IAM per un progetto.
• Devi anche concedere i privilegi del database a un utente IAM o a un account di servizio accedendo come utente del database basato su password.
  
  GRANT ALL PRIVILEGES ON * TO "IAM_USERNAME";.
  
  Per saperne di più, consulta Concedi i privilegi del 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 dati Cloud SQL, esegui questo comando:

gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

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

Per eseguire i passaggi di questo tutorial, accedi a Google Cloud e poi autenticati al database utilizzando l'autenticazione IAM.

prepara l'ambiente

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

• Installa Gemini CLI
• Installa e configura MCP Toolbox
• Installa e configura il server MCP di arricchimento del contesto del database

Installa Gemini CLI

Per installare Gemini CLI, consulta la pagina Introduzione a Gemini CLI. Assicurati di installare Gemini CLI in una directory separata, utilizzata anche per installare MCP Toolbox e il server MCP di arricchimento del contesto del database.

Installa e configura MCP Toolbox

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 MCP Toolbox 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' Google Cloud ID progetto.
   • REGION_ID: la regione dell'istanza Cloud SQL, ad esempio 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 la sezione Origini in MCP Toolbox.
   • PASSWORD: la password dell'utente del database. Per saperne di più su come impostare questo valore, consulta la sezione Origini in MCP Toolbox.

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

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

Installa il server MCP di arricchimento del contesto del database

Il server MCP di arricchimento del contesto del database fornisce un flusso di lavoro guidato e interattivo per generare modelli NL2SQL strutturati dagli schemi di database. Si basa sull'estensione MCP Toolbox per la connettività del database. Per saperne di più sull'installazione del server MCP di arricchimento del contesto del database, consulta la sezione Server MCP di arricchimento del contesto del database.

Per installare il server MCP di arricchimento del contesto del database:

1. Nella stessa directory in cui hai installato Gemini CLI, installa il programma di installazione dei pacchetti Python uv utilizzando pip.

   pip install uv

   Se pip non è installato, installalo prima.

2. Installa il server MCP di 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 la sezione Utilizzo delle chiavi API Gemini.

Esporta la chiave API Gemini:

export GEMINI_API_KEY="YOUR_API_KEY"

Sostituisci YOUR_API_KEY con la tua chiave API Gemini.

Genera 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:

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

   gemini

2. Completa la configurazione dell'autenticazione di Gemini CLI.

3. Verifica che MCP Toolbox e l'estensione di arricchimento del database siano pronti per l'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, consulta la sezione Contesto dell'agente.

Genera aspetti mirati

Se vuoi aggiungere una coppia di query specifica come aspetto al file di contesto dell'agente, puoi utilizzare il comando /generate_targeted_facets. Per saperne di più sugli aspetti, consulta la panoramica degli agenti di dati.

Per aggiungere un aspetto al contesto dell'agente:

1. Esegui il comando /generate_targeted_facets:

   /generate_targeted_facets

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 l'aspetto generato. Puoi salvare l'aspetto in un 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 sugli aspetti, consulta la sezione 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 i 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 di modello o aggiungere le coppie di query a un file di 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, consulta la sezione Contesto dell'agente.

Passaggi successivi

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