Wir haben kürzlich zum Open-Source-Projekt mastra-ai/mastra beigetragen, indem wir Unterstützung für Elasticsearch als Vektordatenbank hinzugefügt haben. Mit diesem neuen Feature können Sie Elasticsearch nativ in Mastra verwenden, um Einbettungen zu speichern. Zusätzlich zu Vektoren bietet Elasticsearch eine Reihe erweiterter Features, die alle Ihre Anforderungen an das Kontext-Engineering erfüllen. (zum Beispiel hybride Suche und Reranking).

Dieser Artikel beschreibt die Erstellung eines Agenten zur Implementierung einer RAG-Architektur (Retrieval-Augmented Generation) mit Elasticsearch. Wir stellen ein Demoprojekt vor, bei dem ein agentischer Ansatz verwendet wird, um mit einem in Elasticsearch gespeicherten Korpus von Science-Fiction-Filmdaten zu interagieren. Das Projekt ist unter elastic/mastra-elasticsearch-example verfügbar.

Mastra

Mastra ist ein TypeScript-Framework zur Erstellung agentischer KI-Anwendungen.

Eine Projektstruktur in Mastra sieht wie folgt aus:

In Mastra können Sie Agenten, Tools, Workflows und Scores erstellen.

Ein Agent ist eine Klasse, die eine Nachricht als Eingabe akzeptiert und eine Antwort als Ausgabe erzeugt. Ein Agent kann Tools, Large Language Models (LLMs) und einem Speicher verwenden (Abbildung 1).

Die Tools eines Agenten ermöglichen ihm die Interaktion mit der „Außenwelt“, beispielsweise die Kommunikation mit einer Web-API oder die Durchführung einer internen Operation, wie etwa das Abfragen von Elasticsearch. Die Speicherkomponente ist entscheidend für die Speicherung des Konversationsverlaufs, einschließlich früherer Ein- und Ausgaben. Dank dieser gespeicherten Kontextinformationen kann der Agent anhand früherer Interaktionen fundiertere und relevantere Antworten auf künftige Fragen geben.

Workflows ermöglichen Ihnen die Definition komplexer Aufgabenabläufe anhand klarer, strukturierter Schritte, anstatt sich auf die Argumentation eines einzelnen Agenten zu verlassen (Abbildung 2). Sie geben Ihnen die volle Kontrolle über die Aufteilung von Aufgaben, den Datenaustausch zwischen ihnen und den Zeitpunkt der Ausführung. Workflows werden standardmäßig über die integrierte Ausführungs-Engine ausgeführt oder können auf Workflow-Runner bereitgestellt werden.

In Mastra können Sie außerdem Scores definieren. Dabei handelt es sich um automatisierte Tests, die die Ausgaben der Agenten mithilfe modellbasierter, regelbasierter und statistischer Methoden bewerten. Scorer geben Scores zurück: numerische Werte (in der Regel zwischen 0 und 1), die messen, wie gut eine Ausgabe Ihre Bewertungskriterien erfüllt. Diese Scores ermöglichen Ihnen eine objektive Leistungsüberwachung, den Vergleich verschiedener Ansätze und die Ermittlung von Verbesserungsmöglichkeiten in Ihren KI-Systemen. Scorer können mit Ihren eigenen Prompts und Scoring-Funktionen angepasst werden.

Elasticsearch

Für die Ausführung des Demoprojekts benötigen wir eine laufende Elasticsearch-Instanz. Sie können eine kostenlose Testversion von Elastic Cloud aktivieren oder Elasticsearch lokal mithilfe des Skripts start-local installieren:

Dadurch werden Elasticsearch und Kibana auf Ihrem Computer installiert und ein API-Schlüssel generiert, der zur Konfiguration der Mastra-Integration verwendet wird.

Der API-Schlüssel wird als Ausgabe des vorherigen Befehls angezeigt und in einer .env-Datei im Ordner elastic-start-local gespeichert.

Demo installieren und konfigurieren

Wir haben ein Elastic/mastra-elasticsearch-example-Repository erstellt, das den Quellcode des Demoprojekts enthält. Das im Repository bereitgestellte Beispiel veranschaulicht, wie Sie in Mastra einen Agenten erstellen, der eine RAG-Architektur zum Abrufen von Dokumenten aus Elasticsearch implementiert.

Wir haben für die Demo einen Datensatz zu Science-Fiction-Filmen bereitgestellt. Wir haben 500 Filme aus dem IMDb-Datensatz auf Kaggle extrahiert.

Der erste Schritt besteht in der Installation der Abhängigkeiten des Projekts mit npm. Verwenden Sie dazu den folgenden Befehl:

Anschließend müssen wir die .env-Datei konfigurieren, die die Einstellungen enthalten wird. Wir können diese Datei generieren, indem wir die Struktur aus der .env.example-Datei mit folgendem Befehl kopieren:

Nun können wir die .env-Datei bearbeiten, indem wir die fehlenden Informationen hinzufügen:

Der Name des Elasticsearch-Index lautet scifi-movies. Auf Wunsch können Sie ihn mithilfe der .env-Variablen ELASTICSEARCH_INDEX_NAME ändern.

Wir haben OpenAI als Einbettungsdienst verwendet, was bedeutet, dass Sie einen API-Schlüssel für OpenAI in der .env-Variablen OPENAI_API_KEY angeben müssen.

Das im Beispiel verwendete Einbettungsmodell ist openai/text-embedding-3-small, mit einer Einbettungsdimension von 1536.

Zur Generierung der endgültigen Antwort haben wir das Modell openai/gpt-5-nano verwendet, um die Kosten zu senken.

