So erstellen Sie agentische KI-Anwendungen mit Mastra und Elasticsearch

In diesem Artikel zeigen wir Ihnen, wie Sie mit dem TypeScript-Framework von Mastra agentische Anwendungen erstellen, die mit Elasticsearch interagieren.

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:

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

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:

curl -fsSL https://elastic.co/start-local | sh

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:

npm install

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:

cp .env.example .env

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

OPENAI_API_KEY=
ELASTICSEARCH_URL=
ELASTICSEARCH_API_KEY=
ELASTICSEARCH_INDEX_NAME=scifi-movies

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:

npx tsx src/utility/store.ts

Der Ausgabe sollte wie folgt aussehen:

🚀 Starting ingestion of 500 movies from 500_scifi_movies.jsonl...
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 1/500 (0%) | ok:1 | fail:0 | chunks:1 | eta:19m 33s | current:Capricorn One
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 2/500 (0%) | ok:2 | fail:0 | chunks:2 | eta:10m 32s | current:Doghouse
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 3/500 (1%) | ok:3 | fail:0 | chunks:3 | eta:7m 33s | current:Dinocroc
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 4/500 (1%) | ok:4 | fail:0 | chunks:7 | eta:6m 10s | current:Back to the Future           
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 5/500 (1%) | ok:5 | fail:0 | chunks:9 | eta:5m 14s | current:The Projected Man            
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 6/500 (1%) | ok:6 | fail:0 | chunks:11 | eta:4m 41s | current:I, Robot
...
✅ Ingestion complete in 1m 46s. Success: 500, Failed: 0, Chunks: 693.

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:

npm run dev

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:

You are a helpful assistant that answers questions based on the provided context.
Follow these steps for each response:

1. First, carefully analyze the retrieved context chunks and identify key information.
2. Break down your thinking process about how the retrieved information relates to the query.
3. Draw conclusions based only on the evidence in the retrieved context.
4. If the retrieved chunks don't contain enough information, explicitly state what's missing.

Format your response as:
THOUGHT PROCESS:
- Step 1: [Initial analysis of retrieved chunks]
- Step 2: [Reasoning based on chunks]

FINAL ANSWER:
[Your concise answer based on the retrieved context]

Important: When asked to answer a question, please base your answer only on the context provided in the tool. 
If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it.
Do not add more information than what is present in the retrieved chunks.
Remember: Explain how you're using the retrieved information to reach your conclusions.

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.

import { Agent } from "@mastra/core/agent";
import { ElasticSearchVector } from '@mastra/elasticsearch';
import { createVectorQueryTool } from '@mastra/rag';
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { Memory } from "@mastra/memory";

const es_url = process.env.ELASTICSEARCH_URL;
const es_apikey = process.env.ELASTICSEARCH_API_KEY;
const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME;
const prompt = 'insert here the previous prompt';

const esVector = new ElasticSearchVector({
  id: 'elasticsearch-vector',
  url: es_url,
  auth: {
    apiKey : es_apikey
  }
});

const vectorQueryTool = createVectorQueryTool({
  vectorStore: esVector,
  indexName: es_index_name,
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
});

export const elasticsearchAgent = new Agent({
  id: "elasticsearch-agent",
  name: "Elasticsearch Agent",
  instructions: prompt,
  model: 'openai/gpt-5-nano',
  tools: { vectorQueryTool },
  memory: new Memory(),
});

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.