Creare contesti utilizzando Gemini CLI

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 di arricchimento del contesto DB.

Per creare un file di contesto dell'agente, esegui i seguenti 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.

Attivare i servizi richiesti

• 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 Creare un database sull'istanza Cloud SQL.

Ruoli e autorizzazioni richiesti

• Aggiungi un utente IAM o un service account a livello di istanza. Per saperne di più, vedi Aggiungere un binding di policy IAM a un utente, un service account o un gruppo.
• 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 service account accedendo come utente basato su password del database.
  
  GRANT ALL PRIVILEGES ON * TO "IAM_USERNAME";.
  
  Per maggiori informazioni, consulta Concedere privilegi di database a un singolo utente IAM o service account.

Concedi l'autorizzazione executesql all'istanza Cloud SQL

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

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 la casella degli strumenti 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 Cloud de Confiance .
   • 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 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.

   curl -LsSf https://astral.sh/uv/install.sh | sh

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

   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.

Esporta la chiave API Gemini:

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