Die RAG-Architektur ermöglicht die Verwendung eines weniger leistungsfähigen (und in der Regel kostengünstigeren) finalen LLM-Modells, da die Hauptarbeit der Beantwortung durch die Retrieval-Komponente (in diesem Fall Elasticsearch) erledigt wird.

Das kleinere LLM ist nur für zwei Hauptaufgaben zuständig:

• Umformulierung/Einbettung der Abfrage: Umwandlung der in natürlicher Sprache formulierten Frage des Nutzers in eine Vektoreinbettung für die semantische Suche.

• Antwortsynthese: Die relevanten, abgerufenen Kontextfragmente (Dokumente/Filme) werden gemäß den vorgegebenen Anweisungen zu einer kohärenten, endgültigen und für Menschen lesbaren Antwort zusammengeführt.

Da der RAG-Prozess den genauen sachlichen Kontext liefert, der für die Antwort benötigt wird, muss das endgültige LLM weder umfangreich noch hochkomplex sein und es muss nicht das gesamte erforderliche Wissen innerhalb seiner eigenen Parameter besitzen (was die Stärke großer, teurer Modelle ist). Es fungiert im Wesentlichen als ausgeklügelter Textzusammenfasser und -formatierer für den von Elasticsearch bereitgestellten Kontext und nicht als vollwertige Wissensdatenbank an sich. Auf diese Weise lassen sich Modelle wie gpt-5-nano zur Kosten- und Latenzoptimierung verwenden.

Nach der Konfiguration der .env-Datei können Sie die Filme mithilfe des folgenden Befehls in Elasticsearch ingestieren:

Der Ausgabe sollte wie folgt aussehen:

Das Mapping des Science-Fiction-Filmindex enthält die folgenden Felder:

• Einbettung, dense_vector mit 1536 Dimensionen, Kosinus-Ähnlichkeit.

• Beschreibung, Text mit der Beschreibung des Films.

• Regisseur, Text mit dem Namen des Regisseurs.

• Titel Text mit dem Titel des Films.

Wir haben die Einbettungen anhand des Titels und der Beschreibung generiert. Da Titel und Beschreibung zwei separate Felder sind, stellt die Verknüpfung beider sicher, dass der resultierende Einbettungsvektor sowohl die spezifische, einzigartige Identität (Titel) als auch den reichhaltigen, beschreibenden Kontext (Beschreibung) des Films erfasst, was zu genaueren und umfassenderen semantischen Suchergebnissen führt. Durch diese kombinierte Eingabe erhält das Einbettungsmodell eine bessere einheitliche Darstellung des Dokumentinhalts für den Ähnlichkeitsabgleich.

Demo ausführen

Sie können die Demo mit folgendem Befehl ausführen:

Dieser Befehl startet eine Webanwendung unter localhost:4111, um auf Mastra Studio zuzugreifen (Abbildung 3).

Mastra Studio bietet eine interaktive Benutzeroberfläche zum Erstellen und Testen Ihrer Agenten sowie eine REST-API, die Ihre Mastra-Anwendung als lokalen Dienst bereitstellt. So können Sie sofort mit der Entwicklung beginnen, ohne sich Gedanken über die Integration machen zu müssen.

Wir haben einen Elasticsearch-Agenten bereitgestellt, der das createVectorQueryTool von Mastra als Tool zur Ausführung semantischer Suchen mit Elasticsearch verwendet. Dieser Agent verwendet den RAG-Ansatz, um relevante Dokumente (d. h. Filme) zu suchen, die die Frage des Nutzers beantworten.

Dieser Agent verwendet folgenden Prompt:

Wenn Sie auf das Menü Mastra Studio > Agents klicken und Elasticsearch-Agent auswählen, können Sie den Agenten über ein Chatsystem testen. Zum Beispiel können Sie Informationen zu Science-Fiction-Filmen mit folgender Frage stellen:

Finden Sie 5 Filme oder Fernsehserien über UFOs.

Sie werden bemerken, dass der Agent das vectorQueryTool ausführen wird. Sie können auf das aufgerufene Tool klicken, um sich die Eingabe und die Ausgabe anzusehen. Am Ende der Ausführung beantwortet das LLM Ihre Frage unter Berücksichtigung des Kontexts aus dem „scifi-movies“-Index von Elasticsearch (Abbildung 4).

Mastra führt intern folgende Schritte aus:

1. Vektorumwandlung: Die Frage des Nutzers, Finde 5 Filme oder TV-Serien über UFOs, wird mithilfe des Modells openai/text-embedding-3-small von OpenAI in eine Vektoreinbettung umgewandelt.

2. Vektorsuche: Diese Einbettung wird dann verwendet, um Elasticsearch über eine Vektorsuche abzufragen.

3. Ergebnisabruf: Elasticsearch gibt eine Liste von 10 Filmen zurück, die für die Suchanfrage besonders relevant sind (d. h. die Filme, deren Vektoren dem Suchvektor des Nutzers am nächsten liegen).

4. Antwortgenerierung: Die abgerufenen Filme und die ursprüngliche Nutzerfrage werden an das LLM gesendet, speziell openai/gpt-5-nano. Das LLM verarbeitet diese Informationen und generiert eine endgültige Antwort, um sicherzustellen, dass die Anfrage des Nutzers nach fünf Ergebnissen erfüllt wird.

Der Elasticsearch-Agent

Hier haben wir den Quellcode des Elasticsearch-Agenten veröffentlicht.

Das vectorQueryTool ist das Tool, das zur Implementierung des Abrufteils des RAG-Beispiels aufgerufen wird. Es verwendet die ElasticSearchVector-Implementierung, die Elastic zu Mastra beigetragen hat.

