Nous avons récemment contribué au projet open source mastra-ai/mastra en ajoutant la prise en charge d'Elasticsearch en tant que base de données vectorielle. Avec cette nouvelle option, vous avez la possibilité d’utiliser Elasticsearch de manière native au sein de Mastra pour le stockage de vos plongements sémantiques. En plus des vecteurs, Elasticsearch propose une suite de fonctionnalités avancées pour répondre à toutes vos exigences en matière d’ingénierie de contexte. (par exemple, recherche hybride et reclassement).

Cet article détaille la création d'un agent chargé de mettre en œuvre une architecture RAG (Retrieval Augmented Generation) à l'aide d'Elasticsearch. Nous présenterons un projet de démonstration dans lequel une approche agentique est utilisée pour interagir avec un corpus de données de films de science-fiction stockées dans Elasticsearch. Le projet est disponible à l’adresse elastic/mastra-elasticsearch-example.

Mastra

Mastra est un framework TypeScript qui permet de créer des applications d'IA agentiques.

La structure du projet dans Mastra se présente comme suit :

Dans Mastra, vous pouvez créer des agents, outils, workflows et scores.

Un agent est une classe qui accepte un message en entrée et produit une réponse en sortie. Un agent peut utiliser des outils, de grands modèles de langage (LLM) et une mémoire (figure 1).

Les outils d’un agent lui permettent d’interagir avec le « monde extérieur », par exemple en communiquant avec une API Web ou en effectuant une opération interne, comme l’interrogation d’Elasticsearch. Le composant mémoire est crucial pour stocker l'historique des conversations, y compris les entrées et sorties passées. Ce contexte stocké permet à l’agent de fournir des réponses plus éclairées et pertinentes aux questions futures en utilisant ses interactions passées.

Les workflows permettent de définir des séquences complexes de tâches en utilisant des étapes claires et structurées, plutôt que de se fier au raisonnement d’un seul agent (figure 2). Ils vous donnent un contrôle total sur la manière dont les tâches sont décomposées, comment les données circulent entre elles et ce qui est exécuté à chaque fois. Les workflows s'exécutent en utilisant le moteur d'exécution intégré par défaut ou peuvent être déployés sur des workflow runners.

Dans Mastra, vous pouvez également définir des scores : des tests automatisés qui évaluent les sorties des agents à l'aide de méthodes basées sur des modèles, des règles et des statistiques. Les scoreurs renvoient des scores : des valeurs numériques (généralement entre 0 et 1) qui quantifient dans quelle mesure une sortie répond à vos critères d'évaluation. Ces scores vous permettent de suivre objectivement les performances, de comparer différentes approches et d'identifier les domaines à améliorer dans vos systèmes d'IA. Les évaluateurs peuvent être personnalisés avec vos propres invites et fonctions de notation.

Elasticsearch

Pour exécuter le projet de démonstration, nous devons avoir une instance Elasticsearch en cours d'exécution. Vous pouvez activer un essai gratuit sur Elastic Cloud ou l’installer localement en utilisant le script start-local :

Cela installera Elasticsearch et Kibana sur votre ordinateur et générera une clé API à utiliser pour configurer l’intégration Mastra.

La clé API sera affichée comme sortie de la commande précédente et stockée dans un fichier .env dans le dossier elastic-start-local.

Installation et configuration de la démo

Nous avons créé un dépôt elastic/mastra-elasticsearch-example contenant le code source du projet de démonstration. L'exemple rapporté dans le référentiel illustre comment créer un agent dans Mastra qui implémente une architecture RAG pour récupérer des documents depuis Elasticsearch.

Nous avons fourni un ensemble de données pour la démo sur les films de science-fiction. Nous avons extrait 500 films de l'ensemble de données IMDb sur Kaggle.

La première étape consiste à installer les dépendances du projet avec npm, en utilisant la commande suivante :

Ensuite, nous devons configurer le fichier .env qui contiendra les paramètres. Nous pouvons générer ce fichier en copiant la structure du fichier .env.example, à l'aide de la commande suivante :

Nous pouvons maintenant modifier le fichier .env, en ajoutant les informations manquantes :

Le nom de l’index Elasticsearch est scifi-movies. Si vous le souhaitez, vous pouvez le modifier en utilisant la variable env ELASTICSEARCH_INDEX_NAME.

Nous avons utilisé OpenAI comme service d’intégration, ce qui signifie que vous devez fournir une clé API pour OpenAI dans la variable OPENAI_API_KEY environnement.

Le modèle de plongement utilisé dans l'exemple est openai/text-embedding-3-small, avec une dimension de plongement de 1536.

Pour obtenir la réponse finale, nous avons utilisé le modèle openai/gpt-5-nano afin de réduire les coûts.

