Introduction

This tutorial starts where most agent demos stop: giving the agent persistent memory, operational context, and a place to write back what happened. An event operator does not just need an agent that can summarize a weather report or generate a generic plan. The operator needs an agent that can remember what happened at prior events, retrieve relevant visitor and venue context, respond to live operational changes, and write the outcome back as memory for the next similar situation.

We built this event-venue operator demo with MongoDB Atlas, Voyage AI embeddings, LangGraph, and optional Langfuse tracing. The demo scenario is the MongoDB Open, a fictional premium tennis tournament on Day 6 of play. Rain is approaching, covered hospitality capacity is constrained, and the operator has two different visitor journeys to protect: Mikiko, a first-time attendee trying to make the most of the grounds, and Nina, a premier guest with hospitality expectations and a history the agent can retrieve.

This is not a customer case study or a production deployment. It is a fictional builder scenario inspired by real event operations economics. Major tennis events show why these decisions matter: the 2025 US Open broke attendance, viewership, and digital reach records and offered $90 million in total player compensation; USTA has also said the three-week US Open drives more than $1.2 billion in annual economic impact for New York City. Premium fan expectations are high, too: PwC found that 60% of high-income U.S. sports fans would spend more than $250 for a special event, and 20% would spend more than $1,000. Weather adds another layer of risk, which is why the U.S. Census Bureau now tracks the monetary impact of extreme weather on business sales through its Business Trends and Outlook Survey.

The MongoDB Open demo agent is not just producing a plausible plan. It reads current venue state, retrieves prior event memory, distinguishes between visitor segments, and acts. At the same time, hospitality capacity is still available, and writes the outcome back so the next disruption can be handled with more context. Check out the full repo here. 

The demo is split into three layers:

• A guided, deterministic UI that makes the operator story easy to follow.
• A hosted Vercel demo that gives readers a public app link.
• Live API endpoints and scripts for Atlas Vector Search, vector-plus-lexical retrieval, visual-document RAG, LangGraph execution, and optional Langfuse traces, to demonstrate how the stack all works together. 

What You Will Build

By the end of the tutorial, you will have a FastAPI app backed by MongoDB Atlas that can run locally and deploy to Vercel.

The app includes:

• A four-tab guided UI for the event-operations story and live backend validation.
• Atlas collections for operational state, semantic memory, agent actions, and LangGraph checkpoints.
• Voyage multimodal embeddings stored in Atlas.
• Atlas Vector Search for memory retrieval.
• A hybrid retrieval endpoint that combines vector similarity with lexical scoring.
• A Vision RAG endpoint that retrieves visual operational documents and passes them to Claude Vision.
• Optional Langfuse tracing for retrieval calls and the live LangGraph run.
• A runnable LangGraph script that follows the same rain-delay story.
• A Vercel deployment configuration for a hosted demo.

The current repo should be treated as a reference demo, not a production platform. There is no production auth, no CI suite, and the full LangGraph agent remains a script-based validation path rather than a public hosted endpoint.

Architecture Overview

The architecture centers on MongoDB Atlas as both the operational and memory layer. Speed matters in the event venue operator scenario because the useful window for action is short. If rain is 20 minutes away and covered hospitality space is filling up, the operator does not need a post-event dashboard or a batch summary a few minutes later. The agent needs to read the current venue state, retrieve relevant memory, decide what to do, and write back the result while there is still capacity to protect the guest experience.

That is why the type of database and how it is used are critical system design choices. Operational records, semantic memory, vector embeddings, visual documents, and agent actions all live in the same data layer. The agent does not need to wait for a separate analytics pipeline, sync data into a second vector database, or reconcile what the memory layer says with what the operational system says. Atlas acts as both the system of record and the retrieval layer for the agent loop: perceive what changed, retrieve the right context, take action, and persist what happened for the next event.

This is also why the demo keeps memory in MongoDB rather than treating it as a sidecar. The agent is not just retrieving chunks; it is composing operational context. A useful decision may need visitor history, current venue status, hospitality inventory, prior rain-delay patterns, and relevant visual documents at the same time. With Atlas, those pieces can stay queryable together instead of being scattered across separate systems.

The demo uses four main state layers:

• Operational records: guests, visits, venue status, weather events, reservations, event metrics, and agent actions.
• Semantic memory: memory_store, with Voyage embeddings and Atlas Vector Search.
• Visual documents: operational images embedded into the same memory store as image-derived multimodal embeddings and document metadata.
• Agent state: LangGraph checkpoints and checkpoint writes.