Der Agent ist ein Objekt der Agentenklasse, das das vectorQueryTool, den Prompt und einen Speicher verbraucht. Wie Sie sehen können, ist der Code, den wir für die Verbindung von Elasticsearch mit einem Agenten implementieren müssen, sehr minimal.

Fazit

Dieser Artikel verdeutlichte die Einfachheit und Leistungsfähigkeit der Integration von Elasticsearch in das Mastra-Framework zur Entwicklung komplexer agentischer KI-Anwendungen. Konkret haben wir gezeigt, wie ein RAG-Agent erstellt wird, der eine semantische Suche in einem Korpus von Science-Fiction-Filmdaten durchführen kann, die in Elasticsearch indiziert sind.

Ein wichtiger Aspekt ist der direkte Beitrag von Elastic zum Open-Source-Projekt Mastra, der native Unterstützung für Elasticsearch als Vektorspeicher bietet. Diese Integration senkt die Einstiegshürde erheblich, wie der Quellcode des Elasticsearch-Agenten zeigt. Mit der Verwendung von ElasticSearchVector und createVectorQueryTool benötigt die vollständige Einrichtung für die Verbindung von Elasticsearch mit Ihrem Agenten nur wenige Zeilen Konfigurationscode.

Elasticsearch bietet verschiedene erweiterte Features zur Verbesserung der Ergebnisrelevanz. Zum Beispiel steigert die hybride Suche die Genauigkeit erheblich, indem die lexikalische Suche mit Vektorsuche kombiniert wird. Ein weiteres interessantes Feature ist das Reranking mit den neuesten Jina-Modellen, die am Ende der hybriden Suche angewendet werden können. Weitere Informationen zu diesen Technologien finden Sie in den folgenden Artikeln von Elasticsearch Labs:

• Elasticsearch Hybrides Suchen von Valentin Crettaz

• Einführung in Jina-Modelle, ihre Funktionen und ihre Verwendung in Elasticsearch von Scott Martens

Wir empfehlen Ihnen außerdem, sich das bereitgestellte Beispiel anzusehen und damit zu beginnen, Ihre eigenen datengestützten Agenten mit Mastra und Elasticsearch zu entwickeln. Weitere Informationen zu Mastra finden Sie hier in der offiziellen Dokumentation.

Die Erweiterung ist hier als Open-Source-Projekt verfügbar.

Was ist Gemini CLI, und wie installieren Sie sie?

Gemini CLI ist ein Open-Source-KI-Agent, der Googles Gemini-Modelle direkt in die Befehlszeile bringt. Er ermöglicht Entwicklern, über das Terminal mit KI zu interagieren, um Aufgaben wie das Generieren von Code, das Bearbeiten von Dateien, das Ausführen von Shell-Befehlen und das Abrufen von Informationen aus dem Web durchzuführen.

Im Gegensatz zu typischen Chat-Schnittstellen integriert sich die Gemini CLI in Ihre lokale Entwicklungsumgebung. Das bedeutet, dass sie den Projektkontext versteht, Dateien ändert, Builds oder Tests ausführt und Workflows direkt im Terminal automatisiert. Dies macht sie besonders nützlich für Entwickler, Site Reliability Engineers (SREs) und Engineers, die KI-gestütztes Codieren und Automatisierung wünschen, ohne ihren Befehlszeilen-Workflow zu verlassen.

Gemini CLI kann mit mehreren Paketmanagern installiert werden. Die gängigste Methode ist die Installation über npm:

Wenn Sie sich über alternative Installationsmöglichkeiten informieren möchten, lesen Sie die offizielle Installationsseite.

Starten Sie die CLI nach der Installation durch Ausführen des folgenden Befehls:

Sie sehen einen Bildschirm, wie in Abbildung 1 dargestellt:

Elasticsearch konfigurieren

Wir benötigen eine laufende Elasticsearch-Instanz. Wenn Sie den Model Context Protocol (MCP)-Server verwenden möchten, benötigen Sie zudem Kibana 9.3+. Für die Nutzung der unten beschriebenen Elasticsearch Query Language (ES|QL)-Fähigkeit (esql) ist Kibana nicht erforderlich.

Sie können eine kostenlose Testversion auf Elastic Cloud aktivieren oder es lokal mit dem start-local-Skript installieren:

Dadurch werden Elasticsearch und Kibana auf Ihrem Computer installiert und ein API-Schlüssel generiert, den Sie für die Konfiguration von Gemini CLI verwenden können.

Der API-Schlüssel wird als Ausgabe des vorherigen Befehls angezeigt und in einer .env-Datei im Ordner elastic-start-local gespeichert.

Wenn Sie Elasticsearch lokal (zum Beispiel start-local), und Elastic Agent Builder mit MCP verwenden möchten, müssen Sie auch ein Large Language Model (LLM) verbinden. Lesen Sie diese Dokumentationsseite, um sich über die verschiedenen Optionen zu informieren.

Wenn Sie Elastic Cloud (oder serverless) verwenden, verfügen Sie bereits über eine vorgefertigte LLM-Verbindung.

Installieren Sie die Elasticsearch-Erweiterung

Sie können die Elasticsearch-Erweiterung für Gemini CLI mit folgendem Befehl installieren:

Sie können überprüfen, ob die Erweiterungen erfolgreich installiert wurden, indem Sie Gemini öffnen und den folgenden Befehl ausführen:

Die Elasticsearch-Erweiterung sollte verfügbar sein.

Wenn Sie die MCP-Integration verwenden möchten, müssen Sie die Elasticsearch-Version 9.3 oder höher installiert haben. Sie benötigen die URL Ihres MCP-Servers aus Kibana:

• Sie erhalten Ihre MCP-Server-URL unter Agenten > Alle Tools anzeigen > MCP verwalten > MCP-Server-URL kopieren.