La structure RAG autorise l’usage d’un LLM moins sophistiqué en bout de chaîne, puisque la mission critique d’ancrage de la réponse dans des données fiables est assurée en amont par le moteur de recherche (Elasticsearch).

Le LLM plus petit n'est responsable que de deux tâches principales :

• Reformuler/intégrer la requête : conversion de la question en langage naturel de l'utilisateur en une question vectorielle intégrée pour la recherche sémantique.

• Synthétiser la réponse : prendre les éléments contextuels (documents/films) les plus pertinents récupérés et les synthétiser pour obtenir une réponse cohérente, finale et lisible par l'homme, en suivant les instructions rapides fournies.

Puisque le processus RAG fournit le contexte factuel précis nécessaire à la réponse, le LLM final n’a pas besoin d’être massif ou extrêmement complexe, et il n’est pas nécessaire qu’il possède toutes les connaissances requises au sein de ses propres paramètres (domaine où excellent les modèles volumineux et coûteux). Il agit essentiellement comme un outil sophistiqué de résumé et de formatage de texte pour le contexte fourni par Elasticsearch, plutôt que comme une base de connaissances à part entière. Cela permet l’utilisation de modèles comme gpt-5-nano pour l’optimisation des coûts et de la latence.

Après la configuration du fichier .env , vous pouvez ingérer les films dans Elasticsearch à l'aide de la commande suivante :

Vous devriez obtenir la sortie suivante :

Le mapping de l’index des films de science-fiction contient les champs suivants :

• plongement, vecteur dense de dimension 1536, similarité cosinus.

• description, texte contenant la description du film.

• réalisateur, texte contenant le nom du réalisateur.

• titre, texte contenant le titre du film.

Nous avons généré les vecteurs d'inclusion en utilisant le titre et la description. Puisque le titre et la description sont deux champs distincts, la concaténation des deux garantit que le vecteur d’inclusion résultant capture à la fois l’identité spécifique et unique (titre) et le contexte descriptif riche (description) du film, conduisant à des résultats de recherche sémantiques plus précis et complets. Cette entrée combinée donne au modèle d'intégration une meilleure représentation unique du contenu du document pour le rapprochement par similarité.

Exécutez la démo

Vous pouvez exécuter la démo avec la commande suivante :

Cette commande lancera une application web à localhost :4111 pour accéder à Mastra Studio (figure 3).

Mastra Studio offre une interface utilisateur interactive pour construire et tester vos agents, ainsi qu'une API REST qui expose votre application Mastra en tant que service local. Cela vous permet de commencer à construire immédiatement sans vous soucier de l'intégration.

