Crea conjuntos de contexto con el agente de ingeniería de contexto

En este documento, se describe cómo crear y optimizar los conjuntos de contextos que ayudan a lograr una alta precisión de las consultas de QueryData en tus aplicaciones de agentes de datos. El agente de ingeniería de contexto te ayuda a compilar, evaluar y mejorar los conjuntos de contextos mediante la automatización de su creación y optimización.

Para obtener información sobre los conjuntos de contextos y QueryData, consulta Descripción general de los conjuntos de contextos y Descripción general de QueryData.

Para compilar aplicaciones de datos de nivel empresarial, la precisión del modelo de texto a SQL suele alcanzar una calidad cercana al 100%. Los resultados de consultas incorrectos afectan la usabilidad general de la aplicación y la experiencia del usuario. Para obtener respuestas explicables y relevantes para la empresa con alta precisión, se requiere ingeniería de contexto, que es el proceso de crear y optimizar de forma iterativa el contexto para lograr una precisión óptima.

Cuando proporcionas a QueryData el contexto segmentado para tu aplicación empresarial, le proporcionas las reglas comerciales precisas que el sistema necesita para resolver la intención matizada del usuario.

Agente de ingeniería de contexto

El agente de ingeniería de contexto automatiza este flujo de trabajo de optimización. Puedes conversar con el agente para controlar tareas ad hoc y optimizar tu contexto. En la siguiente lista, se proporcionan ejemplos de instrucciones en lenguaje natural que puedes usar para indicarle al agente qué hacer, junto con una descripción de cómo responde el agente. Usa estos ejemplos para compilar y optimizar tu contexto:

  • Ejemplo de instrucción para el análisis de fallas: "Update context so that we correctly identify the airport for queries like 'disney world flights'." El agente analiza la falla, razona sobre la brecha y recomienda agregar un elemento de contexto adecuado, como una consulta de búsqueda de valores.
  • Ejemplo de instrucción para sugerencias de contexto: "Read my app code and suggest some context to add." El agente analiza el código, razona sobre el dominio de tu aplicación y sugiere qué elementos de contexto serían relevantes.
  • Ejemplo de instrucción para el procesamiento masivo: "Here are 10 examples of questions and SQL queries. Turn them into templates." El agente procesa de forma masiva tus entradas y actualiza tu conjunto de contextos.

Importancia del conjunto de datos de referencia

Para optimizar tu contexto, primero debes crear un conjunto de datos que coincida con las entradas en lenguaje natural de tu aplicación. El agente puede ayudarte a compilar este conjunto de datos de referencia, que consta de preguntas de los usuarios y sus consultas de bases de datos esperadas. Un conjunto de datos de referencia te permite hacer lo siguiente:

  • Establecer una base de referencia para el rendimiento de las consultas
  • Validar las actualizaciones en función de las consultas de bases de datos de verdad fundamental
  • Medir las mejoras de precisión en las iteraciones

El proceso sistemático de ascenso de colinas

En el ascenso sistemático de colinas, el agente mejora de forma iterativa un conjunto de contextos mediante la evaluación del conjunto de datos de referencia, el análisis de brechas y las actualizaciones para impulsar la precisión hacia un valor cercano al 100%.

  • Generar automáticamente el contexto de referencia: Crea un conjunto de contextos inicial derivado del esquema de tu base de datos y los artefactos de la aplicación.
  • Flujo de trabajo de optimización de ascenso de colinas: Permite que el agente evalúe la precisión de QueryData, realice un análisis de brechas en las fallas y proponga automáticamente mejoras para aumentar la precisión.

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

Flujo de trabajo para crear contexto de forma iterativa.

Antes de comenzar

Completa los siguientes requisitos previos antes de usar el agente de ingeniería de contexto.

Habilita los servicios obligatorios

Habilita los siguientes servicios para tu proyecto:

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.

En este instructivo, se requiere que tengas una base de datos en tu instancia de Cloud SQL. Para obtener más información, consulta Crea una base de datos en la instancia de Cloud SQL.

Roles y permisos requeridos

Otorga el permiso 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 config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Reemplaza lo siguiente:
  • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
  • INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.