• Die URL wird so aussehen: https://your-kibana-instance/api/agent_builder/mcp

Sie benötigen die URL des Elasticsearch-Endpoints. Dies wird üblicherweise oben auf der Kibana Elasticsearch-Seite angezeigt. Wenn Sie Elasticsearch mit start-local ausführen, ist der Endpoint bereits im Schlüssel ES_LOCAL_URL in der .env-Datei start-local hinterlegt.

Sie benötigen auch einen API-Schlüssel. Wenn Sie Elasticsearch mit start-local ausführen, ist der ES_LOCAL_API_KEY in der .env-Datei start-local hinterlegt. Andernfalls können Sie einen API-Schlüssel über die Kibana-Schnittstelle erstellen, wie hier beschrieben:

• In Kibana: Stack Management > Sicherheit > API-Schlüssel > API-Schlüssel erstellen.

• Wir empfehlen, nur die Leserechte für den API-Schlüssel festzulegen und so die hier beschriebene Berechtigung feature_agentBuilder.read zu aktivieren.

• Kopieren Sie den codierten API-Schlüsselwert.

Stellen Sie die erforderlichen Umgebungsvariablen in Ihrer Shell ein:

Installieren Sie den Beispieldatensatz

Sie können den Datensatz für E-Commerce-Bestellungen , der von Kibana verfügbar ist, installieren. Sie enthält einen einzigen Index mit dem Namen kibana_sample_data_ecommerce, der Informationen für 4.675 Bestellungen von einer E-Commerce-Website enthält. Für jede Bestellung haben wir folgende Informationen:

• Kundeninformationen (Name, Ausweis, Geburtsdatum, E-Mail-Adresse und mehr)

• Bestelldatum

• Bestell-ID

• Produkte (Liste aller Produkte mit Preis, Menge, ID, Kategorie, Rabatt und weiteren Details)

• SKU

• Gesamtpreis (ohne Steuern, mit Steuern)

• Gesamtmenge

• Geoinformationen (Stadt, Land, Kontinent, Ort, Region)

