Crea y optimiza conjuntos de información contextual con el agente de ingeniería de contexto

Para lograr una alta precisión de las consultas de QueryData y una baja latencia en línea en tus aplicaciones de agentes de datos, puedes usar el agente de ingeniería de contexto para compilar, evaluar y optimizar conjuntos de información contextual. Con la automatización de la creación, la carga y la optimización del contexto, el agente ayuda a tus aplicaciones a devolver respuestas rápidas, deterministas y explicables a las preguntas en lenguaje natural.

Para obtener más información sobre los conjuntos de información contextual y QueryData, consulta Descripción general de los conjuntos de información contextual y Descripción general de QueryData.

Si proporcionas QueryData con un contexto adaptado a tu aplicación empresarial, proporcionas las reglas empresariales precisas que el sistema necesita para resolver la intención del usuario con matices y ofrecer una calidad de consulta cercana al 100%. A medida que trabajas en tu CLI o IDE, el agente de ingeniería de contexto sube automáticamente tus conjuntos de contexto a Google Cloud mientras guarda archivos locales en tu espacio de trabajo para el control de versión.

Agente de ingeniería de contexto

El agente de ingeniería de contexto actúa como tu asistente de tiempo de diseño directamente en tu CLI o IDE. La creación manual de contexto requiere escribir patrones de consulta detallados a mano, anticipar cada variación de fraseo y diagnosticar manualmente las fallas de consulta en las iteraciones. El agente de ingeniería de contexto elimina esta sobrecarga, ya que inicia el contexto de referencia, selecciona conjuntos de datos de evaluación de verdad fundamental, realiza una búsqueda de ascenso de colinas iterativa para corregir las brechas de exactitud y demuestra que tu contexto se generaliza en las preguntas nuevas.

Conversas con el agente usando lenguaje natural para impulsar el flujo de trabajo de optimización. Comienza con una instrucción como "Optimiza el conjunto de información contextual según los requisitos de mi aplicación".

Antes de comenzar

Antes de usar el agente de ingeniería de contexto, completa los requisitos previos que se indican en las siguientes secciones. Puedes crear y almacenar conjuntos de contexto en las regiones us-central1, us-east1, europe-west4 y asia-southeast1, incluso si tu instancia de base de datos está en una región diferente.

Habilita los servicios obligatorios

Habilita los siguientes servicios para tu proyecto:

Prepara tu base de datos

Prepara tu instancia de Cloud SQL para MySQL y configura el acceso para el agente:

Roles y permisos requeridos

Para obtener los permisos que necesitas para usar el agente de ingeniería de contexto y administrar conjuntos de contexto, configura los siguientes roles de Identity and Access Management (IAM) y privilegios de base de datos:

  • Agrega un usuario o una cuenta de servicio de IAM a la instancia. Para obtener más información, consulta Agrega un usuario individual o una cuenta de servicio de IAM a una instancia de Cloud SQL.
  • Otorga los roles roles/cloudsql.instanceUser (o roles/cloudsql.studioUser si también pruebas consultas en Cloud SQL Studio), roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser y roles/mcp.toolUser al usuario o a la cuenta de servicio de IAM a nivel del proyecto. Para obtener más información, consulta Agrega una vinculación de política de IAM para un proyecto.
  • Para crear, subir y administrar conjuntos de contexto, otorga el rol de editor de Dataplex Catalog (roles/dataplex.catalogEditor) o de administrador de Dataplex Catalog (roles/dataplex.catalogAdmin) al usuario de IAM o a la cuenta de servicio a nivel del proyecto. Para obtener más información, consulta Permisos de los conjuntos de contexto.

  • Haz que un usuario con privilegios otorgue privilegios de base de datos de solo lectura (y privilegios de ejecución en mysql.ml_embedding si usas búsquedas de valores semánticos) a la cuenta de servicio o al usuario de IAM:

    GRANT SELECT ON *.* TO "IAM_USERNAME";
GRANT EXECUTE ON FUNCTION mysql.ml_embedding TO "IAM_USERNAME";

    Reemplaza IAM_USERNAME por el nombre de usuario de la base de datos del usuario o de la cuenta de servicio de IAM (la dirección de correo electrónico sin el @ ni el nombre de dominio). Para obtener más información, consulta Otorga privilegios de base de datos a un usuario o una cuenta de servicio de IAM individuales.

Prepara la base de datos para las búsquedas de valores

