Créer des ensembles de contexte à l'aide de l'agent d'ingénierie du contexte

Ce document explique comment créer et optimiser les ensembles de contextes qui permettent d'obtenir une précision élevée des requêtes QueryData sur vos applications d'agent de données. L'agent d'ingénierie de contexte vous aide à créer, évaluer et améliorer les ensembles de contexte en automatisant leur création et leur optimisation.

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

Pour créer des applications de données de niveau entreprise, la précision du modèle de conversion de texte en requête doit généralement atteindre une qualité proche de 100 %. Un code SQL généré de manière incorrecte affecte l'utilisabilité globale de l'application et l'expérience utilisateur. Pour obtenir des réponses explicables et pertinentes pour l'entreprise avec une grande précision, il est nécessaire de recourir à l'ingénierie de contexte, qui consiste à créer et à optimiser de manière itérative le contexte pour obtenir une précision optimale.

En fournissant à QueryData le contexte ciblé sur votre application métier, vous fournissez les règles métier précises dont le système a besoin pour résoudre l'intention nuancée de l'utilisateur.

Agent de context engineering

L'agent d'ingénierie de contexte automatise ce workflow d'optimisation. Vous pouvez discuter avec l'agent pour gérer des tâches ponctuelles afin d'optimiser votre contexte. La liste suivante fournit des exemples de requêtes en langage naturel que vous pouvez utiliser pour donner des instructions à l'agent, ainsi qu'une description de la réponse de l'agent. Utilisez ces exemples pour créer et optimiser votre contexte :

  • Exemple de prompt pour l'analyse des échecs : "Mettre à jour le contexte afin d'identifier correctement l'aéroport pour les requêtes telles que 'vols disney world'." L'agent analyse l'échec, réfléchit à l'écart et recommande d'ajouter un élément de contexte approprié, tel qu'une requête de recherche de valeur.
  • Exemple de prompt pour une suggestion de contexte : "Lis le code de mon application et suggère du contexte à ajouter." L'agent analyse le code, raisonne sur le domaine de votre application et suggère les éléments de contexte pertinents.
  • Exemple de prompt pour le traitement groupé : "Voici 10 exemples de questions et de requêtes SQL. Transformez-les en modèles." L'agent traite vos entrées de manière groupée et met à jour votre ensemble de contexte.

Importance de l'ensemble de données de référence

Pour optimiser votre contexte, vous devez d'abord créer un ensemble de données qui correspond aux entrées en langage naturel de votre application. L'agent peut vous aider à créer cet ensemble de données de référence, qui se compose de questions d'utilisateurs et des requêtes de base de données attendues. Un ensemble de données de référence vous permet de :

  • Établissez une référence pour les performances des requêtes.
  • Valider les mises à jour par rapport aux requêtes de base de données de vérité terrain.
  • Mesurez les améliorations de la précision au fil des itérations.

Le processus systématique de montée de colline

Dans l'optimisation systématique par hill-climbing, l'agent améliore de manière itérative un ensemble de contextes en évaluant l'ensemble de données de référence, en analysant les écarts et en effectuant des mises à jour pour atteindre une précision proche de 100 %.

  • Générer automatiquement un contexte de référence : créez un ensemble de contextes de départ dérivé de votre schéma de base de données et des artefacts de l'application.
  • Workflow d'optimisation par montée de gradient : laissez l'agent évaluer la précision de vos QueryData, effectuer une analyse des écarts sur les échecs et proposer automatiquement des améliorations pour augmenter la précision.

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

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

Avant de commencer

Avant d'utiliser l'agent d'ingénierie de contexte, remplissez les conditions préalables suivantes.

Activer les services requis

Activez les services suivants pour votre projet :

Préparer un cluster, une instance et une base de données AlloyDB pour PostgreSQL

Assurez-vous d'avoir accès à un cluster et à une instance AlloyDB existants, ou créez-en un.
Pour suivre ce tutoriel, vous devez disposer d'une base de données dans votre instance AlloyDB. Pour en savoir plus, consultez Créer une base de données.

Rôles et autorisations nécessaires

  • Ajoutez un compte d'utilisateur ou de service Identity and Access Management (IAM) au cluster au niveau de la base de données. Pour en savoir plus, consultez Gérer les utilisateurs de base de données.
  • Attribuez les rôles alloydb.databaseUser, serviceusage.serviceUsageConsumer et geminidataanalytics.queryDataUser à l'utilisateur IAM au niveau du projet. Pour en savoir plus, consultez 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.

Accorder l'autorisation executesql à l'instance AlloyDB pour PostgreSQL