Um die Beispieldaten zu installieren, öffnen Sie die Seite Integrationen in Kibana (suchen Sie in der Suchleiste oben nach „Integration") und installieren Sie die Beispieldaten. Weitere Einzelheiten finden Sie in der Dokumentation hier.

Ziel dieses Artikels ist es, zu zeigen, wie einfach es ist, die Gemini CLI so zu konfigurieren, dass sie mit Elasticsearch verbunden ist und mit dem Index kibana_sample_data_ecommerce interagiert.

Verwendung des Elasticsearch MCP

Sie können die Verbindung mit folgendem Befehl in Gemini überprüfen:

Sie sollten sehen, dass elastic-agent-builder aktiviert ist, wie in Abbildung 2 dargestellt:

Elasticsearch bietet eine Reihe von Standardtools. Sehen Sie sich die Beschreibung hier an.

Mithilfe dieser Tools können Sie mit Elasticsearch interagieren und Fragen stellen wie:

• 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?

Je nach Frage wird Gemini eines oder mehrere der verfügbaren Tools verwenden, um sie zu beantworten.

Die /elastic-Befehle

In der Elasticsearch-Erweiterung für Gemini CLI haben wir auch/elastic-Befehlehinzugefügt.

Wenn Sie den Befehl /help ausführen, werden Ihnen alle verfügbaren /elastic-Optionen angezeigt (Abbildung 3):

Diese Befehle können nützlich sein, wenn Sie ein bestimmtes Tool des elastic-agent-builder-MCP-Servers direkt ausführen möchten. Beispielsweise können Sie mit dem folgenden Befehl das Mapping von kibana_sample_data_ecommerce abrufen:

Diese Befehle sind im Wesentlichen Abkürzungen für das Ausführen spezifischer Tools, anstatt sich auf das Gemini-Modell zu verlassen, um zu bestimmen, welches Tool aufgerufen werden sollte.

Verwendung der Elasticsearch-Fähigkeiten

Diese Erweiterung beinhaltet außerdem eine agentische Fähigkeit für ES|QL, die in Elasticsearch verfügbare Elasticsearch Query Language. Agentische Fähigkeiten stellen ein offenes Format dar, das KI-Coding-Agenten wie Gemini CLI individuelle Anweisungen für bestimmte Aufgaben gibt. Sie verwenden ein Konzept namens Progressive Disclosure (progressive Offenlegung), was bedeutet, dass der anfänglichen Systemaufforderung nur eine kurze Beschreibung der Fähigkeit hinzugefügt wird. Wenn Sie den Agenten bitten, eine Aufgabe auszuführen, wie etwa eine Abfrage an Elasticsearch, passt er die Anfrage an die relevante Fähigkeit an und lädt dynamisch die detaillierten Anweisungen. Dies ist eine effiziente Methode, um Token-Budgets zu verwalten und der KI genau den Kontext bereitzustellen, den sie benötigt.

Die esql-Fähigkeit ist so konzipiert, dass Gemini CLI ES|QL-Abfragen direkt in Ihrem Cluster schreiben und ausführen kann. ES|QL ist eine leistungsstarke Abfragesprache, die die Datenexploration, die Log-Analyse und die Aggregationen sehr intuitiv macht. Wenn diese Fähigkeit aktiviert ist, müssen Sie nicht nach der ES|QL-Syntax suchen; Sie können der Gemini CLI einfach Fragen zu Ihren Daten in natürlicher Sprache stellen, und der Agent kümmert sich um den Rest.

Die Ausführung erfolgt mit einfachen curl-Befehlen, die in einem Terminal ausgeführt werden. Dies ist möglich, da Elasticsearch eine umfangreiche Sammlung von REST APIs bereitstellt, die sich problemlos in jede beliebige Architektur integrieren lassen.

Was die esql Fähigkeit bietet:

• Erkennung von Indizes und Schemata: Der Agent kann die integrierten Tools der Fähigkeit nutzen, um verfügbare Indizes aufzulisten und Feld-Mappings abzurufen. Bevor der Agent beispielsweise eine Abfrage für die E-Commerce-Datensätze schreibt, kann er eine Schema-Prüfung für kibana_sample_data_ecommerce ausführen, um die verfügbaren Felder wie taxful_total_price oder category zu ermitteln.

• Nahtlose Übersetzung natürlicher Sprache: Diese Fähigkeit bietet dem Agenten mehr als nur ein einfaches Nachschlagewerk; sie liefert eine konkrete Anleitung zur Interpretation der Nutzerabsicht. Wenn Sie Anfragen in natürlicher Sprache eingeben, wie „Zeige durchschnittliche Reaktionszeit gruppiert nach Service“, nutzt der Agent die in der Fähigkeit integrierte Mustererkennung, um Ihre Worte sofort in die richtigen ES|QL-Aggregationen, Filter und Befehle umzuwandeln.

• Selbstkorrektur: Wenn eine Abfrage fehlschlägt (zum Beispiel wegen eines Typfehlers oder eines Syntaxfehlers), gibt die Fähigkeit die generierte Abfrage zusammen mit der genauen Elasticsearch-Fehlermeldung zurück, sodass der Agent die Abfrage sofort beheben und erneut ausführen kann, ohne dass Sie eingreifen müssen.

Da die esql-Fähigkeit auch als Tool auf dem elastic-agent-builder-MCP-Server verfügbar ist, müssen wir diesen Server vorübergehend deaktivieren. Sie können sie mit dem folgendem Befehl deaktivieren:

Dann können Sie einfach einen Befehl wie diesen in Ihre Gemini CLI eingeben:

Der Agent wird:

• Die Notwendigkeit der esql-Fähigkeit erkennen

• Überprüfen Sie das Schema von kibana_sample_data_ecommerce.

• Eine ES|QL-Abfrage erstellen wie: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5

• Die Abfrage über die Elasticsearch-API ausführen

• Das Ergebnis Ihnen direkt im Terminal anzeigen

Hier haben wir ein Beispiel für die Antwort von Gemini auf die vorherige Eingabe aufgeführt:

Es ist interessant festzustellen, wie das Gemini-Modell die endgültige Antwort generiert, indem es alle Schritte zeigt, die es dabei durchläuft. Hier können Sie deutlich den Einfluss der Fähigkeit auf den Denkprozess des Modells erkennen. Wenn das Modell zum ersten Mal erkennt, dass es eine Fähigkeit verwenden oder einen Shell-Befehl ausführen muss, erfragt es die Genehmigung mithilfe des Human-in-the-Loop-Ansatzes.

Durch die Übernahme der aufwendigen Aufgaben der Schemaerkennung, Abfragegenerierung und -ausführung ermöglicht Ihnen die esql-Fähigkeit, sich voll und ganz auf die Antworten zu konzentrieren, anstatt auf die Mechanismen ihrer Ermittlung. Sie erhalten die Daten, die Sie benötigen, richtig formatiert und direkt in Ihrem Terminal, ohne jemals eine einzige Zeile Syntax zu schreiben oder zu einer anderen Anwendung zu wechseln.

Fazit

In diesem Artikel haben wir die kürzlich veröffentlichte Elasticsearch-Erweiterung für die Gemini CLI vorgestellt. Mit dieser Erweiterung können Sie über Gemini und den von Elastic Agent Builder bereitgestellten Elasticsearch-MCP-Server, der ab Version 9.3.0 verfügbar ist, sowie über den Befehl /elastic mit Ihrer Elasticsearch-Instanz interagieren.

Darüber hinaus enthält die Erweiterung auch eine esql-Fähigkeit, die die Anfrage eines Nutzers von der natürlichen Sprache in eine ES|QL-Abfrage umwandelt. Diese Fähigkeit kann besonders nützlich sein, wenn der MCP-Server nicht genutzt werden kann, da die zugrundeliegende Kommunikation durch einfache Curl-Befehle in einem Terminal gesteuert wird. Elasticsearch bietet eine umfangreiche Auswahl an REST APIs, die leicht in jedes Projekt integriert werden können. Dies ist besonders nützlich bei der Entwicklung von agentischen KI-Anwendungen.

Weitere Informationen zu unserer Gemini CLI-Erweiterung finden Sie hier im Projekt-Repository.

Wir haben vor Kurzem zum Open-Source-Projekt Google MCP Toolbox for Databases beigetragen, indem wir Unterstützung für Elasticsearch als Datenbank hinzugefügt haben.

Mit diesem neuen Feature können Sie jetzt die Google MCP Toolbox verwenden, um eine Verbindung zu Elasticsearch herzustellen und direkt mit Ihren Daten zu „kommunizieren“.

Elasticsearch

Wir benötigen eine laufende Elasticsearch-Instanz. Sie können eine kostenlose Testversion auf Elastic Cloud aktivieren oder es lokal mit dem start-local-Skript installieren:

Dadurch werden Elasticsearch und Kibana auf Ihrem Computer installiert und ein API-Schlüssel generiert, der zur Konfiguration der Google MCP Toolbox verwendet wird.

Der API-Schlüssel wird als Ausgabe des vorherigen Befehls angezeigt und in einer .env-Datei im Ordner elastic-start-local gespeichert.

Installieren Sie den Beispieldatensatz

Nach der Installation können Sie sich mit dem Benutzernamen elastic und dem vom start-local-Skript generierten Passwort (gespeichert in einer .env-Datei) bei Kibana anmelden.

Sie können den Datensatz für E-Commerce-Bestellungen , der von Kibana verfügbar ist, installieren. Sie enthält einen einzigen Index namens kibana_sample_data_ecommerce, der Informationen über 4.675 Bestellungen von einer E-Commerce-Website enthält. Für jede Bestellung haben wir folgende Informationen:

• Kundeninformationen (Name, Ausweis, Geburtsdatum, E-Mail-Adresse usw.)

• Bestelldatum

• Bestell-ID

• Produkte (Liste aller Produkte mit Preis, Menge, ID, Kategorie, Rabatt usw.)

• SKU

• Gesamtpreis (ohne Steuern, mit Steuern)

• Gesamtmenge

• Geoinformationen (Stadt, Land, Kontinent, Ort, Region)

Um die Beispieldaten zu installieren, öffnen Sie die Seite Integrationen in Kibana (suchen Sie in der Suchleiste oben nach „Integration“) und installieren Sie die „Beispieldaten“. Weitere Details finden Sie in der Dokumentation hier: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

Ziel dieses Artikels ist es, zu zeigen, wie einfach es ist, die Google MCP Toolbox so zu konfigurieren, dass sie sich mit Elasticsearch verbindet und mit dem kibana_sample_data_ecommerce-Index in natürlicher Sprache interagiert.

Google MCP Toolbox

Die Google MCP Toolbox ist ein Open-Source-MCP-Server, der entwickelt wurde, um Anwendungen und KI-Agenten die sichere und effiziente Interaktion mit Datenbanken zu erleichtern. Das Projekt, das zuvor unter dem Namen „GenAI Toolbox for Databases“ bekannt war, wurde nach der vollständigen Kompatibilität mit dem Model Context Protocol (MCP) umbenannt. Ziel ist es, den üblicherweise beim Verbinden von Agenten mit Datenbanken erforderlichen hohen Aufwand zu reduzieren, indem Verbindungspooling, Authentifizierung, Beobachtbarkeit und andere betriebliche Belange im Hintergrund übernommen werden.

Im Kern ermöglicht es die Toolbox Entwicklern, wiederverwendbare, hochwertige Werkzeuge zu definieren, die Datenbankinteraktionen kapseln. Diese Tools können dann von jedem MCP-kompatiblen Client – wie beispielsweise einem KI-Agenten – aufgerufen werden, ohne dass der Client Low-Level-SQL-Abfragen implementieren oder Datenbankverbindungen verwalten muss. Dieser Ansatz reduziert die Menge an Boilerplate-Code, die für den Aufbau datenbankbewusster Agenten benötigt wird, drastisch und ermöglicht die Integration fortgeschrittener Datenoperationen in nur wenigen Anwendungszeilen. Sobald ein Werkzeug definiert ist, kann es von mehreren Agenten, Frameworks oder Sprachen gemeinsam genutzt werden (Abbildung 1).

Ein großer Vorteil der Nutzung der Toolbox ist das integrierte Sicherheitsmodell. Authentifizierungsabläufe wie OAuth2 und OIDC werden nativ unterstützt, sodass Entwickler:innen die Verarbeitung oder Speicherung sensibler Datenbankzugangsdaten in Agenten vermeiden können. Die Plattform bietet außerdem Beobachtbarkeit-Features – einschließlich Metriken und Tracing – über OpenTelemetry, was für Debugging, Monitoring und Deployments in der Produktionsumgebung unerlässlich ist. Insgesamt dient die MCP Toolbox als einheitliche, sichere und erweiterbare Schnittstelle zur Interaktion mit Ihren Daten von jedem MCP-fähigen System.

So installieren Sie die MCP Toolbox

Sie können den MCP-Toolbox-Server unter Linux mit folgendem Befehl installieren:

Für eine Installation unter macOS oder Windows können Sie den hier beschriebenen Anweisungen folgen.

Toolbox für Elasticsearch konfigurieren

Um die MCP Toolbox für Elasticsearch zu konfigurieren, müssen wir eine tools.yaml-Datei erstellen, und zwar wie folgt:

Sie müssen den Wert <insert-here-api-key> durch einen gültigen Elasticsearch-API-Schlüssel ersetzen. Wenn Sie Elasticsearch lokal mit start-local ausführen, finden Sie den API-Schlüssel in der von start-local generierten .env-Datei unter der Variable ES_LOCAL_API_KEY. Wenn Sie Elastic Cloud verwenden, können Sie einen API-Schlüssel generieren, indem Sie das hier beschriebene Verfahren befolgen.

Die vorherigen Tools enthalten die folgende ES|QL-Abfrage für Elasticsearch:

Falls Ihnen ES|QL nicht geläufig ist: Es handelt sich um eine von Elastic entwickelte Abfragesprache, die ähnlich wie SQL funktioniert und mit der man einen oder mehrere Indizes durchsuchen kann. Mehr über ES|QL finden Sie in der offiziellen Dokumentation hier.

Die obige Abfrage sucht nach allen im kibana_sample_data_ecommerce-Index gespeicherten Bestellungen, die den Namen des:der angegebenen Kund:in enthalten, und verwendet den ?name-Parameter (das Fragezeichen bezeichnet einen Parameter).

Der Name des Kunden wird in der vorherigen YAML-Konfiguration mit dem Typ „Zeichenfolge“ und der Beschreibung „Der Name des Kunden“ definiert.

Mit diesem Tool können Fragen zu den Bestellungen eines:einer Kund:in beantwortet werden – zum Beispiel: Wie viele Bestellungen hat Kund:in Foo im Oktober 2025 aufgegeben?

Die Beschreibungen der Werkzeuge und ihrer Parameter sind unerlässlich, um die relevanten Informationen aus der natürlichsprachlichen Anfrage des:der Nutzer:in zu extrahieren. Diese Extraktion erfolgt mithilfe der Funktionsaufruf-Funktion eines Large Language Models (LLM). In der Praxis kann ein LLM bestimmen, welche Funktion (welches Werkzeug) ausgeführt werden muss, um die notwendigen Informationen zu erhalten, sowie die entsprechenden Parameter für diese Funktion.

Für weitere Informationen zu Funktionsaufrufen empfehlen wir, den Artikel OpenAI Function Calling with Elasticsearch von Ashish Tiwari zu lesen.

Führen Sie den Toolbox-Server aus

Sie können die MCP Toolbox unter Verwendung der vorherigen tools.yaml-Datei mit folgendem Befehl ausführen:

Der Parameter –ui führt eine Webanwendung unter http://127.0.0.1:5000/ui aus (Abbildung 2).

Sie können die Option Tools > customer-orders auswählen und im Feld Parametername einen Kundennamen eingeben (z. B. Gwen Sanders) und anschließend auf die Schaltfläche Tool ausführen klicken. Sie sollten eine JSON-Reaktion sehen, wie in Abbildung 3 dargestellt.

Die Einrichtung ist abgeschlossen, und die MCP Toolbox kann das Tool customer-orders ausführen, um mit Elasticsearch zu kommunizieren und dabei die ES|QL-Anfrage auszuführen.

Verwendung der MCP Toolbox mit Gemini CLI

Wir können jeden beliebigen MCP-Client verwenden, um mit der MCP Toolbox für Datenbanken zu kommunizieren. Zum Beispiel können wir Gemini CLI verwenden, ein Befehlszeilen-Tool zur Nutzung von Gemini. Sie können die Gemini CLI gemäß den hier beschriebenen Anweisungen installieren.

Gemini CLI bietet eine vorkonfigurierte Erweiterung für die MCP Toolbox an, verfügbar unter gemini-cli-extensions/mcp-toolbox. Sie können diese Erweiterung installieren, indem Sie folgenden Befehl ausführen:

Nach der Installation müssen Sie in das Verzeichnis gehen, in dem Sie die Konfigurationsdatei tools.yaml für die MCP Toolbox gespeichert haben, und Gemini CLI wie folgt ausführen (dieser Schritt ist erforderlich, damit die Gemini-CLI automatisch mit der MCP-Toolbox konfiguriert wird):

In Abbildung 4 sollten Sie eine Ausgabeanzeige sehen.

Mit dem folgenden Befehl können Sie überprüfen, ob die MCP Toolbox verbunden ist:

Sie sollten die mcp_toolbox mit den aufgelisteten Tools customer-orders sehen (Abbildung 5).

Wenn die MCP Toolbox mit der Gemini CLI verbunden ist, können wir nun versuchen, einige Fragen zu stellen, wie zum Beispiel: „ Gib mir die Bestellungen für die Kundin Gwen Sanders.“ Anschließend fordert die Gemini CLI die Berechtigung an, das Tool customer-orders vom Server mcp_toolbox auszuführen (siehe Abbildung 6).

Nach der Bestätigung führt Gemini CLI die Anfrage an die MCP Toolbox aus und erhält als Ergebnis eine JSON-Reaktion, die zur Formatierung der Reaktion verwendet wird (Abbildung 7).

Die Reaktion von Gemini CLI wird berichten, dass Gwen Sanders lediglich eine Bestellung über zwei Produkte zum Gesamtpreis von 132 Euro aufgegeben hat.

MCP Toolbox SDKs

Die Google MCP Toolbox bietet außerdem ein SDK an, um alle Funktionen eines in Go, Python und Javascript geschriebenen Programms abzurufen.

Das Python SDK ist beispielsweise auf GitHub unter folgender Seite verfügbar: https://github.com/googleapis/mcp-toolbox-sdk-python.

Wir müssen einen einfachen Agenten erstellen, der mit der MCP Toolbox verbunden werden kann. Wir müssen die folgenden Pakete installieren:

Und erstellen Sie ein neues Agentenprojekt mit folgendem Befehl:

Dadurch wird ein neues Verzeichnis namens my_agent mit einer Datei agent.py erstellt.

Aktualisieren Sie my_agent/agent.py mit dem folgenden Inhalt, um eine Verbindung zu Toolbox herzustellen:

Erstellen Sie eine .env-Datei mit Ihrem Google API-Schlüssel:

Schließlich können wir den Agenten ausführen und die Ergebnisse beobachten. Um den Agenten auszuführen, können Sie folgenden Befehl ausführen:

Alternativ können Sie ihn über eine Webschnittstelle bereitstellen:

In beiden Tickets können Sie mit der MCP Toolbox über eine Q&A-Schnittstelle interagieren. Sie können zum Beispiel die vorherige Frage stellen: Geben Sie mir die Bestellungen der Kundin Gwen Sanders.

Weitere Informationen zu den verschiedenen SDKs finden Sie auf dieser Dokumentationsseite.

Fazit

In diesem Artikel haben wir die Elasticsearch-Integration für die Google MCP Toolbox for Databases demonstriert. Mithilfe einer einfachen YAML-Konfigurationsdatei können wir eine Reihe von Tools definieren, die Fragen in natürlicher Sprache mithilfe der ES|QL-Sprache in Elasticsearch-Abfragen übersetzen.

Wir haben gezeigt, wie man mit dem Datensatz kibana_sample_data_ecommerce interagiert, der Bestellungen von einer Website enthält. Mit dieser Konfigurationsdatei können wir den MCP Toolbox-Server einfach ausführen und uns von jedem MCP-Client aus mit ihm verbinden.

Abschließend haben wir gezeigt, wie man die Gemini-CLI als Client nutzt, um sich mit der MCP Toolbox for Databases zu verbinden und die in Elasticsearch gespeicherten E-Commerce-Daten abzufragen. Wir haben eine Abfrage in natürlicher Sprache ausgeführt, um Informationen über Bestellungen für eine:n bestimmte:n, namentlich identifizierte:n Kund:in abzurufen.

Während das MCP-Ökosystem weiter wächst, schafft dieses Muster – leichte Werkzeugdefinitionen mit sicherer, produktionsreifer Infrastruktur – neue Möglichkeiten, immer leistungsfähigere, datenbewusste Agenten mit minimalem Aufwand zu entwickeln. Ob Sie nun lokal mit den Elastic-Beispieldatensätzen experimentieren oder Suchfunktionen in eine größere Anwendung integrieren, die MCP Toolbox bietet eine zuverlässige, erweiterbare Grundlage für die Interaktion mit Ihren Elasticsearch-Daten unter Verwendung natürlicher Sprache.

Weitere Informationen zur Entwicklung agentischer KI-Anwendungen finden Sie im Artikel Building AI Agentic Workflows with Elasticsearch von Anish Mathur und Dana Juratoni.

Weitere Informationen über die Google MCP Toolbox finden Sie unter https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

ES|QL

ES|QL ist eine neue Elasticsearch-Abfragesprache, die in Elasticsearch 8.11.0 eingeführt wurde. Aktuell ist es als technische Vorschau verfügbar. Es bietet eine leistungsstarke Möglichkeit, in Elasticsearch gespeicherte Daten zu filtern, zu transformieren und zu analysieren.

Es verwendet "Pipes" (|), um Daten schrittweise zu manipulieren und zu transformieren. Dieser Ansatz ermöglicht es den Benutzern, eine Reihe von Operationen zu erstellen, wobei das Ergebnis einer Operation als Eingabe für die nächste dient, wodurch komplexe Datentransformationen und -analysen möglich werden.

Die folgende Abfrage gibt beispielsweise die ersten 3 Dokumente (Zeilen) des Index sample_data zurück:

Anwendungsfall: ES|QL-Funktionen im offiziellen PHP-Client

Um die im offiziellen PHP-Client entwickelten ES|QL-Funktionen zu veranschaulichen, haben wir eine CSV-Datei mit 81.828 Büchern (54,4 MB) in Elasticsearch gespeichert, die folgende Informationen enthält:

Wir haben diese Liste aus dem öffentlich verfügbaren Datensatz der Amazon-Buchrezensionen extrahiert.

Wir haben einen books -Index mit den folgenden Elasticsearch-Mappings erstellt:

Der Wert rating ist der Durchschnitt der Ranking-Rezensionen aus der 2,9 GB großen Datei Books_rating.csv .

Hier finden Sie das PHP-Skript, mit dem wir alle Bücher in Elasticsearch per Massenimport importiert haben. Die Massenverarbeitung dauerte 7 Sekunden und benötigte 28 MB RAM unter Verwendung von PHP 8.2.17. Mit dem vorgeschlagenen Mapping beträgt die Indexgröße in Elasticsearch etwa 62 MB.

ES|QL-Ergebnisse einem PHP-Objekt oder einer benutzerdefinierten Klasse zuordnen

Wir können ES|QL-Abfragen in PHP über den esql()->query() -Endpunkt ausführen. Das Ergebnis dieser Abfrage ist eine Tabellendatenstruktur. Dies wird in JSON mithilfe der Felder columns und values ausgedrückt. Im Feld columns haben wir die Definitionen name und type .

Hier ist ein Beispiel für eine ES|QL-Abfrage, um die Top-10-Bücher von Stephen King, sortiert nach den Nutzerbewertungen, abzurufen:

Das JSON-Ergebnis von Elasticsearch sieht wie folgt aus:

In diesem Beispiel haben wir 6 Eigenschaften (Autor, Beschreibung, Verlag, Bewertung, Titel, Jahr) zu einem Buch und 10 Ergebnisse, alle Bücher von Stephen King.

Eine Liste aller in ES|QL unterstützten Datentypen finden Sie hier.

Das $result -Antwortobjekt kann als Array, als Zeichenkette oder als Objekt aufgerufen werden (siehe hier für weitere Informationen).

Mithilfe der Objektschnittstelle können wir über Eigenschaften und Indizes auf die Werte zugreifen. Beispielsweise gibt $result->values[0][4] den Titel (4) des ersten Buches (0) in der Liste zurück, $result->values[1][3] die Bewertung (3) des zweiten Buches (1) usw. Denken Sie daran, dass der Index eines Arrays in PHP bei Null beginnt.

Diese Schnittstelle mag für einige Anwendungsfälle ausreichend sein, aber in den meisten Fällen möchten wir als Ergebnis ein Array von Objekten erhalten.

Um das Ergebnis in ein Array von Objekten abzubilden, können wir die neue mapTo()- Funktion von elasticsearch-php verwenden.

Diese Funktion ist direkt im Elasticsearch-Antwortobjekt verfügbar. Das bedeutet, Sie können wie folgt darauf zugreifen:

Wenn Sie eine benutzerdefinierte Buchklasse haben, können Sie das Ergebnis mithilfe dieser Klasse wie folgt abbilden:

Wenn Ihre Klasse neben den im ES|QL-Ergebnis enthaltenen Eigenschaften noch weitere Eigenschaften besitzt, funktioniert dies ebenfalls. Die Funktion mapTo() verwendet nur die Eigenschaften, die als Spalten des ES|QL-Ergebnisses zurückgegeben werden.

Sie können alle in diesem Artikel genannten Beispiele hier herunterladen.