Créer et optimiser des ensembles de contextes avec l'agent d'ingénierie contextuelle

Pour obtenir une précision élevée des requêtes QueryData et une faible latence en ligne dans vos applications d'agent de données, vous pouvez utiliser l'agent d'ingénierie contextuelle pour créer, évaluer et optimiser des ensembles de contexte. En automatisant la création, l'importation et l'optimisation du contexte, l'agent aide vos applications à renvoyer des réponses rapides, déterministes et explicables aux questions en langage naturel.

Pour en savoir plus sur les ensembles de contextes et QueryData, consultez Présentation des ensembles de contextes et Présentation de QueryData.

En fournissant à QueryData un contexte adapté à votre application métier, vous fournissez les règles métier précises dont le système a besoin pour résoudre l'intention utilisateur nuancée et fournir une qualité de requête proche de 100 %. Lorsque vous travaillez dans votre CLI ou votre IDE, l'agent d'ingénierie de contexte importe automatiquement vos ensembles de contexte dans Google Cloud tout en enregistrant les fichiers locaux dans votre espace de travail pour le contrôle des versions.

Agent de context engineering

L'agent d'ingénierie de contexte agit comme votre assistant au moment de la conception, directement dans votre CLI ou votre IDE. La création manuelle de contexte nécessite d'écrire manuellement des schémas de requête détaillés, d'anticiper chaque variation de formulation et de diagnostiquer manuellement les échecs de requête au fil des itérations. L'agent d'ingénierie de contexte élimine cette surcharge en amorçant le contexte de référence, en organisant des ensembles de données d'évaluation de vérité terrain, en effectuant une recherche locale itérative pour corriger les écarts de précision et en prouvant que votre contexte se généralise à de nouvelles questions.

Vous conversez avec l'agent en langage naturel pour piloter le workflow d'optimisation. Commencez par un prompt tel que "Optimise l'ensemble de contextes en fonction des exigences de mon application".

Avant de commencer

Avant d'utiliser l'agent d'ingénierie de contexte, remplissez les conditions préalables décrites dans les sections suivantes. Vous pouvez créer et stocker des ensembles de contexte dans les régions us-central1, us-east1, europe-west4 et asia-southeast1, même si votre instance de base de données se trouve dans une autre région.

Activer les services requis

Activez les services suivants pour votre projet :

Préparer votre base de données

Préparez votre instance et votre base de données Spanner :

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour utiliser l'agent d'ingénierie de contexte et gérer les ensembles de contextes, configurez les rôles IAM (Identity and Access Management) et les droits de base de données suivants :

  • Attribuez les rôles roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser et roles/mcp.toolUser à l'utilisateur ou au compte de service IAM au niveau du projet (ou attribuez roles/spanner.databaseReader au niveau de la base de données pour les bases de données requises). Pour en savoir plus, consultez Appliquer des rôles IAM et Ajouter une liaison de stratégie IAM pour un projet.
  • Pour créer, importer et gérer des ensembles de contexte, attribuez le rôle Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) ou Administrateur de catalogue Dataplex (roles/dataplex.catalogAdmin) à l'utilisateur IAM au niveau du projet. Pour en savoir plus, consultez Autorisations des ensembles de contextes.

Préparer votre environnement

Vous pouvez créer et optimiser des ensembles de contexte à partir de votre environnement de développement local ou de votre IDE.

Installer uv

L'agent d'ingénierie de contexte nécessite uv pour gérer les packages Python sous-jacents :

  1. Installez uv en suivant les instructions de la page Installer uv.

  2. Vérifiez que uv est installé et accessible depuis votre ligne de commande :

    uv --version

Installer l'agent d'ingénierie de contexte

Installez le plug-in de l'agent d'ingénierie de contexte dans l'environnement de développement de votre choix :

CLI Antigravity

  1. Installez la CLI Antigravity. Consultez Premiers pas avec la CLI Antigravity.
  2. Installez le plug-in de l'agent d'ingénierie de contexte : 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Démarrez la CLI Antigravity : 
    agy

Pour mettre à jour le plug-in ultérieurement, exécutez agy plugin uninstall db-context-engineering, puis agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.

Claude Code

  1. Ajoutez la place de marché de plug-ins : 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Installez le plug-in : 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Actualisez les plug-ins pour activer les modifications : 
    /reload-plugins

Pour mettre à jour le plug-in ultérieurement, exécutez /plugin update db-context-engineering@db-context-enrichment-marketplace.

CLI Gemini (obsolète)

  1. Installez Gemini CLI. Consultez Premiers pas avec Gemini CLI.
  2. Installez l'extension : 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Pour mettre à jour l'extension ultérieurement, exécutez gemini extensions update google-cloud-db-context-engineering.

S'authentifier avec Google Cloud

  1. Configurez les identifiants par défaut de l'application (ADC) pour authentifier votre environnement de développement :

    gcloud auth application-default login

  2. Définissez le projet de quota pour vos identifiants afin que les outils MCP (Model Context Protocol) puissent utiliser votre projet Google Cloud  :

    gcloud auth application-default set-quota-project PROJECT_ID

    Remplacez PROJECT_ID par l'ID du projet Google Cloud .

