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 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. Genera modelli collettivi

Prima di iniziare

Completa i seguenti prerequisiti prima di creare un agente.

Prepara un'istanza di Spanner

  • Assicurati che sia disponibile un'istanza Spanner. Per saperne di più, vedi Crea un'istanza.
  • Compila il database con i dati e lo schema a cui l'utente finale vuole accedere.

Ruoli e autorizzazioni richiesti

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 la casella degli strumenti MCP
  • Installa e configura il server MCP di arricchimento del contesto DB

Installare Gemini CLI

Per installare Gemini CLI, vedi Inizia a utilizzare Gemini CLI. Assicurati di installare la CLI Gemini 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-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto Google Cloud .
    • INSTANCE_ID: l'ID dell'istanza Spanner.
    • DATABASE_ID: il nome del database a cui connettersi.

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

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