Compila contextos con Gemini CLI

MySQL   |  PostgreSQL   |  SQL Server

Versión preliminar — Data agents

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicioy las Condiciones Adicionales para Productos en Versión Preliminar de IA Generativa. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para obtener más información sobre el acceso a esta versión, consulta la página de solicitud de acceso.

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

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 Cloud SQL

• Asegúrate de tener acceso a una instancia de Cloud SQL existente o crea una nueva. Para obtener más información, consulta Crea instancias para Cloud SQL.
• Completa la base de datos con los datos y el esquema a los que el usuario final desea acceder.

Roles y permisos requeridos

• Agrega un usuario o una cuenta de servicio de IAM a la instancia. Para obtener más información, consulta Administra usuarios con autenticación de base de datos de IAM para Cloud SQL.
• Otorga los roles cloudsql.studioUser y cloudsql.instanceUser al usuario de IAM a nivel del proyecto. Para obtener más información, consulta Cómo agregar una vinculación de política de IAM a un proyecto.
También debes otorgar privilegios de base de datos a un usuario o una cuenta de servicio de IAM. Para obtener más información, consulta [Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individuales](/sql/docs/postgres/add-manage-iam-users#grant-db-privileges).También debes otorgar privilegios de base de datos a un usuario o una cuenta de servicio de IAM. Para obtener más información, consulta Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individuales.

Otorga permiso de executesql a la instancia de Cloud SQL

Para otorgar el permiso executesql a la instancia de Cloud SQL y habilitar la API de Cloud SQL Data, ejecuta el siguiente comando:

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

Reemplaza INSTANCE_ID por el ID de tu instancia de Cloud SQL.

Prepara el entorno

Puedes compilar archivos de contexto del agente desde cualquier entorno de desarrollo local o IDE. 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 kit de herramientas de MCP 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 MCP Toolbox para Gemini CLI:

   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-cloud-sql-pg-source:
         kind: cloud-sql-postgres
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del proyecto de Google Cloud .
   • REGION_ID: Es la región de tu instancia de Cloud SQL (p.ej., us-central1).
   • INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.
   • DATABASE_ID: El nombre de la base de datos a la que te conectarás.
   • USER_NAME: Es el usuario de la base de datos. Para obtener más información sobre cómo establecer este valor, consulta Fuentes en la caja de herramientas de MCP.
   • PASSWORD: La contraseña del usuario de la base de datos. Para obtener más información sobre cómo establecer este valor, consulta Fuentes en la caja de herramientas de MCP.

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 la 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 preguntas 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 búsqueda, puedes crear un archivo de plantilla nuevo o agregar los pares de búsquedas 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?

• Obtén más información sobre los agentes de datos.
• Obtén información para crear o borrar un agente de datos en Cloud SQL Studio.
• Obtén más información para inspeccionar y llamar a un agente de datos.