Para realizar los pasos de este instructivo, accede a Google Cloud y, luego, autentícate en la base de datos con la autenticación de IAM.

Prepara el entorno

Puedes compilar archivos de conjuntos de contextos desde cualquier entorno de desarrollo local o IDE. Para preparar tu entorno, completa los siguientes pasos:

  • Instala el agente de ingeniería de contexto
  • Configura la conexión de la base de datos

Instala el agente de ingeniería de contexto

El agente de ingeniería de contexto ejecuta el servidor del Protocolo de contexto del modelo (MCP) que requiere uv para administrar los paquetes de Python subyacentes.

  1. Para instalar uv, sigue 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

Para preparar tu entorno, instala el agente de ingeniería de contexto en el arnés de agente seleccionado, como la CLI de Antigravity, Claude Code o la CLI de Gemini.

Según el arnés de agente seleccionado, sigue los pasos de instalación correspondientes:

CLI de Antigravity

Para instalar el agente de ingeniería de contexto en la CLI de Antigravity, sigue estos pasos:

  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, que incluye flujos de trabajo para la generación de contexto. Reemplaza VERSION por la versión publicada requerida: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Inicia la CLI de Antigravity: 
    agy
  4. Es opcional. Actualiza el complemento: 
    agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION

Claude Code

Para instalar el agente de ingeniería de contexto en Claude Code, sigue estos pasos:

  1. Agrega el marketplace 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
  4. Es opcional. Actualiza el complemento: 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

CLI de Gemini (obsoleta)

Para instalar el agente de ingeniería de contexto en la CLI de Gemini, sigue estos pasos:

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

Configura la conexión de la base de datos

El agente requiere una conexión de base de datos para obtener esquemas y la capacidad de validar la sintaxis del contexto de SQL generado. Para permitir que el agente interactúe con tu base de datos, configura las credenciales de autenticación y define la configuración de la conexión de la base de datos.

Configura las credenciales predeterminadas de la aplicación

Configura las credenciales predeterminadas de la aplicación (ADC) para proporcionar credenciales de usuario para acceder a Google Cloud recursos desde el agente de ingeniería de contexto:

  • Servidor de MCP de Toolbox: Usa credenciales para conectarse a tu base de datos, obtener esquemas y ejecutar SQL para la validación.
  • Evalbench: Usa credenciales para invocar QueryData para la evaluación.

Ejecuta los siguientes comandos en tu terminal para autenticarte:

gcloud auth application-default login

Configura el archivo de conexión de la base de datos

El agente requiere una conexión de base de datos para la generación de contexto, que el MCP Toolbox admite y define dentro de un archivo de configuración.

El archivo de configuración especifica la fuente de tu base de datos y las herramientas necesarias para obtener esquemas o ejecutar SQL. El agente de ingeniería de contexto incluye habilidades de agente preinstaladas para ayudarte a generar la configuración.

  1. Inicia tu entorno de agente.

  2. Pídele al agente que te ayude a configurar la conexión de la base de datos. Por ejemplo, ingresa la instrucción "help me set up the database connection". Sigue las instrucciones del agente para crear el archivo de configuración en tu directorio de trabajo actual como autoctx/tools.yaml.

  3. Para aplicar la nueva configuración de tools.yaml, vuelve a cargar tu conexión:

    • En la CLI de Antigravity, ejecuta /mcp y selecciona toolbox para reiniciar.
    • En la CLI de Gemini, ejecuta /mcp reload.
    • En Claude Code, ejecuta /mcp, selecciona toolbox y, luego, Reconnect.

Para obtener más información sobre cómo configurar manualmente el archivo de configuración de la base de datos, consulta Configuración de MCP Toolbox.

Genera y optimiza el contexto

El agente de ingeniería de contexto proporciona un conjunto de habilidades de agente y herramientas de MCP para mejorar la capacidad de ingeniería de contexto de tu agente de codificación. Puedes usar estas herramientas en conjunto para generar una base de referencia, medir la eficacia y aplicar mejoras de forma iterativa. Sin embargo, puedes comenzar en cualquier etapa del flujo de trabajo:

  • Si ya tienes un conjunto de contextos, puedes continuar directamente con la evaluación.
  • Si tienes consultas con errores que deseas corregir, puedes continuar directamente con el análisis de brechas.