Setup

Before you begin, make sure you have:

• Python 3.12 or later
• uv installed
• A MongoDB Atlas cluster with Vector Search enabled (this can be set up for free)
• An Anthropic API key (or feel free to use an LLM of your choice and reconfigure API keys)
• A Voyage API key (this can be set up for free)

Clone the repo and install dependencies: GitHub repo

git clone https://github.com/mongodb-developer/event-venue-operator.git
cd event-venue-operator
uv sync

If you only want to inspect the app before setting up credentials, start with the live Vercel demo. The hosted demo uses the same UI and deployment shape as the repo, while local setup lets you run the full seed, smoke test, Vision RAG, and LangGraph paths yourself.

Create your environment file:

cp .env.example .env

Add the required values:

MONGODB_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority
MONGODB_APP_NAME=devrel-tutorial-agentic_retrieval-memory-marktechpost
MONGODB_DATABASE=event_venue_operator
ANTHROPIC_API_KEY=sk-ant-...
VOYAGE_API_KEY=pa-...

Langfuse is optional for observability:

LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
LANGFUSE_HOST=https://cloud.langfuse.com

Initialize Atlas:

uv run python scripts/setup_atlas.py

This script creates collections and starts the Atlas Vector Search index, then waits up to 60 seconds for the index to become READY. 

Then seed text and visual documents:

uv run python scripts/seed_data.py
uv run python scripts/seed_visual_docs.py

Start the app:

uv run python -m event_venue_operator.server

Open http://127.0.0.1:8000/.

In a second terminal, run the smoke test:

uv run python scripts/smoke_test.py

With the server running in another terminal, the smoke test checks MongoDB health, Atlas Vector Search, hybrid search, visual-document indexing, Vision RAG, optional Langfuse wiring, and collection stats.

Walk Through the UI

The UI has four tabs:

1. The venue-operations dashboard. It establishes the event context: a tennis tournament, rain approaching, hospitality constraints, and two visitor personas.
2. The scenario walkthrough. The agent reads the current state, retrieves long-term memory, plans differentiated actions, acts on behalf of the operator, and writes the result back to memory. 
3. Final outcomes for the day: retention, revenue, reputation, and new memory patterns.
4. Live backend validation calls against Atlas. It lets readers trigger vector and hybrid searches from the browser and emits optional Langfuse traces when Langfuse keys are configured.

Build the Memory Store

The memory store lives in the memory_store collection. Each memory document includes a namespace, key, text payload, category metadata, and an embedding.

Namespaces let the app separate different kinds of memory:

• (“guests”, guest_id) for visitor-specific memory.
• (“fleet”, event_id) for operator-wide event patterns.
• (“docs”, event_id) for visual operational documents.

This design choice streamlines the agent’s access to both operational data and its memory for its own operations. Agent memory in production has many facets: some memories belong to a person, some to a location, some to a business process, and some to reference documents. Atlas gives the app a single backend for all of them while still allowing scoped retrieval, thanks to its flexible data model.

Test Memory Retrieval with Vector and Hybrid Search

At this point, the memory store has already been initialized and seeded. The memory_store collection contains embedded memory documents, and the Atlas Vector Search index is available.

This section shows how to query that memory store directly. You do not need to run these queries to create memory; they are validation calls that help you inspect how retrieval works before the agent uses the same backend path during the scenario.

The simplest retrieval endpoint is vector search:

curl "http://127.0.0.1:8000/api/search?q=weather%20problems&namespace=guests"

This embeds the query with Voyage and searches Atlas for semantically similar memories.

The hybrid endpoint combines vector similarity with lexical scoring over memory text:

curl "http://127.0.0.1:8000/api/hybrid-search?q=thunderstorm%20dinner%20reservation&namespace=guests"

The response includes vector score, lexical score, and combined hybrid score. This is useful because event-operations queries often mix semantic intent with exact operational terms. “Rain delay,” “dinner reservation,” and “covered seating” are all meaningful as concepts, but exact words can still carry a strong signal.

In this implementation, hybrid search means Atlas Vector Search plus deterministic lexical scoring over memory text. It works with the existing vector index and seeded data, so readers do not need to create a separate Atlas Search text index for this tutorial. A natural extension would be to add a dedicated Atlas Search text index and combine those results with vector retrieval.

Add Visual RAG

Operational knowledge is not always text. Accessibility maps, hospitality capacity charts, allergen matrices, weather-response sheets, and evacuation diagrams often exist as images or PDFs.