Se connecter à la base de données

  1. Démarrez l'environnement de votre agent et demandez-lui d'établir la connexion à la base de données (par exemple, "Aide-moi à configurer la connexion à la base de données"). L'agent vous guide tout au long de la création du fichier de configuration .context-engineering/tools.yaml afin qu'il puisse lire les schémas et valider le code SQL. (Avant la création de .context-engineering/tools.yaml, un avertissement initial de connexion au serveur MCP toolbox au démarrage est attendu.)

  2. Actualisez la connexion au serveur MCP pour appliquer la configuration .context-engineering/tools.yaml :

    • CLI Antigravity : exécutez /mcp et sélectionnez toolbox (ou db-context-engineering_toolbox) pour redémarrer.
    • Claude Code : exécutez /mcp, sélectionnez toolbox, puis sélectionnez Reconnect.
    • Gemini CLI : exécutez /mcp refresh (ou /mcp reload).

Créer et optimiser le contexte

L'agent d'ingénierie de contexte guide votre ensemble de contextes tout au long d'un cycle de vie de bout en bout, du bootstrapping initial à la généralisation vérifiée.

Amorcer un ensemble de contextes de référence

Pour éviter de créer un contexte à partir d'une page blanche, l'agent inspecte le schéma de votre base de données ainsi que tous les artefacts d'application disponibles, tels que les exigences métier, la documentation ou des exemples de requêtes SQL. L'agent dérive un ensemble de contexte de référence initial contenant des modèles de requête de base et des facettes de requête ancrées dans votre modèle de base de données.

Après avoir généré et validé le contexte de référence, l'agent l'importe directement dans Google Cloud et renvoie le nom de la ressource de l'ensemble de contextes.

Créer des ensembles de données d'évaluation et de validation à partir d'artefacts d'application

Pour améliorer systématiquement la précision, vous avez besoin de questions de vérité terrain associées à des requêtes SQL validées. Si vous ne disposez pas déjà d'un benchmark d'évaluation, l'agent peut en générer un en extrayant des scénarios d'entreprise à partir du code de votre application, de l'historique des requêtes et du schéma de base de données.

Lors de la génération de l'ensemble de données, l'agent crée deux ensembles distincts :

  • Benchmark d'entraînement : ensemble de paires question-SQL représentatives utilisées lors de l'optimisation itérative.
  • Ensemble de données d'exclusion : ensemble distinct de questions similaires au domaine de votre benchmark d'entraînement, réservé aux tests de généralisabilité.

Optimiser la précision avec l'algorithme de hill climbing

Dans l'optimisation par recherche locale, l'agent affine de manière itérative votre ensemble de contexte pour que la précision de QueryData soit proche de 100 % :

  • Évaluation : l'agent teste votre ensemble de contextes actuel par rapport au benchmark d'entraînement à l'aide de l'API QueryData et évalue la précision.
  • Diagnostiquer les lacunes : l'agent analyse les échecs de requêtes, identifie leurs causes principales (par exemple, des jointures de table manquantes, des entités privées non associées ou des conditions de filtre complexes) et formule des correctifs ciblés.
  • Affiner et importer : l'agent ajoute ou améliore les modèles de requête, les facettes de requête et les recherches de valeurs pour combler les lacunes, et importe automatiquement l'ensemble de contexte mis à jour dans Google Cloud depuis votre CLI.
  • Itérer : l'agent répète ce cycle sur plusieurs tours jusqu'à ce que la précision converge vers le score optimal.

Le diagramme suivant illustre le workflow d'optimisation systématique :

Workflow pour créer du contexte de manière itérative.

Prouver la généralisabilité avec l'ensemble de données retenu

Il est nécessaire d'obtenir une précision élevée sur un benchmark d'entraînement, mais le trafic de production inclut des variations de formulation et des questions composées complexes qui n'ont jamais été vues pendant le développement.

Une fois que l'optimisation par hill-climbing converge, l'agent teste l'ensemble de contextes obtenu par rapport à l'ensemble de données d'exclusion. Cette étape permet de vérifier que l'ensemble de contexte se généralise correctement aux nouvelles entrées utilisateur sans surapprentissage par rapport au benchmark initial. L'agent produit un rapport de généralisabilité montrant la précision sur des variantes de questions non vues et des filtres composites (par exemple, "Trouve-moi des maisons près de bonnes écoles à Del Mar pour une jeune famille avec vue sur l'océan").

Création et raisonnement à la demande

En plus des exécutions d'optimisation complètes, vous pouvez discuter avec l'agent pour obtenir des mises à jour ciblées à mesure que les exigences de l'entreprise évoluent :

  • Création ciblée : décrivez une exigence métier spécifique en langage naturel, et l'agent formate l'élément de contexte et l'importe directement depuis votre CLI sans modification manuelle :

    • "Crée un modèle pour 'Trouve-moi des maisons près de bonnes écoles à Del Mar' avec le code 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."
    • "Crée un attribut pour le filtre properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 intitulé 'pour une jeune famille'."
    • "Crée une recherche de valeur pour properties.city."

  • Mises à jour groupées dans un ensemble de contextes : si des colonnes de base de données sont renommées ou si les structures de table changent, l'agent peut mettre à jour de manière groupée tous les éléments de contexte concernés sans modifier les entrées non liées :

    • "Dans mon ensemble de contexte, remplacez properties.property_type = 'SFR' par properties.property_type = 'Single Family Residential' pour tout élément faisant référence à des maisons individuelles. Ne touchez pas aux éléments non liés."

Étapes suivantes