Cómo construir aplicaciones de IA con agentes con Mastra y Elasticsearch

En este artículo, haremos un recorrido por cómo usar el marco de trabajo Mastra TypeScript para crear aplicaciones agénticas que interactúen con Elasticsearch.

Recientemente, contribuimos al proyecto de mastra-ai/mastra open source agregando soporte para Elasticsearch como base de datos vectorial. Con esta nueva característica, puedes usar Elasticsearch de forma nativa en Mastra para almacenar incrustaciones. Además de los vectores, Elasticsearch ofrece un conjunto de funciones avanzadas para satisfacer todas tus necesidades de ingeniería de contexto (por ejemplo, búsqueda híbrida y reordenamiento).

En este artículo, se detalla la creación de un agente para implementar una arquitectura de Retrieval-Augmented Generation (RAG) con Elasticsearch. Te mostraremos un proyecto de demostración en el que se utiliza un enfoque agéntico para interactuar con un corpus de datos de películas de ciencia ficción almacenados en Elasticsearch. El proyecto está disponible en elastic/mastra-elasticsearch-example.

Mastra

Mastra es un marco de trabajo de TypeScript para crear aplicaciones de IA agéntica.

Una estructura de proyecto en Mastra se ve así:

En Mastra, puedes crear agentes, herramientas, flujos de trabajo y puntajes.

Un agente es una clase que acepta un mensaje como entrada y produce una respuesta como salida. Un agente puede usar herramientas, modelos de lenguaje a gran escala (LLM) y una memoria (figura 1).

Las herramientas de un agente le permiten interactuar con el "mundo externo", como comunicarse con una API web o hacer una operación interna, como consultar Elasticsearch. El componente de memoria es crucial para almacenar el historial de conversaciones, incluidas las entradas y salidas pasadas. Este contexto almacenado permite que el agente proporcione respuestas más informadas y relevantes a preguntas futuras mediante el uso de sus interacciones pasadas.

Los flujos de trabajo te permiten definir secuencias complejas de tareas mediante pasos claros y estructurados, en lugar de depender del razonamiento de un solo agente (figura 2). Te brindan control total sobre cómo se desglosan las tareas, cómo se mueven los datos entre ellas y qué se ejecuta y cuándo. Los flujos de trabajo se ejecutan con el motor de ejecución integrado de forma predeterminada o se pueden desplegar en ejecutores de flujos de trabajo.

En Mastra, también puedes definir puntuaciones, que son pruebas automatizadas que evalúan las salidas de los agentes mediante métodos calificados por modelos, basados en reglas y estadísticos. Los evaluadores devuelven puntuaciones: valores numéricos (normalmente entre 0 y 1) que cuantifican qué tan bien una salida cumple con tus criterios de evaluación. Estas puntuaciones te permiten hacer un seguimiento objetivo del rendimiento, comparar diferentes enfoques e identificar áreas de mejora en tus sistemas de IA. Los evaluadores pueden personalizarse con tus propias solicitudes y funciones de puntuación.

Elasticsearch

Para ejecutar el proyecto de demostración, necesitamos tener una instancia de Elasticsearch en ejecución. Puedes activar una prueba gratis en Elastic Cloud o instalarlo localmente usando el script start-local:

Se instalarán Elasticsearch y Kibana en tu computadora y se generará una clave API que se utilizará para configurar la integración de Mastra.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env en la carpeta elastic-start-local.

Instalar y configurar la demo

Creamos un repositorio elastic/mastra-elasticsearch-example que contiene el código fuente del proyecto de demostración. El ejemplo reportado en el repositorio ilustra cómo crear un agente en Mastra que implemente una arquitectura RAG para recuperar documentos de Elasticsearch.

Proporcionamos un set de datos para la demostración sobre películas de ciencia ficción. Extrajimos 500 películas de los sets de datos de IMDb en Kaggle.

El primer paso es instalar las dependencias del proyecto con npm, usando el siguiente comando:

Luego tenemos que configurar el archivo .env que contendrá la configuración. Podemos generar este archivo copiando la estructura del archivo .env.example , usando el siguiente comando:

Ahora podemos editar el archivo .env, agregando la información faltante:

El nombre del índice de Elasticsearch es scifi-movies. Si quieres, puedes cambiarlo usando la variable de entorno ELASTICSEARCH_INDEX_NAME.

Usamos OpenAI como servicio de incrustación, lo que significa que necesitas proporcionar una clave API para OpenAI en la variable OPENAI_API_KEY .env.

El modelo de incrustación empleado en el ejemplo es openai/text-embedding-3-small, con una dimensión de incrustación de 1536.

Para generar la respuesta final, empleamos el modelo openai/gpt-5-nano para reducir costos.

La arquitectura RAG te permite usar un modelo LLM final menos potente (y generalmente menos costoso) porque el trabajo pesado de fundamentar la respuesta está a cargo del componente de recuperación (Elasticsearch en este caso).

El LLM más pequeño solo se encarga de dos tareas principales:

• Reformulación/incrustación de la consulta: Convertir la pregunta en lenguaje natural del usuario en una incrustación de vectores para la búsqueda semántica.
• Sintetizar la respuesta: Se toman los fragmentos de contexto muy relevantes y recuperados (documentos/películas) y se los sintetiza en una respuesta coherente, final y legible por seres humanos, siguiendo las instrucciones del prompt proporcionado.

