Here is a new, self-contained article built from the provided post content, now organized with a structured introduction, a body that walks through the what/how, a concise FAQ section, and a concluding summary.
—
# Build an Agentic Event-Venue Operator with MongoDB Atlas, Voyage, and LangGraph
## Introduction
Modern event operators need more than dashboards—they need agents that remember, reason, and act in real time. This tutorial demonstrates a MongoDB Atlas–based event-venue operator that persists operational context and memory across interactions. Designed around the fictional MongoDB Open tennis tournament, the demo shows how an agent can:
– Remember prior events and guest preferences
– Distinguish visitor segments (e.g., first-time attendees vs. premium guests)
– React to live changes such as incoming rain
– Record decisions as memory for future scenarios
The stack used includes MongoDB Atlas for operational state and memory, Voyage AI for embeddings and multimodal document indexing, LangGraph for agent orchestration, and optional Langfuse for observability. The demo is a reference implementation, not a production platform, but it shows how tightly integrated data and agent workflows can become when everything lives in a single database.
—
## What You Will Build
You will end up with a FastAPI application backed by MongoDB Atlas that supports:
– A guided four-tab UI illustrating an event-ops story and live backend validation
– Persistent semantic memory stored in Atlas with vector and hybrid search
– Multimodal document indexing and retrieval via Vision RAG
– Optional Langfuse tracing for query and agent observability
– A runnable LangGraph script that follows the same rain-delay scenario end to end
Key data entities live in MongoDB collections:
– Operational records (guests, visits, venue status, weather, reservations)
– Semantic memory with Voyage embeddings
– Visual documents stored as multimodal embeddings
– LangGraph checkpoints for agent state
—
## Architecture Overview
The design centers on MongoDB Atlas as the single source of truth for both operational data and memory. Because event windows are short—minutes, not hours—the agent must perceive changes, retrieve context, decide, and act quickly. Keeping everything in Atlas avoids costly syncs and enables joint queries over operational state, memory, and vector similarity.
Four main state layers are used:
– Operational records for real-time venue and guest state
– Semantic memory with vector embeddings for long-term recall
– Visual documents indexed by multimodal embeddings
– Agent state via LangGraph checkpoints persisted in Atlas
This unified backend lets the agent compose context from visitor history, current inventory, prior rain-delay patterns, and visual SOP documents without stitching together multiple systems.
—
## Setup and Local Run
### Prerequisites
– Python 3.12+
– MongoDB Atlas cluster with Vector Search enabled
– Voyage API key (free tier available)
– Anthropic API key (or equivalent LLM)
– Optional: Langfuse public/secret keys
### Steps
1. Clone the repo and install dependencies
“`bash
git clone
cd event-venue-operator
uv sync
“`
2. Configure environment variables in a `.env` file
“`env
MONGODB_URI=mongodb+srv://
MONGODB_APP_NAME=devrel-tutorial-agentic_retrieval-memory-marktechpost
MONGODB_DATABASE=event_venue_operator
ANTHROPIC_API_KEY=sk-ant-…
VOYAGE_API_KEY=pa-…
# Optional:
LANGFUSE_PUBLIC_KEY=…
LANGFUSE_SECRET_KEY=…
LANGFUSE_HOST=…
“`
3. Initialize Atlas collections and vector search index
“`bash
uv run python scripts/setup_atlas.py
“`
4. Seed memory and visual documents
“`bash
uv run python scripts/seed_data.py
uv run python scripts/seed_visual_docs.py
“`
5. Start the FastAPI server
“`bash
uv run python -m event_venue_operator.server
“`
6. Optionally run the smoke test to validate all integrations
“`bash
uv run python scripts/smoke_test.py
“`
A hosted Vercel demo is also available for quick inspection using the same UI and deployment configuration.
—
## Walk Through the UI
The app UI contains four tabs:
1. Venue-operations dashboard establishing tournament context, rain risk, and visitor personas
2. Scenario walkthrough where the agent retrieves memory, plans differentiated actions for each guest, executes, and writes outcomes back
3. Final outcomes for the day covering retention, revenue, reputation, and evolved memory patterns
4. Live backend validation for search, vector retrieval, and optional Langfuse traces
—
## Build the Memory Store
Memory documents are stored in a single `memory_store` collection with:
– Namespace tuples such as `(“guests”, guest_id)`, `(“fleet”, event_id)`, and `(“docs”, event_id)`
– Text payloads enriched by Voyage embeddings
– Metadata for category, timestamps, and related entities
This schema keeps visitor-specific, event-wide, and document memories queryable in one place. The agent benefits from scoped retrieval without managing multiple stores.
—
## Test Memory Retrieval: Vector and Hybrid Search
Two query endpoints are provided for validation:
– Pure vector search using Voyage embeddings via Atlas Vector Search
– Hybrid search combining vector similarity with lexical scoring over memory text
Hybrid search is useful in event operations where semantic intent appears alongside exact terms such as “rain delay” or “covered seating.” The current implementation performs lexical scoring over memory text in addition to vector scoring, all without requiring a separate Atlas Search text index.
—
## Add Visual RAG
Operational knowledge is not always textual. Five sample visual documents—maps, capacity charts, and response sheets—are seeded with multimodal embeddings. You can retrieve them by text query and send them to Claude Vision.
Example:
“`bash
curl -X POST “…”
-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 and forwards it to the LLM as part of the reasoning context, turning static SOPs into dynamic agent memory.
—
## Run the LangGraph Agent Path
The repo also includes a local LangGraph proof-of-concept (`scripts/run_poc.py`) that follows the same narrative:
– perceive: fetch current venue state and memory
– plan: ask Claude to generate persona-specific actions
– Hitl_gate: auto-approve in demo mode, with placeholders for production approvals
– act: update Atlas records
– reflect: write new inferences back to memory
This path mirrors the UI logic and demonstrates how retrieval, reasoning, and writes remain centralized in Atlas.
—
## Optional Langfuse Observability
If you add Langfuse keys to your environment:
– Retrieval endpoints emit traces named `api.search` and `api.hybrid_search`
– The LangGraph run emits a `langgraph.run_agent` observation
This optional instrumentation helps you inspect where latency and hallucinations occur without making tracing mandatory.
—
## Deploy to Vercel
To host the demo:
1. Add environment variables in Vercel:
– MONGODB_URI
– MONGODB_DATABASE
– MONGODB_APP_NAME
– VOYAGE_API_KEY
– ANTHROPIC_API_KEY (only if enabling hosted Vision RAG)
2. Ensure the Python runtime is set to 3.12
3. Deploy via your Vercel Git integration or CLI
Post-deployment checks include health verification, search endpoints, and, if configured, Langfuse traces.
—
## Production Notes and Constraints
This demo is intentionally scoped:
– The UI is deterministic and illustrative, not a real-time operations console
– Seed data is synthetic, good for patterns but not production profiling
– There is no authentication, rate limiting, tenant isolation, or CI/CD in this reference
You can run the entire flow on an Atlas Free cluster for development. For serious prototyping, choose a dedicated Atlas tier aligned with your data volume and query load.
—
## Where to Go Next
The demo keeps operational records, semantic memories, visual documents, checkpoints, and traces together in Atlas. From here you can:
– Add personas, SLA rules, and human approval workflows
– Integrate real event data sources and ticketing systems
– Expand multimodal use cases across hospitality, safety, and logistics
If this tutorial helped you, consider exploring more GenAI agent patterns in the MongoDB University catalog and the project’s GitHub repo.
—
### FAQ
**Q: Can I run this without an Anthropic key?**
A: Yes. The app will run but skip LLM-dependent features unless you configure an alternative LLM via environment variables.
**Q: Do I need a paid Atlas cluster?**
A: No. Atlas Free supports Vector Search and is sufficient for prototyping and light usage.
**Q: What does the smoke test validate?**
A: It checks MongoDB connectivity, Vector Search index readiness, hybrid search, visual document indexing, Vision RAG, optional Langfuse wiring, and collection statistics.
**Q: Can I swap Voyage for another embedding model?**
A: Yes. Replace Voyage embeddings in setup and search code with any compatible embedding provider supported by Atlas Vector Search.
**Q: Is the LangGraph path production-ready?**
A: Not out of the box. This is a POC. Production deployments should add authentication, tenant isolation, rate limiting, secret management, and CI testing.
—
## Conclusion
This tutorial shows how to build a focused event-venue operator agent that remembers, reasons, and acts using a single database backend. By keeping operational state, semantic memory, embeddings, visual documents, and agent checkpoints together in MongoDB Atlas, the demo achieves low-latency decisioning essential for time-sensitive scenarios like rain delays and capacity constraints. Whether used as a starting point for a production operations console or as a learning reference, this stack illustrates the practical value of unified data and agentic workflows in GenAI applications.
—
