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 los 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 y base de datos de Spanner:

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:

  • Otorga los roles roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser y roles/mcp.toolUser al usuario o a la cuenta de servicio de IAM a nivel del proyecto (u otorga roles/spanner.databaseReader a nivel de la base de datos para las bases de datos requeridas). Para obtener más información, consulta Aplica roles de IAM y 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 a nivel de proyecto. Para obtener más información, consulta Permisos de los conjuntos de contexto.

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?