Compila contextos con Gemini CLI

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

Para obtener más información sobre los agentes de datos, consulta Descripción general de los agentes de datos.

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

  • Prepara el entorno
  • Genera plantillas segmentadas
  • Genera facetas segmentadas
  • Es opcional. Genera plantillas de forma masiva

Antes de comenzar

Completa los siguientes requisitos previos antes de crear un agente.

Prepara una instancia de Spanner

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

Roles y permisos requeridos

Prepara el entorno

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

  • Instala Gemini CLI
  • Instala y configura la caja de herramientas de MCP
  • Instala y configura el servidor de MCP de enriquecimiento del contexto de la base de datos

Instala Gemini CLI

Para instalar Gemini CLI, consulta Comienza a usar Gemini CLI. Asegúrate de instalar Gemini CLI en un directorio independiente, que también se usa para instalar el MCP toolbox y el servidor de MCP de enriquecimiento del contexto de la base de datos.

Instala y configura la caja de herramientas de MCP

  1. En el mismo directorio en el que instalaste 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 instalaste la caja de herramientas de MCP 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

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INSTANCE_ID: Es el ID de tu instancia de Spanner.
    • DATABASE_ID: El nombre de la base de datos a la que te conectarás.

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

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

Instala el servidor de MCP de enriquecimiento del contexto de la base de datos

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

Para instalar el servidor de MCP de enriquecimiento del contexto de la base de datos, haz lo siguiente:

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

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. Instala el servidor de MCP de enriquecimiento del 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 una variable de entorno. Para obtener más información sobre cómo encontrar tu clave de API, consulta Usa claves de la API de Gemini.

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

export GEMINI_API_KEY="YOUR_API_KEY"

Reemplaza YOUR_API_KEY por tu clave de la API de Gemini.

Genera plantillas segmentadas

Si deseas agregar un par de preguntas específico como plantilla de preguntas al contexto del agente, puedes usar el comando /generate_targeted_templates. Para obtener más información sobre las plantillas, consulta Descripción general de los agentes de datos.

Para agregar una plantilla de consulta al contexto del agente, sigue estos pasos:

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

    gemini

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

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

    /mcp list

  4. Ejecuta el comando /generate_targeted_templates:

    /generate_targeted_templates

  5. Ingresa la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

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

  7. Revisa la plantilla de búsqueda generada. Puedes guardar la plantilla de consulta como un archivo de contexto del agente o agregarla a un archivo de contexto existente.

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

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

Genera facetas segmentadas

Si deseas agregar un par de búsquedas 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 Descripción general de los agentes de datos.

Para agregar una faceta al contexto del agente, sigue estos pasos:

  1. Ejecuta el comando /generate_targeted_fragments:

    /generate_targeted_fragments

  2. Ingresa la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

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

  4. Revisa la faceta generada. Puedes guardar la faceta en un archivo de contexto del agente o agregarla a un archivo de contexto existente.

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

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

Opcional: Genera plantillas de forma masiva

Si deseas 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 masivas, sigue estos pasos:

  1. Ejecuta el comando /generate_bulk_templates:

    /generate_bulk_templates

  2. Según el esquema de tu base de datos, la generación de SQL basada en plantillas te guía a través de una serie de preguntas relacionadas con la verificación de la información de la base de datos y el otorgamiento de permisos para acceder al esquema de la base de datos.

  3. Revisa la plantilla de búsqueda generada. Puedes aprobar la plantilla o actualizar un par de búsquedas que quieras revisar.

  4. Ingresa la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

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

  6. Revisa la plantilla de búsqueda generada. Puedes guardar la plantilla de consulta como un archivo de contexto del agente o agregarla a un archivo de contexto existente.

  7. Después de aprobar la plantilla de consulta, puedes crear un archivo de plantilla nuevo o agregar los pares de consultas a un archivo de plantilla existente. 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 ejecutaste los comandos.

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

¿Qué sigue?