Nous avons fourni un agent Elasticsearch qui utilise l'outil createVectorQueryTool de Mastra comme outil pour exécuter une recherche sémantique à l'aide d'Elasticsearch. Cet agent utilise l'approche RAG pour rechercher des documents pertinents (c'est-à-dire des films) pour répondre à la question de l'utilisateur.

Cet agent utilise la consigne suivante :

Si vous cliquez sur le menu Mastra Studio > Agents et sélectionnez Agent Elasticsearch, vous pouvez tester l’agent via un système de chat. Par exemple, vous pouvez demander des informations sur les films de science-fiction en posant la question suivante :

Trouvez 5 films ou séries télévisées sur les OVNI.

Vous remarquerez que l’agent exécutera le vectorQueryTool. Vous pouvez cliquer sur l'outil invoqué pour voir l'entrée et la sortie. À la fin de l’exécution, le LLM répondra à votre question, compte tenu du contexte issu de l’index des films de science-fiction d’Elasticsearch (figure 4).

Mastra exécute les étapes suivantes en interne :

1. Conversion vectorielle : La question de l'utilisateur, trouvez 5 films ou séries télévisées sur les OVNI, est convertie en une intégration vectorielle à l'aide du modèle openai/text-embedding-3-small d'OpenAI.

2. Recherche vectorielle : ce plongement sémantique sert alors à effectuer une requête au sein d’Elasticsearch par le biais d’une recherche vectorielle.

3. Récupération des résultats : Elasticsearch renvoie un ensemble de 10 films très pertinents par rapport à la requête (c'est-à-dire ceux dont les vecteurs sont les plus proches du vecteur de la requête de l'utilisateur).

4. Génération de réponses : Les films récupérés et la question originale de l'utilisateur sont envoyés au LLM, en particulier à openai/gpt-5-nano. Le LLM traite ces informations et génère une réponse finale, en s'assurant que la demande de l'utilisateur pour cinq résultats est satisfaite.

L'agent Elasticsearch

Ici, nous avons rapporté le code source d'Elasticsearch Agent.

L'outil vectorQueryTool est l'outil invoqué pour mettre en œuvre la partie extraction de l'exemple RAG. Il utilise l’implémentation ElasticSearchVector qu’Elastic a apportée à Mastra.

L’agent est une instance de la classe agent qui utilise le vectorQueryTool, l’invite et un composant de mémoire. On remarque que le code nécessaire pour l’interconnexion entre Elasticsearch et un agent est extrêmement réduit.

Conclusion

Cet article a mis en lumière la facilité et l'efficacité de l'association entre Elasticsearch et la structure Mastra pour développer des solutions d'IA agentiques avancées. Nous avons plus spécifiquement exploré la conception d’un agent RAG pouvant mener des recherches sémantiques sur un ensemble de données relatives à des films de science-fiction indexés sous Elasticsearch.

L’un des enseignements majeurs réside dans la contribution directe d’Elastic à la communauté Mastra, permettant d’intégrer nativement Elasticsearch comme magasin de vecteurs. Cette intégration réduit considérablement la barrière à l'entrée, comme le montre le code source de l'agent Elasticsearch. En utilisant ElasticSearchVector et createVectorQueryTool, la configuration complète pour connecter Elasticsearch à votre agent ne nécessite qu'un nombre minimal de lignes de code de configuration.

Elasticsearch propose plusieurs fonctionnalités avancées pour améliorer la pertinence des résultats. Par exemple, la recherche hybride améliore considérablement la précision en combinant la recherche lexicale et la recherche vectorielle. Une autre fonctionnalité intéressante est le reranking utilisant les derniers modèles Jina qui peuvent être appliqués à la fin de la recherche hybride. Pour en savoir plus sur ces techniques, consultez les articles suivants d'Elasticsearch Labs :

• Recherche hybride Elasticsearch par Valentin Crettaz

• Présentation des modèles Jina, de leurs fonctionnalités et de leurs cas d'usage dans Elasticsearch par Scott Martens

Nous vous encourageons également à explorer l’exemple fourni et à commencer à créer vos propres agents alimentés par les données avec Mastra et Elasticsearch. Pour plus d'informations sur Mastra, vous pouvez consulter la documentation officielle ici.

L'extension est disponible en tant que projet open source ici.

Qu'est-ce que Gemini CLI et comment l'installer ?

Gemini CLI est un agent d’IA open source qui intègre les modèles Gemini de Google directement dans la ligne de commande. Il permet aux développeurs d’interagir avec l’IA depuis le terminal pour effectuer des tâches telles que générer du code, éditer des fichiers, exécuter des commandes shell et récupérer des informations sur le web.

Contrairement aux interfaces de chat classiques, Gemini CLI s'intègre à votre environnement de développement local, ce qui signifie qu'il peut comprendre le contexte du projet, modifier des fichiers, assurer l'exécution des compilations ou des tests et automatiser les workflows directement dans le terminal. Il est donc utile aux développeurs, aux ingénieurs de fiabilité des sites (SRE) et aux ingénieurs qui souhaitent un codage assisté par l'IA et une automatisation sans quitter leur workflow en ligne de commande.

Le CLI Gemini s’installe à l’aide de plusieurs gestionnaires de paquets. La méthode la plus courante passe par npm :

Si vous souhaitez connaître d’autres options d’installation, consultez la page officielle d’installation.

Après l’installation, lancez la CLI en exécutant :

Vous voyez un écran, comme illustré sur la figure 1 :

Configurer Elasticsearch

Nous avons besoin d'une instance Elasticsearch en cours d'exécution. Si vous souhaitez utiliser le serveur Model Context Protocol (MCP), vous devez également installer Kibana 9.3+. Pour utiliser le langage de requête Elasticsearch (ES|QL) (esql) décrit ci-dessous, Kibana n’est pas requise.

Vous pouvez activer un essai gratuit sur Elastic Cloud ou l’installer localement en utilisant le script start-local :

Cela installera Elasticsearch et Kibana sur votre ordinateur et générera une clé API à utiliser pour configurer Gemini CLI.

La clé API sera affichée comme sortie de la commande précédente et stockée dans un fichier .env fichier dans le dossier elastic-start-local.

Si vous utilisez Elasticsearch sur site (par exemple, en utilisant start-local), et que vous souhaitez utiliser Elastic Agent Builder avec MCP, vous devez aussi connecter un grand modèle de langage (LLM). Vous pouvez consulter cette page de documentation pour comprendre les différentes options.

Si vous utilisez Elastic Cloud (ou Elastic Cloud Serverless), vous disposez déjà d’une connexion LLM préconfigurée.

Installez l'extension Elasticsearch

Vous pouvez installer l'extension Elasticsearch pour Gemini CLI avec la commande suivante :

Vous pouvez vérifier que les extensions ont été installées avec succès en ouvrant Gemini et en exécutant la commande suivante :

L'extension Elasticsearch devrait être disponible.

Si vous souhaitez utiliser l'intégration MCP, vous devez avoir une version d'Elasticsearch 9.3+ installée. Vous avez besoin de l’URL de votre serveur MCP depuis Kibana :

• Obtenez l'URL de votre serveur MCP dans Agents > Voir tous les outils > Gérer MCP > Copier l'URL du serveur MCP.

• L'URL se présentera comme suit : https://your-kibana-instance/api/agent_builder/mcp

Vous avez besoin de l’URL de l'endpoint Elasticsearch. Ce message apparaît généralement en haut de la page Elasticsearch de Kibana. Si vous utilisez Elasticsearch avec start-local, vous avez déjà l'endpoint dans la clé ES_LOCAL_URL dans le fichierstart-local .env.

Vous avez également besoin d’une clé API. Si vous exécutez Elasticsearch avec start-local, vous avez déjà le ES_LOCAL_API_KEY dans le fichier start-local .env. Sinon, vous pouvez créer une clé API en utilisant l’interface Kibana, comme indiqué ici :

• Dans Kibana : Stack Management > Security > Clés API > Créer une clé API.

• Nous suggérons de définir uniquement les privilèges de lecture pour la clé API, en activant le privilège feature_agentBuilder.read comme indiqué ici.

• Copiez la valeur de la clé API encodée.

Définissez les variables d'environnement requises dans votre shell :

Installer l'ensemble de données d'exemple

Vous pouvez installer l'ensemble de données eCommerce orders disponible dans Kibana. Il comprend un seul index nommé kibana_sample_data_ecommerce, contenant des informations sur 4 675 commandes provenant d'un site web. Pour chaque commande, nous disposons des informations suivantes :

• Informations client (nom, identifiant, date de naissance, e-mail, etc.).

• Date de la commande.

• ID de commande.

• Produits (liste de tous les produits avec prix, quantité, identification, catégorie, réduction et autres détails).

• SKU.

• Prix total (hors taxes, taxes incluses).

• Quantité totale.

• Informations géographiques (ville, pays, continent, localisation, région).

Pour installer les données d'exemple, ouvrez la page Intégrations dans Kibana (recherchez « Intégrations » dans la barre de recherche supérieure) et installez l'ensemble de données « Échantillons de données ». Pour plus de détails, consultez la documentation ici.

Le but de cet article est de montrer à quel point il est facile de configurer la CLI Gemini pour se connecter à Elasticsearch et interagir avec l'index kibana_sample_data_ecommerce.

Comment utiliser le MCP d’Elasticsearch

Vous pouvez vérifier la connexion à l'aide de la commande suivante dans Gemini :

Le elastic-agent-builder devrait être activé, comme le montre la figure 2 :

Elasticsearch fournit un ensemble d'outils par défaut. Voir la description ici.

Grâce à ces outils, vous pouvez interagir avec Elasticsearch, en posant des questions telles que :

• Give me the list of all the indexes available in Elasticsearch.

• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

En fonction de la question, Gemini utilisera un ou plusieurs des outils disponibles pour tenter d'y répondre.

Les commandes /elastic

Dans l’extension Elasticsearch pour Gemini CLI, nous avons également ajouté/elastic commandes.

Si vous exécutez la commande /help, vous verrez toutes les options /elastic disponibles (Figure 3) :

Ces commandes peuvent être utiles si vous souhaitez exécuter directement un outil spécifique du serveur MCP elastic-agent-builder. Par exemple, en utilisant la commande suivante, vous pouvez obtenir le mapping de kibana_sample_data_ecommerce :

Ces commandes sont essentiellement des raccourcis permettant d’exécuter des outils spécifiques, plutôt que de s’en remettre au modèle Gemini pour déterminer l’outil à invoquer.

Comment utiliser les compétences Elasticsearch

Cette extension inclut également une compétence d’agent pour ES|QL, le langage de requête canalisé d’Elasticsearch (ES|QL) disponible dans Elasticsearch. Agent Skills est un format ouvert qui fournit aux agents IA de codage, comme Gemini CLI, des instructions personnalisées pour des tâches spécifiques. Ils utilisent un concept appelé divulgation progressive, ce qui signifie que seule une brève description de la compétence est ajoutée au prompt système initial. Lorsque vous demandez à l’agent d’effectuer une tâche, comme interroger Elasticsearch, il fait correspondre la requête à la compétence pertinente et charge dynamiquement les instructions détaillées. Il s’agit d’un moyen efficace de gérer les budgets de tokens tout en fournissant à l’IA exactement le contexte dont elle a besoin.

La compétence esqlest conçue pour permettre à Gemini CLI d’écrire et d’exécuter des requêtes ES|QL directement sur votre cluster. ES|QL est un langage de requête puissant qui rend l'exploration des données, l'analyse des logs et les agrégations très intuitives. Avec cette compétence activée, vous n'avez pas besoin de rechercher la syntaxe ES|QL ; vous pouvez simplement poser des questions en langage naturel à l'interface en ligne de commande Gemini sur vos données, et l'agent se chargera du reste.

Les exécutions sont réalisées à l'aide de simples commandes curl lancées dans un terminal. L’intégration d’Elasticsearch à n’importe quelle architecture est simplifiée par la richesse de ses API REST.

Ce que la compétenceesql offre :

• Recherche d'index et de schémas : L'agent peut utiliser les outils intégrés de la compétence pour dresser la liste des index disponibles et récupérer le mapping des champs. Par exemple, avant d’écrire une requête pour l’ensemble de données eCommerce, l’agent peut effectuer une exécution de vérification de schéma sur kibana_sample_data_ecommerce afin de comprendre les champs disponibles, comme taxful_total_price ou category.

• Traduction transparente en langage naturel : La compétence donne à l'agent plus qu'un simple manuel de référence ; elle lui fournit un guide spécifique pour interpréter l'intention de l'utilisateur. Dès que vous tapez une demande en langage naturel, par exemple « Afficher le temps de réponse moyen groupé par service », l’agent s’appuie sur les modèles intégrés de la compétence pour convertir vos mots en commandes, filtres et agrégations ES|QL appropriés.

• Autocorrection : en cas d’échec d’une requête (erreur de syntaxe ou de type, par exemple), la compétence transmet la requête ainsi que l’erreur Elasticsearch précise. L’agent peut alors la rectifier immédiatement et retenter l’opération sans que vous ayez à intervenir.

Comme la compétence esql est également disponible sous forme d'outil sur le serveur MCP elastic-agent-builder, nous devons désactiver ce serveur temporairement. Vous pouvez utiliser la commande suivante pour le désactiver :

Ensuite, vous pouvez simplement taper une invite comme celle-ci dans votre interface de ligne de commande Gemini :

L’agent devra :

• Reconnaissez la nécessité de la compétence esql.

• Consultez le schéma de kibana_sample_data_ecommerce.

• Construisez une requête ES|QL, comme : FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.

• Exécutez la requête auprès de l’API Elasticsearch.

• Présentez la réponse finale directement dans le terminal.

Nous avons cité ici un exemple de réponse de Gemini à la question précédente :

Il est intéressant de noter comment le modèle Gemini génère la réponse finale en montrant toutes les étapes qu’il suit. On peut voir ici l’influence de la compétence sur la démarche de réflexion du modèle. Dès que le modèle identifie la nécessité d’utiliser une compétence ou d’exécuter une commande shell, il sollicite une autorisation via l’approche supervision humaine dans la boucle.

Grâce à la gestion automatisée de la découverte de schéma, de la génération de requêtes et de leur exécution, la compétence esql vous libère des contraintes techniques pour vous focaliser uniquement sur l’analyse des résultats. Vous obtiendrez les données dont vous avez besoin, correctement formatées et directement dans votre terminal, sans jamais écrire une seule ligne de code ni basculer vers une autre application.

Conclusion

Dans cet article, nous avons présenté l'extension Elasticsearch pour Gemini CLI que nous avons récemment publiée. Cette extension vous permet d'interagir avec votre instance Elasticsearch en utilisant Gemini et le serveur Elasticsearch MCP fourni par Elastic Agent Builder, disponible à partir de la version 9.3.0, ainsi que la commande /elastic.

De plus, l'extension comprend également une compétence esql qui convertit la demande d'un utilisateur en langage naturel en une requête ES|QL. Cette compétence est très pratique quand l’usage du serveur MCP est impossible, puisque les échanges s’appuient sur l’exécution de commandes curl basiques dans le terminal. L’intégration d’Elasticsearch à tous vos projets est simplifiée par la richesse de ses API REST. C’est particulièrement utile lors du développement d’applications d’IA agentique.

Pour plus d’informations sur notre extension Gemini CLI, visitez le dépôt de projets ici.

Nous avons récemment contribué au projet open source Google MCP Toolbox for Databases en ajoutant la prise en charge d'Elasticsearch en tant que base de données.

Grâce à cette nouvelle fonctionnalité, vous pouvez désormais utiliser Google MCP Toolbox pour vous connecter à Elasticsearch et "dialoguer" directement avec vos données.

Elasticsearch

Nous avons besoin d'une instance Elasticsearch en cours d'exécution. Vous pouvez activer un essai gratuit sur Elastic Cloud ou l'installer localement via le script start-local :

Cela installera Elasticsearch et Kibana sur votre ordinateur et générera une clé API à utiliser pour configurer Google MCP Toolbox.

La clé API sera affichée comme sortie de la commande précédente et stockée dans un fichier .env dans le dossier elastic-start-local.

Installer l'ensemble de données d'exemple

Après l'installation, connectez-vous à Kibana en utilisant le nom d'utilisateur elastic et le mot de passe généré par le script "start-local" (stocké dans un fichier .env).

Vous pouvez installer l'ensemble de données eCommerce orders disponible dans Kibana. Il comprend un seul index nommé kibana_sample_data_ecommerce contenant des informations sur 4 675 commandes provenant d'un site web. Pour chaque commande, nous disposons des informations suivantes :

• Informations client (nom, identifiant, date de naissance, e-mail, etc.)

• Date de la commande

• ID de la commande

• Produits (liste de tous les produits avec prix, quantité, ID, catégorie, réduction, etc.)

• SKU

• Prix total (hors taxes, taxes incluses)

• Quantité totale

• Informations géographiques (ville, pays, continent, localisation, région)

Pour installer les données d'exemple, ouvrez la page Intégrations dans Kibana (recherchez "Integration" dans la barre de recherche supérieure), puis installez l'ensemble de données "Sample Data". Pour plus de détails, consultez la documentation ici : https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

Cet article a pour but de montrer combien il est facile de configurer Google MCP Toolbox pour se connecter à Elasticsearch et interagir avec l'index kibana_sample_data_ecommerce en utilisant le langage naturel.

Google MCP Toolbox

Google MCP Toolbox est un serveur MCP open source conçu pour faciliter l'interaction sécurisée et efficace des applications et des agents IA avec les bases de données. Auparavant appelé "GenAI Toolbox for Databases", le projet a été renommé après l'adoption d'une compatibilité totale avec le protocole MCP (Model Context Protocol). Son objectif est de supprimer les tâches complexes traditionnellement requises lors de la connexion d'agents à des bases de données en gérant en arrière-plan les pools de connexion, l'authentification, l'observabilité et d'autres aspects opérationnels.

Essentiellement, la boîte à outils permet aux développeurs de définir des outils réutilisables de haut niveau qui encapsulent les interactions avec la base de données. Ces outils peuvent ensuite être invoqués par n'importe quel client compatible MCP, tel qu'un agent IA, sans que le client n'ait à implémenter des requêtes SQL de bas niveau ni à gérer des connexions de base de données. Cette approche réduit considérablement la quantité de code répétitif nécessaire à la création d'agents compatibles avec les bases de données, permettant ainsi d'intégrer des opérations de données avancées en seulement quelques lignes de logique applicative. Une fois qu'un outil est défini, il peut être partagé entre plusieurs agents, frameworks, ou langages (Figure 1).

L'un des principaux avantages de la boîte à outils est le modèle de sécurité intégré. Les flux d'authentification tels que OAuth2 et OIDC sont pris en charge de manière native, ce qui permet aux développeurs d'éviter de manipuler ou de stocker des informations sensibles d'identification de base de données dans les agents. La plateforme fournit également des fonctionnalités d'observabilité via OpenTelemetry, y compris les métriques et le traçage, ce qui est essentiel pour le débogage, la surveillance et les déploiements en production. De manière générale, MCP Toolbox sert d'interface unifiée, sécurisée et extensible pour interagir avec vos données depuis n'importe quel système compatible MCP.

Comment installer MCP Toolbox

Vous pouvez installer le serveur MCP Toolbox sur Linux en utilisant la commande suivante :

Si vous souhaitez l'installer sur macOS ou Windows, vous pouvez suivre les instructions détaillées ici.

Configurer Toolbox pour Elasticsearch

Pour configurer MCP Toolbox pour Elasticsearch, nous devons créer un fichier tools.yaml comme suit :

Vous devez remplacer la valeur <insert-here-api-key> par une clé API Elasticsearch valide. Si vous exécutez Elasticsearch localement avec la commande "start-local", vous trouverez la clé API dans le fichier .env généré par start-local, sous la variable ES_LOCAL_API_KEY. Si vous utilisez Elastic Cloud, vous pouvez générer une clé API en suivant la procédure décrite ici.

Les outils précédents contiennent la requête ES|QL suivante pour Elasticsearch :

Si vous ne connaissez pas ES|QL, il s'agit d'un langage de requête développé par Elastic, similaire à SQL, qui peut être utilisé pour effectuer des recherches sur un ou plusieurs indices. Pour en savoir plus sur ES|QL, consultez la documentation officielle ici.

La requête ci-dessus recherche toutes les commandes stockées dans l'index kibana_sample_data_ecommerce qui contiennent le nom du client spécifié, en utilisant le paramètre ?name (le point d'interrogation indique un paramètre).

