Créer des ensembles de contextes pour Firestore compatible avec MongoDB à l'aide de l'agent d'ingénierie contextuelle

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 requête textuelle doit généralement atteindre près de 100 %. Une génération incorrecte du langage de requête compatible avec MongoDB (MQL) 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é 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 d'ingénierie contextuelle

L'agent d'ingénierie contextuelle automatise ce workflow d'optimisation. Vous pouvez converser avec l'agent pour gérer des 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 un 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 MQL. 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 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 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 une base de données Firestore

Assurez-vous de disposer d'une base de données Firestore Enterprise Edition compatible avec MongoDB.

Si vous essayez les exemples de cette page, nous vous recommandons de créer une base de données à cet effet. Pour en savoir plus, consultez Créer et gérer des bases de données.

Rôles et autorisations requis

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 le 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 MQL 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 MQL pour la 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 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 MQL 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-MQL candidates en fonction de votre schéma de 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 MQL généré par rapport à 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-MQL :

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for each of the top 5 products?",
    "golden_sql": "db.sales.aggregate([ { $group: { _id: '$product_id', total_net_revenue: { $sum: '$net_revenue' } } }, { $sort: { total_net_revenue: -1 } }, { $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 de départ et un MQL. Développez-le 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 de votre schéma de 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, 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 de Firestore 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 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 du 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 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 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 SQL par rapport à 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 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 introduire 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 détail 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 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 repérez 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 la requête : db.airports.find({ country: "United States", state: "CA" }, { name: 1, _id: 0 })."
  • "Créer une facette pour le filtre { departure_time: { $gte: "00:00:00", $lte: "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 des 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: { $gte: "00:00:00", $lte: "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 groupées à un ensemble de contextes

L'agent prend en charge les mises à jour groupées pour gérer de grands ensembles de contextes de manière cohérente. 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'un format de valeur de code est modifié 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