Pour accorder l'autorisation executesql à l'instance AlloyDB pour PostgreSQL et définir le paramètre d'instance data_api_access sur la valeur ALLOW_DATA_API, utilisez la commande curl suivante : 
   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'
Remplacez les éléments suivants :
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région où se trouve votre cluster AlloyDB.
  • CLUSTER_ID : ID de votre cluster AlloyDB.
  • INSTANCE_ID : ID de votre instance AlloyDB.
Pour suivre les étapes de ce tutoriel, connectez-vous à Google Cloud, puis authentifiez-vous auprès de la base de données à l'aide de l'authentification IAM.

Préparer votre environnement

Vous pouvez créer des fichiers d'ensemble de contexte à partir de n'importe quel environnement de développement local ou IDE. Pour préparer votre environnement, procédez comme suit :

  • Installer l'agent d'ingénierie de contexte
  • Configurer la connexion à la base de données

Installer l'agent d'ingénierie de contexte

L'agent d'ingénierie de contexte exécute un serveur MCP (Model Context Protocol) qui 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

Pour préparer votre environnement, installez l'agent d'ingénierie de contexte dans le harnais d'agent de votre choix, comme la CLI Antigravity, Claude Code ou la CLI Gemini.

En fonction du harnais d'agent que vous avez sélectionné, suivez les étapes d'installation correspondantes :

CLI Antigravity

Pour installer l'agent d'ingénierie de contexte dans la CLI Antigravity, procédez comme suit :

  1. Installez la CLI Antigravity. Consultez Premiers pas avec la CLI Antigravity.
  2. Installez le plug-in d'agent d'ingénierie de contexte, qui inclut des workflows pour la génération de contexte. Remplacez VERSION par la version publiée requise : 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Démarrez la CLI Antigravity : 
    agy

Pour mettre à jour le plug-in vers la dernière version, exécutez la commande suivante. Remplacez VERSION par la version publiée requise :

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION

Claude Code

Pour installer l'agent d'ingénierie de contexte dans Claude Code, procédez comme suit :

  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
  4. Mettez à jour le plug-in : 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

CLI Gemini (obsolète)

Pour installer l'agent d'ingénierie de contexte dans Gemini CLI, procédez comme suit :

  1. Installez Gemini CLI. Consultez Premiers pas avec Gemini CLI.
  2. Installez l'extension : 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Mettez à jour l'extension : 
    gemini extensions update google-cloud-db-context-engineering

Configurer la connexion à la base de données

L'agent nécessite une connexion à la base de données pour récupérer les schémas et la capacité de valider la syntaxe du contexte SQL généré. Pour permettre à l'agent d'interagir avec votre base de données, configurez les identifiants d'authentification et définissez la configuration de votre connexion à la base de données.

Configurer les identifiants par défaut de l'application

Configurez les identifiants par défaut de l'application (ADC) pour fournir des identifiants utilisateur permettant d'accéder aux ressources Google Cloud à partir de l'agent d'ingénierie de contexte :

  • Serveur MCP Toolbox : utilise des identifiants pour se connecter à votre base de données, récupérer des schémas et exécuter du code SQL pour la validation.
  • Evalbench : utilise des identifiants pour appeler QueryData à des fins d'évaluation.

Exécutez la commande suivante dans votre terminal pour vous authentifier :

gcloud auth application-default login

Configurer le fichier de connexion à la base de données

L'agent nécessite une connexion à la base de données pour générer le contexte, ce que MCP Toolbox accepte et définit dans un fichier de configuration.

Le fichier de configuration spécifie la source de votre base de données et les outils requis pour récupérer des schémas ou exécuter du code SQL. L'agent d'ingénierie contextuelle est fourni avec des compétences d'agent préinstallées pour vous aider à générer la configuration.

  1. Démarrez l'environnement de votre agent.

  2. Demandez à l'agent de vous aider à configurer la connexion à la base de données. Par exemple, saisissez le prompt "aide-moi à configurer la connexion à la base de données". Suivez les instructions de l'agent pour créer le fichier de configuration dans votre répertoire de travail actuel sous le nom autoctx/tools.yaml.

  3. Pour appliquer la nouvelle configuration tools.yaml, actualisez votre connexion :

    • Dans la CLI Antigravity, exécutez /mcp et sélectionnez toolbox pour redémarrer.
    • Dans Gemini CLI, exécutez /mcp reload.
    • Dans Claude Code, exécutez /mcp, sélectionnez toolbox, puis sélectionnez Reconnect.

Pour en savoir plus sur la configuration manuelle du fichier de configuration de la base de données, consultez Configuration de MCP Toolbox.

Générer et optimiser le contexte

