Comment créer des applications d'IA agentique avec Mastra et Elasticsearch

Dans cet article, nous allons voir comment utiliser le framework Mastra TypeScript pour créer des applications agentiques qui interagissent avec Elasticsearch.

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.