Le nom du client est défini dans la configuration YAML précédente en utilisant le type chaîne et la description "The customer name" (nom du client).

Cet outil peut être utilisé pour répondre à des questions sur les commandes d'un client, par exemple : Combien de commandes le client Foo a-t-il passées en octobre 2025 ?

Les descriptions des outils et de leurs paramètres sont essentielles pour extraire les informations pertinentes de la requête en langage naturel de l'utilisateur. Cette extraction est réalisée à l'aide de la capacité d'appel de fonctions d'un grand modèle de langage (LLM). En pratique, un LLM peut déterminer quelle fonction (outil) doit être exécutée pour obtenir les informations nécessaires, ainsi que les paramètres appropriés pour cette fonction.

Pour plus d'informations sur les appels de fonctions, nous vous invitons à lire l'article OpenAI function calling with Elasticsearch (en anglais) par Ashish Tiwari.

Exécuter le serveur Toolbox

Vous pouvez exécuter le serveur MCP Toolbox à l'aide du fichier "tools.yaml" précédent avec la commande suivante :

Le paramètre –ui exécute une application web à l'adresse http://127.0.0.1:5000/ui (Figure 2).

Sélectionnez Tools (Outils) > customer-orders et insérez un nom de client dans le paramètre name (par ex. Gwen Sanders), puis cliquez sur le bouton Run Tool (Exécuter l'outil). Une réponse JSON devrait s'afficher comme illustré dans la figure 3.

La configuration est terminée et MCP Toolbox peut exécuter l'outil customer-orders pour communiquer avec Elasticsearch, en lançant la requête ES|QL.

Utiliser MCP Toolbox avec Gemini CLI

Nous pouvons utiliser n'importe quel client MCP pour communiquer avec MCP Toolbox for Databases. Par exemple, nous pouvons choisir Gemini CLI, un outil en ligne de commande permettant d'utiliser Gemini. Si vous souhaitez installer Gemini CLI, suivez les instructions indiquées ici.

Gemini CLI propose une extension préconfigurée pour MCP Toolbox, disponible sur gemini-cli-extensions/mcp-toolbox. Vous pouvez installer cette extension en exécutant la commande suivante :

Après l'installation, vous devez accéder au répertoire dans lequel vous avez stocké le fichier de configuration "tools.yaml" pour MCP Toolbox et exécuter Gemini CLI comme suit (cette étape est nécessaire pour que Gemini CLI soit automatiquement configuré avec MCP Toolbox) :

Un message de sortie devrait s'afficher comme illustré dans la figure 4.

Vous pouvez vérifier si la boîte à outils MCP est connectée en utilisant la commande suivante :

Vous devriez voir s'afficher mcp_toolbox avec les outils customer-orders répertoriés (Figure 5).

Si MCP Toolbox est connecté à Gemini CLI, nous pouvons maintenant poser quelques questions, telles que : "Indiquez-moi les commandes pour la cliente Gwen Sanders". Gemini CLI demande alors l'autorisation d'exécuter l'outil "customer-orders" depuis le serveur mcp_toolbox (voir Figure 6).

Après confirmation, Gemini CLI exécute la requête dans MCP Toolbox, reçoit une réponse JSON et l'utilise pour mettre en forme la réponse (Figure 7).

La réponse de Gemini CLI indique que Gwen Sanders a passé une seule commande de 2 produits, pour un prix total de 132 EUR.

SDK MCP Toolbox

Google MCP Toolbox propose également un SDK pour accéder à toutes les fonctionnalités depuis un programme écrit en Go, Python et Javascript.

Par exemple, le SDK Python est disponible sur Github à la page suivante : https://github.com/googleapis/mcp-toolbox-sdk-python.

Nous devons créer un agent simple pour nous connecter à MCP Toolbox. Nous devons installer les packages suivants :

Et créer un nouveau projet d'agent à l'aide la commande suivante :

Cela créera un nouveau répertoire nommé my_agent contenant un fichier agent.py.

Mettez à jour le fichier my_agent/agent.py avec le contenu suivant pour vous connecter à Toolbox :

Créez un fichier .env avec votre clé API Google :

Enfin, nous pouvons lancer l'exécution de l'agent et observer les résultats. Pour ce faire, exécutez la commande suivante :

Ou, vous pouvez le servir via une interface web :

Dans les deux cas, vous pouvez interagir avec MCP Toolbox à l'aide d'une interface de questions-réponses. Par exemple, vous pouvez poser la question précédente : Indiquez-moi les commandes de la cliente Gwen Sanders.

Pour plus d'informations sur les différents SDK, consultez cette page de documentation.

Conclusion

Dans cet article, nous avons démontré l'intégration d'Elasticsearch pour Google MCP Toolbox for Databases. À l'aide d'un simple fichier de configuration YAML, nous pouvons définir un ensemble d'outils qui traduisent les questions en langage naturel en requêtes Elasticsearch en utilisant le langage ES|QL.

Nous avons montré comment interagir avec l'ensemble de données "kibana_sample_data_ecommerce", qui contient des commandes provenant d'un site web. Avec ce fichier de configuration, nous pouvons simplement lancer l'exécution du serveur MCP Toolbox et nous y connecter depuis n'importe quel client MCP.

Enfin, nous avons démontré comment utiliser Gemini CLI en tant que client pour nous connecter à MCP Toolbox for Databases et interroger les données e-commerce stockées dans Elasticsearch. Nous avons exécuté une requête en langage naturel pour récupérer des informations sur les commandes d'un client spécifique identifié par son nom.

À mesure que l'écosystème MCP se développe, ce modèle – des définitions d'outils légères soutenues par une infrastructure sécurisée et prête pour la production – crée de nouvelles possibilités pour construire des agents de plus en plus performants et sensibles aux données avec un minimum d'efforts. Qu'il s'agisse d'expérimenter localement les ensembles de données Elastic ou d'intégrer des fonctionnalités de recherche dans une application plus vaste, MCP Toolbox fournit une base fiable et extensible pour interagir avec vos données Elasticsearch en langage naturel.

Pour en savoir plus sur le développement d'applications d'IA agentique, consultez l'article Construire des workflows d'IA agentique avec Elasticsearch par Anish Mathur et Dana Juratoni.

Pour plus d'informations sur Google MCP Toolbox, consultez la page vhttps://googleapis.github.io/genai-toolbox/getting-started/introduction/.

ES|QL

ES|QL est un nouveau langage de requête Elasticsearch introduit dans Elasticsearch 8.11.0. Pour l'instant, il est disponible en aperçu technique. Il offre un moyen puissant de filtrer, de transformer et d'analyser les données stockées dans Elasticsearch.

Il utilise les tuyaux "" (|) pour manipuler et transformer les données étape par étape. Cette approche permet aux utilisateurs de composer une série d'opérations, où la sortie d'une opération devient l'entrée de la suivante, ce qui permet des transformations et des analyses de données complexes.

Par exemple, la requête suivante renvoie les 3 premiers documents (lignes) de l'index sample_data:

Cas d'utilisation : Fonctionnalités ES|QL dans le client PHP officiel

Pour illustrer les fonctionnalités ES|QL développées dans le client PHP officiel, nous avons stocké dans Elasticsearch un fichier CSV de 81 828 livres (54,4 Mo) contenant les informations suivantes :

Nous avons extrait cette liste de l' ensemble de données publiques Amazon Books Reviews.

Nous avons créé un index books avec les mappings Elasticsearch suivants :

La valeur rating est la moyenne des avis de classement tirés du fichier Books_rating.csv de 2,9 Go.

Vous trouverez ici le script PHP que nous avons utilisé pour importer en masse tous les livres dans Elasticsearch. L'opération en bloc a pris 7 secondes et 28 Mo de RAM en utilisant PHP 8.2.17. Avec le mappage proposé, la taille de l'index dans Elasticsearch est d'environ 62 Mo.

Mapper les résultats ES|QL vers un objet PHP ou une classe personnalisée

Nous pouvons exécuter une requête ES|QL en PHP en utilisant le point de terminaison esql()->query(). Le résultat de cette requête est une structure de données sous forme de tableau. Ceci est exprimé en JSON à l'aide des champs columns et values. Dans le champ columns, nous avons les définitions name et type.

Voici un exemple de requête ES|QL permettant d'obtenir les 10 meilleurs livres écrits par Stephen King, classés par ordre d'appréciation des utilisateurs :

Le résultat JSON d'Elasticsearch se présente comme suit :

Dans cet exemple, nous avons 6 propriétés (auteur, description, éditeur, note, titre, année) liées à un livre et 10 résultats, tous des livres de Stephen King.

Une liste de tous les types pris en charge dans ES|QL est présentée ici.

L'objet de réponse $result est accessible sous la forme d'un tableau, d'une chaîne de caractères ou d'un objet (voir ici pour plus d'informations).

L'interface objet permet d'accéder aux valeurs à l'aide de propriétés et d'index. Par exemple, $result->values[0][4] renvoie le titre (4) du premier livre (0) de la liste, $result->values[1][3] renvoie le rang (3) du deuxième livre (1), etc. Rappelez-vous que l'index d'un tableau en PHP commence à zéro.

Cette interface peut être suffisante pour certains cas d'utilisation, mais la plupart du temps, nous aimerions avoir un tableau d'objets comme résultat.

Pour convertir le résultat en un tableau d'objets, nous pouvons utiliser la nouvelle fonction mapTo() d'elasticsearch-php.

Cette fonction est disponible directement dans l'objet de réponse Elasticsearch. Cela signifie que vous pouvez y accéder de la manière suivante :

Si vous disposez d'une classe de livre personnalisée, vous pouvez mapper le résultat en l'utilisant, comme suit :

Si votre classe possède d'autres propriétés en plus de celles incluses dans le résultat ES|QL, cela fonctionnera également. La fonction mapTo() n'utilisera que les propriétés renvoyées sous forme de colonnes dans le résultat ES|QL.

Vous pouvez télécharger tous les exemples présentés dans cet article ici.