L'agent d'ingénierie de contexte fournit un ensemble de compétences d'agent et d'outils MCP pour améliorer la capacité d'ingénierie de contexte de votre agent de codage. Vous pouvez utiliser ces outils ensemble pour générer une référence, mesurer l'efficacité et appliquer des améliorations de manière itérative. Toutefois, vous pouvez commencer à n'importe quelle étape du workflow :

  • Si vous avez déjà défini un contexte, vous pouvez passer directement à l'évaluation.
  • Si vous souhaitez corriger des requêtes défaillantes, vous pouvez passer directement à l'analyse des écarts.

Chaque fonctionnalité décrit les actions, les cas d'utilisation et les commandes d'appel de l'agent.

Les exemples de requêtes montrent comment interroger l'agent en langage naturel. Si l'agent a besoin d'informations supplémentaires pour répondre à une requête, il vous demande des précisions.

Créer et développer des ensembles de données d'évaluation

Pour améliorer les performances, vous devez d'abord les mesurer. L'ingénierie de contexte sans ensemble de données de référence, qui se compose de questions d'utilisateurs associées au code SQL attendu, manque de vérification systématique. Avec un ensemble de données de référence, chaque modification est une amélioration mesurable que vous pouvez valider par rapport à la vérité terrain.

La création manuelle d'un ensemble de données de référence représentatif prend du temps, et les petits ensembles de données peuvent ne pas tenir compte des variations dans la formulation des utilisateurs. L'agent résout ce problème en procédant comme suit :

  • Génération de paires question-SQL candidates basées sur votre schéma de base de données.
  • Développer un petit ensemble de données de départ à l'aide de variantes de filtres, de synonymes et de reformulations.

Vous pouvez éventuellement laisser l'agent exécuter le code SQL généré sur votre base de données. Cette vérification confirme que les requêtes s'exécutent correctement avant de les ajouter à l'ensemble de données.

L'ensemble de données est un fichier JSON contenant des paires question-SQL :

json [ { "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;" } ]

Les paires approuvées sont ajoutées au fichier autoctx/golden.json de votre espace de travail, où elles sont prêtes à être évaluées. Vous pouvez fournir un fichier existant ou écrire des exemples d'évaluation intégrés que l'agent pourra développer.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Génère un ensemble de données d'évaluation à partir de mon schéma."
  • "Voici une question de départ et une requête SQL. Développe-le en un ensemble de données plus vaste et vérifie que les requêtes s'exécutent."

Générer un ensemble de contextes de référence

Pour éviter de créer un contexte de zéro, vous pouvez laisser l'agent déduire un ensemble de contexte initial à partir du schéma de votre base de données et des artefacts de l'application, tels que les règles métier, les exemples de requêtes ou les fichiers README. Bien que ce contexte de référence ne soit pas définitif, il fournit un point de départ validé basé sur votre modèle de base de données.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Génère un ensemble de contextes à partir de mon schéma."
  • "Génère le contexte initial à l'aide de ces schémas et des règles d'entreprise dans requirements.md."

L'agent vous invite à nommer le test, qui organise les artefacts générés, et peut vous demander de limiter le champ d'application si votre schéma de base de données est volumineux. Pour importer le contexte à l'aide d'AlloyDB Studio, suivez les instructions après que l'agent a généré le fichier JSON.

Évaluer l'efficacité du contexte

Une fois que vous avez établi un ensemble de contextes et un ensemble de données de référence, vous pouvez laisser l'agent mesurer les performances du contexte en interrogeant l'API QueryData de votre agent de données avec chaque question de référence. L'agent compare le code SQL généré et les résultats de son exécution à la réponse attendue à l'aide d'Evalbench pour gérer la comparaison.

L'exécution d'une évaluation fournit les éléments suivants :

  • Des métriques quantitatives, telles que les résultats de réussite et d'échec et les scores agrégés, pour suivre la progression entre les itérations de contexte.
  • Un résumé de la conversation intégré et des rapports CSV détaillés écrits dans le répertoire eval_reports/ de votre dossier de test.

Pour lancer une évaluation, indiquez le chemin d'accès à l'ensemble de données de référence et l'ID de l'ensemble de contexte. Pour savoir comment trouver l'ID de l'ensemble de contextes, consultez Trouver l'ID de contexte de l'agent.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Évalue mon contexte par rapport à golden.json."
  • "Réexécuter l'évaluation en utilisant la configuration de mon dernier test."

Pour réexécuter une configuration d'évaluation précédemment générée sans la configurer à nouveau, demandez à l'agent ou appelez directement la CLI :

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

Pour en savoir plus sur le schéma de configuration de l'évaluation et sur la personnalisation des exécutions d'évaluation, consultez la documentation d'Evalbench.

Effectuer une analyse des écarts et proposer des améliorations