Cada capacidad describe las acciones, los casos de uso y los comandos de invocación del agente.

Las instrucciones de ejemplo muestran cómo puedes consultar al agente en lenguaje natural. Si el agente requiere detalles adicionales para completar una solicitud, te pedirá una aclaración.

Compila y expande conjuntos de datos de evaluación

Para mejorar el rendimiento, primero debes medirlo. La ingeniería de contexto sin un conjunto de datos de referencia, que consta de preguntas de los usuarios combinadas con su SQL esperado, carece de verificación sistemática. Con un conjunto de datos de referencia, cada cambio es una mejora medible que puedes validar en función de la verdad fundamental.

Crear un conjunto de datos de referencia representativo de forma manual lleva mucho tiempo, y los conjuntos de datos pequeños podrían no incluir variaciones en la fraseología del usuario. El agente resuelve esto de la siguiente manera:

  • Genera pares de pregunta y SQL candidatos en función del esquema de tu base de datos.
  • Expande un pequeño conjunto de datos inicial con variaciones de filtros, sinónimos y reformulaciones.

De manera opcional, puedes permitir que el agente ejecute el SQL generado en tu base de datos. Esta verificación confirma que las consultas se ejecutan correctamente antes de agregarlas al conjunto de datos.

El conjunto de datos es un archivo JSON que contiene pares de pregunta y SQL:

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

Los pares aprobados propagan el archivo autoctx/golden.json en tu espacio de trabajo, donde están listos para la evaluación. Puedes proporcionar un archivo existente o escribir algunos ejemplos de evaluación intercalados para que el agente los expanda.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "Generate an evaluation dataset from my schema."
  • "Here's a seed question and SQL—expand it into a broader dataset and verify the queries run."

Genera un conjunto de contextos de referencia

Para evitar crear contexto desde cero, puedes permitir que el agente derive un conjunto de contextos inicial del esquema de tu base de datos y los artefactos de la aplicación, como reglas comerciales, consultas de muestra o archivos README. Si bien este contexto de referencia no es definitivo, proporciona un punto de partida validado basado en tu modelo de base de datos.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "Generate a context set from my schema."
  • "Generate initial context using these schemas and the business rules in requirements.md."

El agente te pedirá que le des un nombre al experimento, que organiza los artefactos generados, y podría pedirte que acotes el alcance si el esquema de tu base de datos es grande. Para subir el contexto con Cloud SQL Studio, sigue las instrucciones después de que el agente genere el archivo JSON.

Evalúa la eficacia del contexto

Después de establecer un conjunto de contextos y un conjunto de datos de referencia, puedes permitir que el agente mida el rendimiento del contexto consultando la API de QueryData de tu agente de datos con cada pregunta de referencia. El agente compara el SQL generado y sus resultados de ejecución con la respuesta esperada mediante Evalbench para controlar la comparación.

La ejecución de una evaluación proporciona lo siguiente:

  • Métricas cuantitativas, como resultados de aprobación y reprobación, y puntuaciones agregadas, para hacer un seguimiento del progreso en las iteraciones de contexto
  • Un resumen de conversación intercalado y informes CSV detallados escritos en el directorio eval_reports/ de tu carpeta de experimento

Para iniciar una evaluación, proporciona la ruta de acceso del conjunto de datos de referencia y el ID del conjunto de contextos. Para obtener información sobre cómo encontrar el ID del conjunto de contextos, consulta Encuentra el ID del contexto del agente.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "Evaluate my context against golden.json."
  • "Re-run the evaluation using the config from my last experiment."

Para volver a ejecutar una configuración de evaluación generada anteriormente sin volver a configurarla, pídele al agente que lo haga o invoca la CLI directamente:

uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

Para obtener detalles sobre el esquema de configuración de la evaluación y cómo personalizar las ejecuciones de evaluación, consulta la documentación de Evalbench.

Realiza un análisis de brechas y propone mejoras

