Crear contextos de compilación con Gemini CLI

En este documento se describe cómo usar la CLI de Gemini y el conjunto de herramientas de MCP para crear archivos de contexto de agente. Estos archivos contienen plantillas y facetas que proporcionan contexto para generar consultas SQL a partir de lenguaje natural. También usarás el servidor MCP de enriquecimiento de contexto de base de datos.

Para obtener información sobre los agentes de datos, consulta el artículo Descripción general de los agentes de datos.

Para crear el contexto del agente, sigue estos pasos generales:

  • Prepara tu entorno
  • Generar plantillas segmentadas
  • Generar facetas segmentadas
  • Opcional. Generar plantillas en bloque

Antes de empezar

Completa los siguientes requisitos previos antes de crear un agente.

Preparar una instancia de Spanner

  • Asegúrate de que haya una instancia de Spanner disponible. Para obtener más información, consulta Crear una instancia.
  • Rellena la base de datos con los datos y el esquema a los que quiera acceder el usuario final.

Roles y permisos necesarios

Prepara tu entorno

Puedes crear archivos de contexto de agente desde cualquier entorno de desarrollo local o IDE. Para preparar el entorno, sigue estos pasos:

  • Instalar Gemini CLI
  • Instalar y configurar la caja de herramientas de MCP
  • Instalar y configurar el servidor MCP de enriquecimiento de contexto de DB

Instalar Gemini CLI

Para instalar Gemini CLI, consulta el artículo Empezar a usar Gemini CLI. Asegúrate de instalar la CLI de Gemini en un directorio independiente, que también se utiliza para instalar el conjunto de herramientas de MCP y el servidor de MCP de enriquecimiento de contexto de base de datos.

Instalar y configurar la caja de herramientas de MCP

  1. En el mismo directorio en el que has instalado Gemini CLI, instala la extensión de Gemini CLI de MCP Toolbox:

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

  2. Crea un archivo de configuración tools.yaml en el mismo directorio en el que hayas instalado MCP Toolbox para configurar la conexión de la base de datos:

      sources:
    my-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

    Haz los cambios siguientes:

    • PROJECT_ID: tu ID de proyecto Google Cloud .
    • INSTANCE_ID: el ID de tu instancia de Spanner.
    • DATABASE_ID: nombre de la base de datos a la que se va a conectar.

  3. Verifica que el archivo tools.yaml esté configurado correctamente:

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

Instalar el servidor de MCP de enriquecimiento de contexto de la base de datos

El servidor MCP de enriquecimiento de contexto de base de datos proporciona un flujo de trabajo interactivo guiado para generar plantillas de NL2SQL estructuradas a partir de los esquemas de tu base de datos. Se basa en la extensión MCP Toolbox para la conectividad de bases de datos. Para obtener más información sobre cómo instalar el servidor MCP de enriquecimiento de contexto de base de datos, consulta Servidor MCP de enriquecimiento de contexto de base de datos.

Para instalar el servidor MCP de enriquecimiento de contexto de DB, sigue estos pasos:

  1. En el mismo directorio en el que has instalado la CLI de Gemini, instala uv, el instalador de paquetes de Python.

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. Instala el servidor de MCP de enriquecimiento de contexto de la base de datos.

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

El servidor usa la API de Gemini para la generación. Asegúrate de exportar tu clave de API como variable de entorno. Para obtener más información sobre cómo encontrar tu clave de API, consulta el artículo Usar claves de API de Gemini.

Para exportar la clave de API de Gemini, ejecuta el siguiente comando:

export GEMINI_API_KEY="YOUR_API_KEY"

Sustituye YOUR_API_KEY por tu clave de API de Gemini.

Generar plantillas segmentadas

Si quieres añadir un par de consultas específico como plantilla de consulta al contexto del agente, puedes usar el comando /generate_targeted_templates. Para obtener más información sobre las plantillas, consulta el artículo Descripción general de los agentes de datos.

Para añadir una plantilla de consulta al contexto del agente, sigue estos pasos:

  1. En el mismo directorio en el que has instalado Gemini CLI, inicia Gemini:

    gemini

  2. Completa la configuración de autenticación de Gemini CLI.

  3. Comprueba que la caja de herramientas de MCP y la extensión de enriquecimiento de bases de datos estén listas para usarse:

    /mcp list

  4. Ejecuta el comando /generate_targeted_templates:

    /generate_targeted_templates

  5. Introduce la consulta en lenguaje natural que quieras añadir a la plantilla de consulta.

  6. Introduce la consulta de SQL correspondiente en la plantilla de consulta.

  7. Revisa la plantilla de consulta generada. Puedes guardar la plantilla de consulta como un archivo de contexto del agente o añadirla a un archivo de contexto ya creado.

El archivo de contexto del agente, similar a my-cluster-psc-primary_postgres_templates_20251104111122.json, se guarda en el directorio en el que has ejecutado los comandos.

Para obtener más información sobre el archivo de contexto y la plantilla de consulta, consulta Contexto del agente.

Generar facetas segmentadas

Si quieres añadir un par de consultas específico como faceta al archivo de contexto del agente, puedes usar el comando /generate_targeted_fragments. Para obtener más información sobre las facetas, consulta el artículo Información general sobre los agentes de datos.

Para añadir un facet al contexto del agente, sigue estos pasos:

  1. Ejecuta el comando /generate_targeted_fragments:

    /generate_targeted_fragments

  2. Introduce la consulta en lenguaje natural que quieras añadir a la plantilla de consulta.

  3. Introduce la consulta de SQL correspondiente en la plantilla de consulta.

  4. Revisa la faceta generada. Puedes guardar la faceta en un archivo de contexto de agente o añadirla a un archivo de contexto ya creado.

El archivo de contexto del agente, similar a my-cluster-psc-primary_postgres_templates_20251104111122.json, se guarda en el directorio en el que has ejecutado los comandos.

Para obtener más información sobre el archivo de contexto y las facetas, consulta Contexto del agente.

Opcional: Generar plantillas en bloque

Si quieres generar automáticamente el archivo de contexto del agente en función del esquema y los datos de tu base de datos, puedes usar el comando /generate_bulk_templates.

Para generar automáticamente plantillas en bloque, sigue estos pasos:

  1. Ejecuta el comando /generate_bulk_templates:

    /generate_bulk_templates

  2. En función del esquema de tu base de datos, la generación de SQL basada en plantillas te guiará por una serie de preguntas relacionadas con la verificación de la información de la base de datos y la concesión de permisos para acceder al esquema de la base de datos.

  3. Revisa la plantilla de consulta generada. Puedes aprobar la plantilla o actualizar un par de consultas que quieras revisar.

  4. Introduce la consulta en lenguaje natural que quieras añadir a la plantilla de consulta.

  5. Introduce la consulta de SQL correspondiente en la plantilla de consulta.

  6. Revisa la plantilla de consulta generada. Puedes guardar la plantilla de consulta como un archivo de contexto del agente o añadirla a un archivo de contexto ya creado.

  7. Una vez que haya aprobado la plantilla de consulta, puede crear un archivo de plantilla o añadir los pares de consultas a un archivo de plantilla que ya tenga. La plantilla de consulta se guarda como un archivo JSON en tu directorio local.

El archivo de contexto del agente, similar a my-cluster-psc-primary_postgres_templates_20251104111122.json, se guarda en el directorio en el que has ejecutado los comandos.

Para obtener más información sobre el archivo de contexto del agente, consulta el artículo Contexto del agente.

Siguientes pasos