Pour résoudre les échecs de requêtes, vous devez identifier leurs causes principales, telles que des colonnes incorrectes, des jointures de table manquantes ou des termes flous non résolus. L'identification manuelle de ces problèmes nécessite une analyse approfondie des rapports d'évaluation.

L'agent automatise cette boucle d'analyse et de correction :

  • Analyse des écarts : l'agent lit les résultats de l'évaluation et votre ensemble de contexte pour regrouper les échecs similaires et recommander des ajouts de contexte ciblés, tels que des modèles, des facettes ou des recherches de valeurs.
  • Corrections proposées : l'agent propose des modifications concrètes et teste éventuellement le code SQL sur votre base de données pour vérifier la résolution.
  • Préservation de la référence : l'agent écrit les améliorations dans un nouveau fichier JSON à côté de votre contexte de référence, en préservant les fichiers d'origine.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Effectue une analyse des écarts sur ma dernière évaluation et propose des corrections."
  • "Optimise cet ensemble de contextes par rapport à golden.json."

Pour préparer l'itération suivante, importez le contexte amélioré dans l'ensemble de contextes cible à l'aide d'AlloyDB Studio en suivant les instructions.

Créer des éléments de contexte spécifiques à la demande

Si vous connaissez déjà le contexte requis, comme un modèle pour une question spécifique, un attribut pour un filtre répété ou une recherche de valeur pour une colonne particulière, l'écriture manuelle du fichier JSON de contexte peut introduire des erreurs de sérialisation dans les noms de paramètres, les métadonnées de type ou la syntaxe des fragments. L'agent gère la mise en forme JSON pour vous permettre de vous concentrer sur votre intention commerciale.

Vous pouvez également utiliser cette fonctionnalité pour des mises à jour ponctuelles, par exemple lorsque vous devez prendre en charge un nouveau schéma de requête ou corriger un détail de schéma manquant. Pour obtenir le fichier JSON, décrivez le contexte requis à l'agent sans exécuter d'évaluation ni configurer de test.

C'est également la fonctionnalité idéale lorsque vous êtes confronté à une tâche ponctuelle : un intervenant vous donne une nouvelle paire question-SQL qu'il souhaite prendre en charge, ou vous repérez un aspect manquant lors d'une revue de code. Vous n'avez pas besoin de configurer un test ni d'exécuter une évaluation pour résoudre le problème. Décrivez ce que vous voulez, et l'agent génère le JSON.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Crée un modèle pour 'Quels aéroports se trouvent en Californie ?' avec le code SQL : SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Crée un attribut pour le filtre departure_time BETWEEN '00:00:00' AND '06:00:00' intitulé 'yeux rouges'."
  • "Crée une recherche de valeur pour airports.iata."

Raison du choix du type de contexte

Sélectionner le bon type de contexte, qu'il s'agisse d'une recherche de modèle, d'attribut ou de valeur, permet d'éviter l'encombrement du contexte et les régressions des requêtes de base de données. Par exemple, l'utilisation d'un modèle au lieu d'un attribut peut entraîner des règles en double, tandis que les recherches de valeurs introduites lorsqu'un modèle est suffisant peuvent augmenter la latence des requêtes. Pour trouver le format de schéma approprié, demandez à l'agent de recommander un type en fonction de la structure de la requête ou des colonnes de la base de données avant de créer des éléments de contexte. L'agent explique son raisonnement pour vous aider à comprendre les options de contexte.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Je n'arrête pas d'écrire le filtre departure_time BETWEEN '00:00:00' AND '06:00:00' dans de nombreuses requêtes. Quelle est la meilleure façon de capturer cela ?"
  • "Les utilisateurs décrivent l'état du vol en texte libre, et je souhaite les faire correspondre à flights.status. Quel type de recherche de valeur dois-je configurer ?"
  • "Quelle est la différence entre un modèle et un attribut, et quand dois-je utiliser l'un ou l'autre ?"

Appliquer des opérations groupées à un ensemble de contextes

L'agent accepte les mises à jour groupées pour gérer de manière cohérente de grands ensembles de contextes. Si vous devez mettre à jour plusieurs éléments de contexte simultanément (par exemple, lorsqu'une colonne de base de données est renommée, qu'une valeur de code change de format ou que des modèles font référence à une table obsolète), l'agent peut appliquer la modification à chaque élément concerné sans modifier les entrées non liées.

Vous pouvez utiliser les exemples de requêtes suivants pour donner des instructions à l'agent :

  • "Lis golden.txt et transforme toutes les paires en modèles."
  • "Dans context_set.json, remplacez airline = 'UA' par airline = 'United Airlines' pour tout élément faisant référence à 'United'. Ne touchez pas aux éléments non liés."

Étapes suivantes