This repo seeds five visual documents:

uv run python scripts/seed_visual_docs.py

Each image is embedded with Voyage multimodal embeddings and stored in the memory collection. A text query can then retrieve the relevant visual document:

curl -X POST "http://127.0.0.1:8000/api/vision-rag/query" \
  -H "Content-Type: application/json" \
  -d '{"query":"What should we do for a thunderstorm during dinner service?", "limit": 1}'

The endpoint retrieves the best-matching visual document from Atlas and sends it to Claude Vision with the user question. This turns static operational material into retrievable agent context.

Run the LangGraph Agent Path

The repo also includes a LangGraph proof-of-concept:

uv run python scripts/run_poc.py

The graph follows the same tennis-event narrative as the guided UI, but runs it through the live agent path:

• perceive: retrieve prior memories and current operational state.
• plan: call Claude with retrieved context to produce persona-specific actions for Mikiko and Nina.
• Hitl_gate: auto-approve proposed actions in V1, while showing where human approval would fit in production. 
• act: execute tools that update Atlas.
• reflect: write new inferences back to semantic memory.

The generated output will vary because Claude is planning from retrieved memory, but the seeded memories and prompt are aligned to the tennis rain-delay scenario.

Add Optional Langfuse Observability

Langfuse is optional. If you add keys to .env, the app emits tracing around retrieval calls:

LANGFUSE_PUBLIC_KEY=...
LANGFUSE_SECRET_KEY=...
LANGFUSE_HOST=https://cloud.langfuse.com

Check whether the running server is configured:

curl "http://127.0.0.1:8000/api/observability/status"

Run a retrieval request from the Live Backend tab or with /api/search and /api/hybrid-search, then check Langfuse for traces named api.search and api.hybrid_search.

The live LangGraph script also emits a run-level langgraph.run_agent observation when Langfuse keys are configured so that readers can validate observability for both the API layer and the agent path.

For a tutorial, this is a helpful way to show readers where observability fits without making it a hard setup requirement.

Deploy the Hosted Demo to Vercel

The repo includes a Vercel deployment path so the app can be shared as a public demo link. The deployment uses api/index.py as the Vercel ASGI entrypoint, and vercel.json to route requests to FastAPI. The repo includes .python-version  for local Python 3.12 tooling; confirm the Vercel Python runtime is also set to 3.12 and that the build installs dependencies from pyproject.toml.

For the hosted demo, configure these environment variables in Vercel:

MONGODB_URI=<atlas-connection-string>
MONGODB_DATABASE=event_venue_operator
MONGODB_APP_NAME=devrel-tutorial-agentic_retrieval-memory-marktechpost
VOYAGE_API_KEY=<voyage-key>

Langfuse keys are optional. Add ANTHROPIC_API_KEY only if you intentionally want hosted Vision RAG or other LLM-backed endpoints exposed. The full LangGraph path is still validated locally via scripts/run_poc.py rather than through a public, unauthenticated endpoint.

After deployment, validate:

1. Open / and confirm the guided UI loads.
2. Open /api/health and confirm MongoDB reports up.
3. Use the Live Backend tab to run vector search.
4. Use the Live Backend tab to run hybrid search.
5. If Langfuse keys are configured, confirm traces appear in Langfuse.

Production Notes and Constraints

This demo is intentionally scoped.

The UI is deterministic. It is useful for communicating the scenario, but it is not a full real-time operations console.

The seed data is synthetic. It is good enough to demonstrate retrieval patterns, but it should not be treated as representative production data.

The current project does not include production authentication, rate limiting, tenant isolation, secret management, or CI. Those would be required before adapting the pattern for a real operator-facing application.

You can run this tutorial on an Atlas Free cluster to test the Vector Search workflow. Free clusters are intended for small-scale development and testing; for serious prototyping or production workloads, use a dedicated Atlas tier sized for your data and query volume.

Where to Go Next

The demo keeps the useful parts of the agent stack in data: operational records, semantic memories, visual documents, checkpoints, and traces. MongoDB Atlas can hold those pieces together while still supporting vector search, multimodal retrieval, and application state in one place.

 If you enjoyed this tutorial, feel free to create your own scenario and/or add features you think would make the demo more realistic. 

If you want to learn more, check out our other tutorials in GenAI Showcase or learn more about agents and memory at MongoDB University. 

Check out the GitHub repo here.

_{Note:Thanks to the MongoDB team for the Technical Resources and promotional support for this article.}