Para resolver las fallas de las consultas, debes identificar sus causas raíz, como columnas incorrectas, uniones de tablas faltantes o términos difusos no resueltos. La identificación manual de estos problemas requiere un análisis exhaustivo de los informes de evaluación.

El agente automatiza este bucle de análisis y corrección:

  • Análisis de brechas: El agente lee los resultados de la evaluación y tu conjunto de contextos para agrupar fallas similares y recomendar adiciones de contexto segmentadas, como plantillas, facetas o búsquedas de valores.
  • Correcciones propuestas: El agente propone ediciones concretas y, de manera opcional, prueba el SQL en tu base de datos para verificar la resolución.
  • Conservación de la base de referencia: El agente escribe las mejoras en un archivo JSON nuevo junto con tu contexto de referencia, lo que conserva los archivos originales.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "Run gap analysis on my last evaluation and propose fixes."
  • "Optimize this context set against golden.json."

Para prepararte para la próxima iteración, sube el contexto mejorado al conjunto de contextos de destino con Data Agents Studio y sigue las instrucciones.

Crea elementos de contexto específicos a pedido

Si ya conoces el contexto requerido, como una plantilla para una pregunta específica, una faceta para un filtro repetido o una búsqueda de valores para una columna en particular, escribir el JSON de contexto de forma manual puede introducir errores de serialización en los nombres de los parámetros, los metadatos de tipo o la sintaxis de fragmentos. El agente controla el formato JSON para que puedas enfocarte en tu intención comercial.

También puedes usar esta función para actualizaciones ad hoc, como cuando necesitas admitir un nuevo patrón de consulta o abordar un detalle de esquema faltante. Para obtener el JSON, describe el contexto requerido al agente sin ejecutar una evaluación ni configurar un experimento.

Esta también es la capacidad adecuada para usar cuando se te asigna una tarea única: un interesado te da un nuevo par de pregunta y SQL que quiere que se admita, o bien detectas una faceta faltante durante una revisión de código. No es necesario que configures un experimento ni ejecutes una evaluación para corregirlo. Describe lo que quieres y el agente producirá el JSON.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "Create a template for: 'Which airports are in California?' with SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Create a facet for the filter departure_time BETWEEN '00:00:00' AND '06:00:00' labeled 'red eye'."
  • "Create a value search for airports.iata."

Razona sobre la selección del tipo de contexto

Seleccionar el tipo de contexto correcto, independientemente de si se trata de una plantilla, una faceta o una búsqueda de valores, ayuda a evitar el aumento del contexto y las regresiones de consultas de bases de datos. Por ejemplo, usar una plantilla en lugar de una faceta puede provocar reglas duplicadas, mientras que las búsquedas de valores introducidas cuando una plantilla es suficiente pueden aumentar la latencia de las consultas. Para encontrar el formato de esquema correcto, pídele al agente que recomiende un tipo en función de la estructura de la consulta o las columnas de la base de datos antes de crear elementos de contexto. El agente explica su razonamiento para ayudarte a comprender las opciones de contexto.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "I keep writing the filter departure_time BETWEEN '00:00:00' AND '06:00:00' across many queries. What's the best way to capture this?"
  • "Users describe flight status in free text and I want to match them to flights.status. What kind of value search should I set up?"
  • "What's the difference between a template and a facet, and when should I use each?"

Aplica operaciones masivas en un conjunto de contextos

El agente admite actualizaciones masivas para administrar grandes conjuntos de contextos de manera coherente. Si necesitas actualizar varios elementos de contexto de forma simultánea, como cuando se cambia el nombre de una columna de la base de datos, un valor de código cambia de formato o las plantillas hacen referencia a una tabla obsoleta, el agente puede aplicar el cambio en cada elemento afectado sin alterar las entradas no relacionadas.

Puedes usar las siguientes instrucciones de ejemplo para indicarle al agente qué hacer:

  • "Read golden.txt and turn all the pairs into templates."
  • "In context_set.json, replace airline = 'UA' with airline = 'United Airlines' for any item referencing 'United'. Leave unrelated items alone."

¿Qué sigue?