Dado que el proceso RAG proporciona el contexto fáctico exacto necesario para la respuesta, el LLM final no necesita ser masivo o muy complejo y no necesita poseer todo el conocimiento requerido dentro de sus propios parámetros (que es donde sobresalen los modelos grandes y caros). Esencialmente actúa como un sofisticado resumidor y formateador de texto para el contexto proporcionado por Elasticsearch, en lugar de ser una base de conocimientos completa en sí mismo. Esto permite el uso de modelos como gpt-5-nano para optimizar costos y latencia.

Después de la configuración del archivo .env, puedes ingestar las películas a Elasticsearch usando el siguiente comando:

Deberías ver una salida como la siguiente:

El mapping del índice de películas de ciencia ficción contiene los siguientes campos:

• incrustación, dense_vector con 1536 dimensiones, similitud del coseno.
• descripción, texto que contiene la descripción de la película.
• director, texto que contiene el nombre del director.
• título, texto que contiene el título de la película.

Generamos las incrustaciones usando el título + la descripción. Como el título y la descripción son dos campos separados, la concatenación de ambos asegura que el vector de incrustación resultante capture tanto la identidad única y específica (título) como el contexto rico y descriptivo (descripción) de la película, lo que lleva a resultados de búsqueda semántica más precisos y completos. Esta entrada combinada le brinda al modelo de incrustación una mejor representación del contenido del documento para la búsqueda por similitud.

Ejecuta la demostración

Puedes ejecutar la demo con el siguiente comando:

Este comando iniciará una aplicación web en localhost:4111 para acceder a Mastra Studio (figura 3).

Mastra Studio ofrece una UI interactiva para crear y probar tus agentes, junto con una API REST que expone tu aplicación Mastra como un servicio local. Esto te permite comenzar a construir de inmediato sin preocuparte por la integración.

Proporcionamos un Agente Elasticsearch que emplea createVectorQueryTool de Mastra como herramienta para ejecutar búsqueda semántica usando Elasticsearch. Este agente emplea el enfoque RAG para buscar documentos relevantes (es decir, películas) que respondan a la pregunta del usuario.

Este agente usa el siguiente prompt:

Si haces clic en el menú Mastra Studio > Agents y seleccionas Agente de Elasticsearch, puedes probar el agente usando un sistema de chat. Por ejemplo, puedes pedir información sobre películas de ciencia ficción con una pregunta como esta:

Encuentra 5 películas o series de TV sobre ovnis.

Notarás que el agente ejecutará el vectorQueryTool. Puedes hacer clic en la herramienta invocada para ver la entrada y la salida. Al final de la ejecución, el LLM responderá tu pregunta, dado el contexto que proviene del índice de películas de ciencia ficción de Elasticsearch (figura 4).

Mastra ejecuta los siguientes pasos internamente:

1. Conversión en vectores: La pregunta del usuario, Encuentra 5 películas o series de televisión sobre ovnis, se convierte en una incrustación de vectores mediante el modelo openai/text-embedding-3-small de OpenAI.
2. Búsqueda de vectores: Esta incrustación se usa luego para hacer una búsqueda en Elasticsearch mediante una búsqueda de vectores.
3. Recuperación de resultados: Elasticsearch devuelve una serie de 10 películas muy relevantes para la consulta (es decir, aquellas con vectores más cercanos al vector de consulta del usuario).
4. Generación de respuestas: Las películas recuperadas y la pregunta original del usuario se envían al LLM, específicamente openai/gpt-5-nano. El LLM procesa esta información y genera una respuesta final, asegurando que se cumpla la solicitud del usuario para cinco resultados.

El agente de Elasticsearch

Aquí presentamos el código fuente del agente de Elasticsearch.

El vectorQueryTool es la herramienta que se invoca para implementar la parte de recuperación del ejemplo de RAG. Emplea la implementación de ElasticSearchVector que Elastic aportó a Mastra.

El agente es un objeto de la clase agente que utiliza la herramienta vectorQueryTool, el prompt y una memoria. Como puedes ver, el código que necesitamos implementar para conectar Elasticsearch a un agente es muy sencillo.

Conclusión

En este artículo, se demostró la simplicidad y el poder de integrar Elasticsearch con el marco de trabajo Mastra para construir sofisticadas aplicaciones de IA agéntica. En concreto, te mostramos cómo crear un agente RAG capaz de efectuar búsquedas semánticas sobre un corpus de datos de películas de ciencia ficción indexados en Elasticsearch.

Una de las principales conclusiones es la contribución directa de Elastic al proyecto de código abierto Mastra, que ofrece compatibilidad nativa con Elasticsearch como almacén de vectores. Esta integración reduce considerablemente las barreras de acceso, como se puede ver en el código fuente del agente de Elasticsearch. Usando el ElasticSearchVector y createVectorQueryTool, la configuración completa para conectar Elasticsearch a tu agente requiere solo un número mínimo de líneas de código de configuración.

Elasticsearch ofrece varias características avanzadas para mejorar la relevancia de los resultados. Por ejemplo, la búsqueda híbrida aumenta significativamente la precisión combinando la búsqueda léxica con la búsqueda de vectores. Otra característica interesante es la reclasificación con los últimos modelos de Jina, que puede aplicarse al final de la búsqueda híbrida. Para obtener más información sobre estas técnicas, consulta los siguientes artículos de Elasticsearch Labs:

• Búsqueda híbrida Elasticsearch de Valentin Crettaz
• Introducción a los modelos de Jina, su funcionalidad y usos en Elasticsearch de Scott Martens

También te animamos a consultar el ejemplo proporcionado y comenzar a crear tus propios agentes basados en datos con Mastra y Elasticsearch. Para más información sobre Mastra, puedes consultar la documentación oficial aquí.