Para usar las búsquedas de valores semánticos y de trigramas, debes configurar tu instancia de Cloud SQL para MySQL para que admita embeddings de vectores y la indexación de n-gramas.

  1. Habilita la API de Vertex AI y la API de Compute Engine, y otorga el rol roles/aiplatform.user a la cuenta de servicio de tu instancia de Cloud SQL para MySQL. Para obtener más información, consulta Habilita la integración de Vertex AI.

  2. Habilita las marcas de base de datos cloudsql_vector y ngram_token_size, y la integración de Vertex AI en tu instancia de Cloud SQL para MySQL:

    gcloud sql instances patch INSTANCE_NAME \
    --enable-google-ml-integration \
    --database-flags=cloudsql_iam_authentication=on,cloudsql_vector=on,ngram_token_size=3

    Reemplaza INSTANCE_NAME por el nombre de tu instancia de Cloud SQL para MySQL.

  3. Para permitir que la instancia de Cloud SQL para MySQL realice búsquedas de valores semánticos, haz lo siguiente:

    1. Crea una columna de vectores para almacenar embeddings (por ejemplo, embeddings de city en la tabla properties):

      ALTER TABLE `properties`
ADD COLUMN `city_embedding` VECTOR(768) USING VARBINARY;

    2. Genera y almacena embeddings de vectores para los valores de la columna:

      UPDATE `properties`
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`)
WHERE `city` IS NOT NULL;

  4. Para permitir que la instancia de Cloud SQL para MySQL realice búsquedas de valores de trigramas, crea un índice FULLTEXT con el analizador ngram en la columna de texto de destino (por ejemplo, address en la tabla properties):

    CREATE FULLTEXT INDEX `idx_ngram_properties_address`
ON `properties`(`address`)
WITH PARSER ngram;

Prepara el entorno

Puedes compilar y optimizar conjuntos de contexto desde tu entorno de desarrollo local o IDE.

Instala uv

El agente de ingeniería de contexto requiere uv para administrar los paquetes de Python subyacentes:

  1. Instala uv siguiendo las instrucciones que se indican en Instala uv.

  2. Verifica que uv esté instalado y que se pueda acceder a él desde la línea de comandos:

    uv --version

Instala el agente de ingeniería de contexto

Instala el complemento del agente de ingeniería de contexto en tu entorno de desarrollo preferido:

CLI de Antigravity

  1. Instala la CLI de Antigravity. Consulta Comienza a usar la CLI de Antigravity.
  2. Instala el complemento del agente de ingeniería de contexto: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Inicia la CLI de Antigravity: 
    agy

Para actualizar el complemento más adelante, ejecuta agy plugin uninstall db-context-engineering seguido de agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.

Claude Code

  1. Agrega el mercado de complementos: 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Instala el complemento: 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Vuelve a cargar los complementos para activar los cambios: 
    /reload-plugins

Para actualizar el complemento más adelante, ejecuta /plugin update db-context-engineering@db-context-enrichment-marketplace.

Gemini CLI (obsoleto)

  1. Instalar la CLI de Gemini Consulta Comienza a usar Gemini CLI.
  2. Instala la extensión: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Para actualizar la extensión más adelante, ejecuta gemini extensions update google-cloud-db-context-engineering.

Autenticar con Google Cloud

  1. Configura las credenciales predeterminadas de la aplicación (ADC) para autenticar tu entorno de desarrollo:

    gcloud auth application-default login

  2. Establece el proyecto de cuota para tus credenciales de modo que las herramientas del Protocolo de contexto del modelo (MCP) puedan usar tu proyecto de Google Cloud :

    gcloud auth application-default set-quota-project PROJECT_ID

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

Conéctate a tu base de datos

  1. Inicia el entorno del agente y pídele que establezca la conexión con la base de datos (por ejemplo, "Ayúdame a configurar la conexión con la base de datos"). El agente te guía para crear el archivo de configuración .context-engineering/tools.yaml, de modo que pueda leer esquemas y validar SQL. (Antes de que se cree .context-engineering/tools.yaml, se espera una advertencia inicial de conexión del servidor de MCP de toolbox al inicio).

  2. Vuelve a cargar la conexión del servidor de MCP para aplicar la configuración de .context-engineering/tools.yaml:

    • CLI de Antigravity: Ejecuta /mcp y selecciona toolbox (o db-context-engineering_toolbox) para reiniciar.
    • Claude Code: Ejecuta /mcp, selecciona toolbox y, luego, Reconnect.
    • Gemini CLI: Ejecuta /mcp refresh (o /mcp reload).

Cómo crear y optimizar el contexto

El agente de ingeniería de contexto guía tu conjunto de contexto a través de un ciclo de vida de extremo a extremo, desde el inicio inicial hasta la generalización verificada.

Cómo iniciar un conjunto de contextos de referencia

Para evitar crear contexto desde una página en blanco, el agente inspecciona el esquema de tu base de datos junto con cualquier artefacto de aplicación disponible, como requisitos empresariales, documentación o consultas en SQL de ejemplo. El agente deriva un conjunto de contexto de referencia inicial que contiene plantillas de consultas fundamentales y facetas de consultas basadas en tu modelo de base de datos.

Después de generar y validar el contexto de referencia, el agente lo sube directamente a Google Cloud y devuelve el nombre del recurso del conjunto de contexto.

Crea conjuntos de datos de evaluación y de exclusión a partir de artefactos de la aplicación

Para mejorar la exactitud de forma sistemática, necesitas preguntas de verdad fundamental vinculadas con consultas en SQL verificadas. Si aún no tienes un benchmark de evaluación, el agente puede generar uno extrayendo situaciones empresariales del código de la aplicación, las consultas históricas y el esquema de la base de datos.

Durante la generación del conjunto de datos, el agente crea dos conjuntos distintos:

  • Comparativa de entrenamiento: Es una colección de pares de preguntas y SQL representativos que se usan durante la optimización iterativa.
  • Conjunto de datos de exclusión: Es un conjunto independiente de preguntas similares en el dominio a tu comparativa de entrenamiento, reservado para probar la generalización.

Optimiza la precisión con el algoritmo de ascenso de colinas

En la optimización de ascenso de colinas, el agente define de forma iterativa tu conjunto de contexto para impulsar la exactitud de QueryData hacia casi el 100%:

  • Evaluar: El agente prueba tu conjunto de contexto actual con el comparativo de entrenamiento usando la API de QueryData y puntúa la exactitud.
  • Diagnostica brechas: El agente analiza las fallas de las consultas, identifica sus causas raíz (como uniones de tablas faltantes, entidades privadas no vinculadas o condiciones de filtro complejas) y formula correcciones específicas.
  • Define mejor y sube: El agente agrega o mejora las plantillas de consultas, las facetas de consultas y las búsquedas de valores para resolver las brechas, y sube automáticamente el conjunto de contexto actualizado a Google Cloud desde tu CLI.
  • Iterar: El agente repite este ciclo en varias rondas hasta que la exactitud converge en la puntuación óptima.

En el siguiente diagrama, se muestra el flujo de trabajo sistemático de ascenso de colinas:

Flujo de trabajo para compilar contexto de forma iterativa.

Demuestra la generalización con el conjunto de datos de exclusión

Es necesario lograr una precisión alta en una comparativa de entrenamiento, pero el tráfico de producción incluye variaciones de frases y preguntas compuestas complejas que nunca se vieron durante el desarrollo.

Después de que converge la optimización de ascenso de colinas, el agente prueba el conjunto de contexto resultante con el conjunto de datos de exclusión. En este paso, se verifica que el contexto establecido se generalice de forma clara a las entradas de usuarios nuevos sin sobreajustarse a la comparación inicial. El agente produce un informe de generalización que muestra la exactitud en las variaciones de preguntas no vistas y los filtros compuestos (como "Encuentra casas cerca de buenas escuelas en Del Mar para una familia que recién empieza, con vista al mar").

Creación y razonamiento on demand

Además de las ejecuciones de optimización completas, puedes conversar con el agente para obtener actualizaciones específicas a medida que evolucionan los requisitos empresariales:

  • Creación de contenido segmentado: Describe un requisito empresarial específico en lenguaje natural, y el agente dará formato al elemento de contexto y lo subirá directamente desde tu CLI sin necesidad de editarlo de forma manual:

    • "Crea una plantilla para: 'Encuentra casas cerca de buenas escuelas en Del Mar' con SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7".
    • "Crea una faceta para el filtro properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 etiquetado como 'para una familia que recién comienza'".
    • "Crea una búsqueda de valor para properties.city".

  • Actualizaciones masivas en un conjunto de contexto: Si se cambia el nombre de las columnas de la base de datos o cambian las estructuras de las tablas, el agente puede actualizar todos los elementos de contexto afectados de forma simultánea sin modificar las entradas no relacionadas:

    • "En mi conjunto de contexto, reemplaza properties.property_type = 'SFR' por properties.property_type = 'Single Family Residential' para cualquier elemento que haga referencia a casas unifamiliares. No modifiques los elementos no relacionados".

¿Qué sigue?