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 grande précision des requêtes QueryData dans vos applications d'agent de données. L'agent d'ingénierie contextuelle vous aide à créer, évaluer et améliorer les ensembles de contextes 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 près 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, vous devez utiliser l'ingénierie contextuelle, qui consiste à créer et à optimiser de manière itérative le contexte afin d'obtenir une précision optimale.

En fournissant à QueryData le contexte ciblé pour 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 d'ingénierie contextuelle

L'agent d'ingénierie contextuelle automatise ce workflow d'optimisation. Vous pouvez discuter avec l'agent pour gérer les tâches ad hoc 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 façon dont l'agent répond. Utilisez ces exemples pour créer et optimiser votre contexte :

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

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 des utilisateurs et des requêtes de base de données attendues. Un ensemble de données de référence vous permet de :

  • établir 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 ;
  • mesurer les améliorations de la précision au fil des itérations.

Processus systématique d'escalade

Dans l'escalade systématique, 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 apportant des mises à jour pour atteindre une précision de près de 100%.

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

Le schéma suivant illustre le workflow d'escalade systématique :

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

Avant de commencer

Avant d'utiliser l'agent d'ingénierie contextuelle, 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.
Ce tutoriel nécessite que vous disposiez 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 requis

  • 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 la base de données.
  • Accordez 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 contextes, accordez 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 Google Cloud projet.
  • 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 contextes à 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 contextuelle
  • Configurer la connexion à la base de données

Installer l'agent d'ingénierie contextuelle

L'agent d'ingénierie contextuelle 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 section 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 contextuelle dans l'harnais d'agent de votre choix, tel que la CLI Antigravity, Claude Code ou la CLI Gemini.

Selon le harnais d'agent que vous avez sélectionné, suivez les étapes d'installation correspondantes :

CLI Antigravity

Pour installer l'agent d'ingénierie contextuelle 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 de l'agent d'ingénierie contextuelle, qui inclut des workflows pour la génération 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 vers la dernière version :

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

Claude Code

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

  1. Ajoutez le marketplace 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. Rechargez 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 contextuelle dans la CLI Gemini, procédez comme suit :

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

Configurer la connexion à la base de données

L'agent nécessite une connexion à la base de données pour extraire les schémas et 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 Google Cloud ressources à partir de l' agent d'ingénierie contextuelle :

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

Exécutez les commandes suivantes 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 la génération de contexte, que la Boîte à outils MCP prend en charge et définit dans un fichier de configuration.

Le fichier de configuration spécifie votre source de base de données et les outils nécessaires pour extraire 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 votre environnement d'agent.

  2. Demandez à l'agent de vous aider à configurer la connexion à la base de données. Par exemple, saisissez "help me set up the database connection" (aidez-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, rechargez votre connexion :

    • Dans la CLI Antigravity, exécutez /mcp et sélectionnez toolbox pour redémarrer.
    • Dans la CLI Gemini, exécutez /mcp reload.
    • Dans Claude Code, exécutez /mcp, sélectionnez toolbox, puis 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 contextuelle fournit un ensemble de compétences d'agent et d'outils MCP pour améliorer la capacité d'ingénierie contextuelle 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 disposez déjà d'un ensemble de contextes, vous pouvez passer directement à l'évaluation.
  • Si vous avez des requêtes qui échouent et que vous souhaitez corriger, 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 effectuer une requête, il vous demande des précisions.

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

Pour améliorer les performances, vous devez d'abord les mesurer. L'ingénierie contextuelle sans ensemble de données de référence, qui se compose de questions des utilisateurs associées à leur 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 manquer de variations dans la formulation des utilisateurs. L'agent résout ce problème en :

  • générant des paires question-SQL candidates en fonction du schéma de votre base de données ;
  • développant un petit ensemble de données de départ à l'aide de variations de filtres, de synonymes et de reformulations.

Vous pouvez également autoriser 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 que vous ne les ajoutiez à l'ensemble de données.

L'ensemble de données est un fichier JSON contenant des paires question-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;"
  }
]

Les paires approuvées remplissent le 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 pour que l'agent les développe.

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

  • "Générer un ensemble de données d'évaluation à partir de mon schéma."
  • "Voici une question et un code SQL de départ. Développez-les en un ensemble de données plus large et vérifiez 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 à partir de zéro, vous pouvez laisser l'agent dériver un ensemble de contextes initial à partir du schéma de votre base de données et des artefacts de votre application, tels que des règles métier, des exemples de requêtes ou des fichiers README. Bien que ce contexte de référence ne soit pas final, 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érer un ensemble de contextes à partir de mon schéma."
  • "Générer un contexte initial à l'aide de ces schémas et des règles métier dans requirements.md."

L'agent vous invite à nommer l'expérience, ce qui permet d'organiser les artefacts générés, et peut vous demander de limiter le champ d'application si le schéma de votre base de données est volumineux. Pour importer le contexte à l'aide d'AlloyDB Studio, suivez les instructions une fois 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 ses résultats d'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, ainsi que des scores agrégés, pour suivre les progrès au fil des 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 d'expérience.

Pour démarrer une évaluation, fournissez le chemin d'accès à l'ensemble de données de référence et l'ID de l'ensemble de contextes. 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 :

  • "Évaluer mon contexte par rapport à golden.json."
  • "Réexécuter l'évaluation à l'aide de la configuration de ma dernière expérience."

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

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

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 profondes, telles que des colonnes incorrectes, des jointures de tables manquantes ou des termes approximatifs 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 contextes 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 par rapport à votre base de données pour vérifier la résolution.
  • Conservation 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 conservant les fichiers d'origine.

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

  • "Exécuter une analyse des écarts sur ma dernière évaluation et proposer des corrections."
  • "Optimiser 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 de Data Agents Studio, puis suivez les instructions.

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

Si vous connaissez déjà le contexte requis, tel qu'un modèle pour une question spécifique, une facette pour un filtre répété ou une recherche de valeur pour une colonne particulière, l'écriture manuelle du JSON de contexte peut entraîner des erreurs de sérialisation dans les noms de paramètres, les métadonnées de type ou la syntaxe de fragment. 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 les mises à jour ad hoc, par exemple lorsque vous devez prendre en charge un nouveau modèle de requête ou résoudre un problème de schéma manquant. Pour obtenir le JSON, décrivez le contexte requis à l'agent sans exécuter d'évaluation ni configurer d'expérience.

Il s'agit également de la bonne fonctionnalité à utiliser lorsque vous recevez une tâche ponctuelle : un partenaire vous donne une nouvelle paire question-SQL qu'il souhaite prendre en charge, ou vous remarquez une facette manquante lors d'une revue de code. Vous n'avez pas besoin de configurer une expérience 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éer 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éer une facette pour le filtre departure_time BETWEEN '00:00:00' AND '06:00:00' libellé 'red eye'."
  • "Créer une recherche de valeur pour airports.iata."

Expliquer le type de contexte à sélectionner

La sélection du type de contexte approprié, qu'il s'agisse d'un modèle, d'une facette ou d'une recherche de valeur, permet d'éviter le gonflement du contexte et les régressions de requêtes de base de données. Par exemple, l'utilisation d'un modèle au lieu d'une facette peut entraîner la duplication de règles, 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 correct, 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 continue 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 des vols 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 une facette, et quand dois-je utiliser chacun d'eux ?"

Appliquer des opérations par lot à un ensemble de contextes

L'agent prend en charge les mises à jour groupées pour gérer de manière cohérente les 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 :

  • "Lire golden.txt et transformer 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 modifiez pas les éléments non liés."

Étape suivante