Introducción
Este tutorial comienza donde terminan la mayoría de las demostraciones de agentes: brindarle al agente memoria persistente, contexto operativo y un lugar para escribir lo que sucedió. Un operador de eventos no sólo necesita un agente que pueda resumir un informe meteorológico o generar un plan genérico. El operador necesita un agente que pueda recordar lo que sucedió en eventos anteriores, recuperar el contexto relevante del visitante y del lugar, responder a los cambios operativos en vivo y escribir el resultado como memoria para la siguiente situación similar.
Creamos esta demostración del operador del lugar de eventos con MongoDB Atlas, incorporaciones de Voyage AI, LangGraph y seguimiento Langfuse opcional. El escenario de demostración es el MongoDB Open, un torneo de tenis premium ficticio que se celebra el día 6 de juego. Se acerca la lluvia, la capacidad de hospitalidad cubierta es limitada y el operador tiene dos recorridos de visitantes diferentes que proteger: Mikiko, una asistente por primera vez que intenta aprovechar al máximo el recinto, y Nina, una invitada de primer nivel con expectativas de hospitalidad y una historia que el agente puede recuperar.
Este no es un estudio de caso de un cliente ni una implementación de producción. Es un escenario de construcción ficticio inspirado en la economía de operaciones de eventos reales. Los principales eventos de tenis muestran por qué estas decisiones son importantes: el US Open de 2025 batió récords de asistencia, audiencia y alcance digital y ofreció 90 millones de dólares en compensación total a los jugadores; La USTA también ha dicho que el Abierto de Estados Unidos de tres semanas genera más de 1.200 millones de dólares en impacto económico anual para la ciudad de Nueva York. Las expectativas de los fanáticos premium también son altas: PwC descubrió que el 60% de los fanáticos de los deportes estadounidenses con altos ingresos gastarían más de $250 en un evento especial, y el 20% gastaría más de $1,000. El clima agrega otra capa de riesgo, razón por la cual la Oficina del Censo de EE. UU. ahora rastrea el impacto monetario del clima extremo en las ventas comerciales a través de su Encuesta de perspectivas y tendencias comerciales.
El agente de demostración MongoDB Open no sólo está elaborando un plan plausible. Lee el estado actual del lugar, recupera la memoria de eventos anteriores, distingue entre segmentos de visitantes y actúa. Al mismo tiempo, la capacidad hotelera todavía está disponible y escribe el resultado para que la próxima interrupción pueda manejarse con más contexto. Consulte el repositorio completo aquí.
La demostración se divide en tres capas:
Una interfaz de usuario guiada y determinista que hace que la historia del operador sea fácil de seguir. Una demostración alojada de Vercel que ofrece a los lectores un enlace de aplicación pública. Puntos finales y scripts de API en vivo para Atlas Vector Search, recuperación de vectores más léxico, RAG de documentos visuales, ejecución de LangGraph y seguimientos Langfuse opcionales, para demostrar cómo funciona la pila en conjunto.
Lo que construirás
Al final del tutorial, tendrá una aplicación FastAPI respaldada por MongoDB Atlas que puede ejecutarse localmente e implementarse en Vercel.
La aplicación incluye:
Una interfaz de usuario guiada por cuatro pestañas para la historia de operaciones de eventos y la validación de backend en vivo. Colecciones de Atlas para estado operativo, memoria semántica, acciones de agentes y puntos de control de LangGraph. Incorporaciones multimodales de viaje almacenadas en Atlas. Atlas Vector Search para recuperación de memoria. Un criterio de valoración de recuperación híbrido que combina la similitud de vectores con la puntuación léxica. Un punto final de Vision RAG que recupera documentos operativos visuales y los pasa a Claude Vision. Seguimiento de Langfuse opcional para llamadas de recuperación y ejecución de LangGraph en vivo. Un script LangGraph ejecutable que sigue la misma historia del retraso por lluvia. Una configuración de implementación de Vercel para una demostración alojada.
El repositorio actual debe tratarse como una demostración de referencia, no como una plataforma de producción. No hay autenticación de producción ni conjunto de CI, y el agente LangGraph completo sigue siendo una ruta de validación basada en scripts en lugar de un punto final alojado públicamente.
Descripción general de la arquitectura
La arquitectura se centra en MongoDB Atlas como capa operativa y de memoria. La velocidad es importante en el escenario del operador del lugar del evento porque la ventana útil para la acción es corta. Si faltan 20 minutos para que llueva y el espacio cubierto de hostelería se está llenando, el operador no necesita un panel posterior al evento ni un resumen del lote unos minutos más tarde. El agente debe leer el estado actual del lugar, recuperar la memoria relevante, decidir qué hacer y escribir el resultado mientras todavía haya capacidad para proteger la experiencia del huésped.
Es por eso que el tipo de base de datos y cómo se utiliza son decisiones críticas en el diseño del sistema. Los registros operativos, la memoria semántica, las incrustaciones de vectores, los documentos visuales y las acciones de los agentes viven en la misma capa de datos. El agente no necesita esperar un proceso de análisis separado, sincronizar datos en una segunda base de datos vectorial o conciliar lo que dice la capa de memoria con lo que dice el sistema operativo. Atlas actúa como sistema de registro y capa de recuperación para el bucle del agente: percibe lo que cambió, recupera el contexto correcto, toma medidas y persiste en lo que sucedió para el siguiente evento.
Esta es también la razón por la que la demostración mantiene la memoria en MongoDB en lugar de tratarla como un complemento. El agente no se limita a recuperar fragmentos; está componiendo el contexto operativo. Una decisión útil puede necesitar al mismo tiempo el historial de visitantes, el estado actual del lugar, el inventario de hospitalidad, los patrones anteriores de retrasos por lluvia y documentos visuales relevantes. Con Atlas, esas piezas pueden consultarse juntas en lugar de estar dispersas en sistemas separados.
La demostración utiliza cuatro capas de estado principales:
Registros operativos: invitados, visitas, estado del lugar, eventos climáticos, reservas, métricas de eventos y acciones de los agentes. Memoria semántica: Memory_store, con incrustaciones de Voyage y Atlas Vector Search. Documentos visuales: imágenes operativas incrustadas en el mismo almacén de memoria que las incrustaciones multimodales derivadas de imágenes y los metadatos de documentos. Estado del agente: puntos de control de LangGraph y escrituras de puntos de control.
Configuración
Antes de comenzar, asegúrese de tener:
Python 3.12 o posterior instalado con uv Un clúster MongoDB Atlas con Vector Search habilitado (esto se puede configurar de forma gratuita) Una clave API de Anthropic (o siéntase libre de usar un LLM de su elección y reconfigurar las claves API) Una clave API de Voyage (esto se puede configurar de forma gratuita)
Clonar el repositorio e instalar dependencias: repositorio de GitHub
Si solo desea inspeccionar la aplicación antes de configurar las credenciales, comience con la demostración en vivo de Vercel. La demostración alojada utiliza la misma interfaz de usuario y forma de implementación que el repositorio, mientras que la configuración local le permite ejecutar las rutas completas de semilla, prueba de humo, Vision RAG y LangGraph usted mismo.
Crea tu archivo de entorno:
Agregue los valores requeridos:
Langfuse es opcional para la observabilidad:
Inicializar Atlas:
Este script crea colecciones e inicia el índice Atlas Vector Search, luego espera hasta 60 segundos para que el índice esté LISTO.
Luego, siembre texto y documentos visuales:
Inicie la aplicación:
Abra http://127.0.0.1:8000/.
En una segunda terminal, ejecute la prueba de humo:
Con el servidor ejecutándose en otra terminal, la prueba de humo verifica el estado de MongoDB, Atlas Vector Search, búsqueda híbrida, indexación de documentos visuales, Vision RAG, cableado Langfuse opcional y estadísticas de recopilación.
Caminar por la interfaz de usuario
La interfaz de usuario tiene cuatro pestañas:
El panel de operaciones del lugar. Establece el contexto del evento: un torneo de tenis, la lluvia que se acerca, limitaciones de hospitalidad y dos personajes visitantes. El recorrido del escenario. El agente lee el estado actual, recupera la memoria a largo plazo, planifica acciones diferenciadas, actúa en nombre del operador y escribe el resultado en la memoria. Resultados finales del día: retención, ingresos, reputación y nuevos patrones de memoria. Llamadas de validación de backend en vivo contra Atlas. Permite a los lectores activar búsquedas vectoriales e híbridas desde el navegador y emite seguimientos Langfuse opcionales cuando se configuran las claves Langfuse.
Construye la tienda de recuerdos
El almacén de memoria vive en la colección Memory_store. Cada documento de memoria incluye un espacio de nombres, una clave, una carga útil de texto, metadatos de categoría y una incrustación.
Los espacios de nombres permiten que la aplicación separe diferentes tipos de memoria:
(“guests”, guest_id) para la memoria específica del visitante. (“fleet”, event_id) para patrones de eventos de todo el operador. (“docs”, event_id) para documentos operativos visuales.
Esta elección de diseño agiliza el acceso del agente tanto a los datos operativos como a su memoria para sus propias operaciones. La memoria del agente en producción tiene muchas facetas: algunas memorias pertenecen a una persona, otras a una ubicación, algunas a un proceso de negocio y algunas a documentos de referencia. Atlas le brinda a la aplicación un backend único para todos ellos y al mismo tiempo permite la recuperación con alcance, gracias a su modelo de datos flexible.
Pruebe la recuperación de memoria con búsqueda vectorial e híbrida
En este punto, el almacén de memoria ya se ha inicializado y sembrado. La colección Memory_store contiene documentos de memoria incrustados y el índice Atlas Vector Search está disponible.
Esta sección muestra cómo consultar ese almacén de memoria directamente. No es necesario ejecutar estas consultas para crear memoria; son llamadas de validación que le ayudan a inspeccionar cómo funciona la recuperación antes de que el agente utilice la misma ruta de backend durante el escenario.
El punto final de recuperación más simple es la búsqueda vectorial:
Esto incorpora la consulta con Voyage y busca en Atlas recuerdos semánticamente similares.
El punto final híbrido combina similitud de vectores con puntuación léxica sobre texto de memoria:
La respuesta incluye puntuación vectorial, puntuación léxica y puntuación híbrida combinada. Esto es útil porque las consultas de operaciones de eventos a menudo combinan intención semántica con términos operativos exactos. “Retraso por lluvia”, “reserva para cenar” y “asientos cubiertos” son conceptos significativos, pero las palabras exactas aún pueden transmitir una señal fuerte.
En esta implementación, la búsqueda híbrida significa Atlas Vector Search más puntuación léxica determinista sobre el texto de memoria. Funciona con el índice vectorial existente y los datos inicializados, por lo que los lectores no necesitan crear un índice de texto de Atlas Search por separado para este tutorial. Una extensión natural sería agregar un índice de texto de Atlas Search dedicado y combinar esos resultados con la recuperación de vectores.
Agregar RAG visual
El conocimiento operativo no siempre es texto. Los mapas de accesibilidad, los gráficos de capacidad hotelera, las matrices de alérgenos, las hojas de respuesta climática y los diagramas de evacuación a menudo existen en forma de imágenes o archivos PDF.
Este repositorio genera cinco documentos visuales:
Cada imagen está incrustada con incrustaciones multimodales de Voyage y se almacena en la colección de memoria. Luego, una consulta de texto puede recuperar el documento visual relevante:
El punto final recupera el documento visual que mejor coincide de Atlas y lo envía a Claude Vision con la pregunta del usuario. Esto convierte el material operativo estático en un contexto de agente recuperable.
Ejecute la ruta del agente LangGraph
El repositorio también incluye una prueba de concepto de LangGraph:
El gráfico sigue la misma narrativa del evento de tenis que la interfaz de usuario guiada, pero la recorre a través de la ruta del agente en vivo:
percibir: recuperar recuerdos anteriores y el estado operativo actual. Plan: llamar a Claude con el contexto recuperado para producir acciones específicas de persona para Mikiko y Nina. Hitl_gate: aprueba automáticamente las acciones propuestas en V1, al tiempo que muestra dónde encajaría la aprobación humana en la producción. actuar: ejecutar herramientas que actualicen Atlas. reflexionar: escribir nuevas inferencias en la memoria semántica.
El resultado generado variará porque Claude está planificando a partir de la memoria recuperada, pero los recuerdos sembrados y el aviso están alineados con el escenario de retraso por lluvia del tenis.
Agregue observabilidad Langfuse opcional
Langfuse es opcional. Si agrega claves a .env, la aplicación emite un seguimiento de las llamadas de recuperación:
Compruebe si el servidor en ejecución está configurado:
Ejecute una solicitud de recuperación desde la pestaña Live Backend o con /api/search y /api/hybrid-search, luego verifique en Langfuse los rastros llamados api.search y api.hybrid_search.
El script LangGraph en vivo también emite una observación langgraph.run_agent a nivel de ejecución cuando las claves Langfuse están configuradas para que los lectores puedan validar la observabilidad tanto para la capa API como para la ruta del agente.
Para un tutorial, esta es una forma útil de mostrar a los lectores dónde encaja la observabilidad sin que sea un requisito de configuración difícil.
Implementar la demostración alojada en Vercel
El repositorio incluye una ruta de implementación de Vercel para que la aplicación se pueda compartir como un enlace de demostración público. La implementación utiliza api/index.py como punto de entrada Vercel ASGI y vercel.json para enrutar solicitudes a FastAPI. El repositorio incluye la versión .python para herramientas locales de Python 3.12; Confirme que el tiempo de ejecución de Vercel Python también esté configurado en 3.12 y que la compilación instale dependencias desde pyproject.toml.
Para la demostración alojada, configure estas variables de entorno en Vercel:
Las llaves Langfuse son opcionales. Agregue ANTHROPIC_API_KEY solo si desea intencionalmente exponer Vision RAG alojado u otros puntos finales respaldados por LLM. La ruta completa de LangGraph todavía se valida localmente a través de scripts/run_poc.py en lugar de a través de un punto final público no autenticado.
Después de la implementación, valide:
Abra / y confirme las cargas de la interfaz de usuario guiada. Abra /api/health y confirme que los informes de MongoDB estén activos. Utilice la pestaña Live Backend para ejecutar la búsqueda vectorial. Utilice la pestaña Live Backend para ejecutar la búsqueda híbrida. Si las claves de Langfuse están configuradas, confirme que los rastros aparezcan en Langfuse.
Notas y restricciones de producción
Esta demostración tiene un alcance intencional.
La interfaz de usuario es determinista. Es útil para comunicar el escenario, pero no es una consola de operaciones completa en tiempo real.
Los datos de las semillas son sintéticos. Es suficientemente bueno para demostrar patrones de recuperación, pero no debe tratarse como datos de producción representativos.
El proyecto actual no incluye autenticación de producción, limitación de velocidad, aislamiento de inquilinos, gestión de secretos ni CI. Serían necesarios antes de adaptar el patrón para una aplicación real orientada al operador.
Puede ejecutar este tutorial en un clúster Atlas Free para probar el flujo de trabajo de búsqueda vectorial. Los clústeres gratuitos están destinados al desarrollo y pruebas a pequeña escala; para cargas de trabajo de producción o creación de prototipos importantes, utilice un nivel Atlas dedicado del tamaño de sus datos y volumen de consultas.
Adónde ir a continuación
La demostración mantiene en datos las partes útiles de la pila de agentes: registros operativos, memorias semánticas, documentos visuales, puntos de control y rastreos. MongoDB Atlas puede mantener juntas esas piezas y al mismo tiempo admitir la búsqueda de vectores, la recuperación multimodal y el estado de la aplicación en un solo lugar.
Si disfrutó de este tutorial, siéntase libre de crear su propio escenario y/o agregar funciones que crea que harían la demostración más realista.
Si desea obtener más información, consulte nuestros otros tutoriales en GenAI Showcase o obtenga más información sobre agentes y memoria en la Universidad MongoDB.
Consulte el repositorio de GitHub aquí.
Nota: Gracias al equipo de MongoDB por los recursos técnicos y el apoyo promocional para este artículo.
Defensor del personal de desarrollo @ MongoDB. Anteriormente DevRel/DS @ Contextual AI, no estructurado, Spectrum Labs (adquirido), IQT Labs. Carrera anterior como investigador de neurociencia en Berkeley, NIDA, Princeton.