Xây dựng Trình vận hành Địa điểm Sự kiện Tác nhân với MongoDB Atlas, Voyage và LangGraph

Hướng dẫn này bắt đầu từ điểm mà hầu hết các bản demo agent kết thúc: cung cấp cho agent bộ nhớ liên tục, bối cảnh vận hành và một nơi để ghi lại những gì đã xảy ra.

Một người điều hành sự kiện không chỉ cần một agent có thể tóm tắt báo cáo thời tiết hoặc tạo ra một kế hoạch chung chung. Người điều hành cần một agent có thể nhớ những gì đã xảy ra tại các sự kiện trước đó, truy xuất bối cảnh liên quan về khách tham quan và địa điểm, phản hồi các thay đổi vận hành theo thời gian thực và ghi lại kết quả dưới dạng bộ nhớ cho tình huống tương tự tiếp theo.

Chúng tôi đã xây dựng bản demo về người điều hành địa điểm tổ chức sự kiện này với MongoDB Atlas, nhúng Voyage AI, LangGraph và tùy chọn theo dõi Langfuse. Kịch bản demo là MongoDB Open, một giải đấu quần vợt cao cấp hư cấu diễn ra vào Ngày thi đấu thứ 6. Mưa đang đến gần, sức chứa khu vực có mái che bị hạn chế và người điều hành có hai hành trình khách tham quan khác nhau cần bảo vệ: Mikiko, một người tham dự lần đầu cố gắng tận dụng tối đa khuôn viên, và Nina, một khách VIP với kỳ vọng về dịch vụ khách sạn và một lịch sử mà agent có thể truy xuất.

Đây không phải là một nghiên cứu điển hình về khách hàng hay một triển khai sản xuất. Đây là một kịch bản xây dựng hư cấu lấy cảm hứng từ kinh tế vận hành sự kiện thực tế. Các sự kiện quần vợt lớn cho thấy lý do tại sao những quyết định này lại quan trọng: US Open 2025 đã phá vỡ kỷ lục về số người tham dự, lượng người xem và phạm vi tiếp cận kỹ thuật số, đồng thời cung cấp 90 triệu đô la tiền thưởng cho các tay vợt; USTA cũng cho biết US Open kéo dài ba tuần tạo ra hơn 1,2 tỷ đô la tác động kinh tế hàng năm cho Thành phố New York. Kỳ vọng của người hâm mộ cao cấp cũng rất cao: PwC phát hiện ra rằng 60% người hâm mộ thể thao có thu nhập cao tại Mỹ sẽ chi hơn 250 đô la cho một sự kiện đặc biệt và 20% sẽ chi hơn 1.000 đô la. Thời tiết tạo thêm một lớp rủi ro khác, đó là lý do tại sao Cục điều tra dân số Hoa Kỳ hiện theo dõi tác động tiền tệ của thời tiết khắc nghiệt lên doanh số bán hàng của doanh nghiệp thông qua Khảo sát Xu hướng và Triển vọng Kinh doanh của mình.

Agent demo MongoDB Open không chỉ tạo ra một kế hoạch khả thi. Nó đọc trạng thái hiện tại của địa điểm, truy xuất bộ nhớ sự kiện trước đó, phân biệt giữa các phân khúc khách tham quan và hành động. Đồng thời, sức chứa dịch vụ khách sạn vẫn còn và ghi lại kết quả để lần gián đoạn tiếp theo có thể được xử lý với nhiều bối cảnh hơn. Xem toàn bộ kho lưu trữ tại đây.

Bản demo được chia thành ba lớp:

Vào cuối hướng dẫn, bạn sẽ có một ứng dụng FastAPI được hỗ trợ bởi MongoDB Atlas có thể chạy cục bộ và triển khai lên Vercel.

Kho lưu trữ hiện tại nên được coi là một bản demo tham khảo, không phải là một nền tảng sản xuất. Không có xác thực sản xuất, không có bộ CI và agent LangGraph đầy đủ vẫn là một đường dẫn xác thực dựa trên tập lệnh thay vì một endpoint lưu trữ công khai.

Kiến trúc tập trung vào MongoDB Atlas như cả lớp vận hành và bộ nhớ. Tốc độ rất quan trọng trong kịch bản người điều hành địa điểm tổ chức sự kiện vì khoảng thời gian hữu ích để hành động là ngắn. Nếu mưa còn 20 phút nữa và không gian dịch vụ khách sạn có mái che đang lấp đầy, người điều hành không cần một bảng điều khiển sau sự kiện hay một bản tóm tắt hàng loạt vài phút sau đó. Agent cần đọc trạng thái hiện tại của địa điểm, truy xuất bộ nhớ liên quan, quyết định phải làm gì và ghi lại kết quả trong khi

Dù vẫn còn khả năng bảo vệ trải nghiệm của khách hàng.

Đó là lý do tại sao loại cơ sở dữ liệu và cách sử dụng nó là những lựa chọn thiết kế hệ thống quan trọng. Hồ sơ vận hành, bộ nhớ ngữ nghĩa, vector embeddings, tài liệu hình ảnh và hành động của agent đều nằm trong cùng một lớp dữ liệu. Agent không cần phải chờ một pipeline phân tích riêng, đồng bộ dữ liệu vào cơ sở dữ liệu vector thứ hai, hay đối chiếu những gì lớp bộ nhớ nói với những gì hệ thống vận hành nói. Atlas đóng vai trò vừa là hệ thống ghi chép vừa là lớp truy xuất cho vòng lặp agent: nhận biết những gì đã thay đổi, truy xuất ngữ cảnh phù hợp, thực hiện hành động và lưu lại những gì đã xảy ra cho sự kiện tiếp theo.

Đây cũng là lý do tại sao bản demo giữ bộ nhớ trong MongoDB thay vì coi nó như một thành phần phụ trợ. Agent không chỉ truy xuất các đoạn thông tin rời rạc; nó đang tổng hợp ngữ cảnh vận hành. Một quyết định hữu ích có thể cần đồng thời lịch sử khách truy cập, trạng thái hiện tại của địa điểm, tồn kho dịch vụ khách sạn, các mẫu chậm trễ do mưa trước đây và các tài liệu hình ảnh liên quan. Với Atlas, những mảnh thông tin đó có thể được truy vấn cùng nhau thay vì bị phân tán trên các hệ thống riêng biệt.

Bản demo sử dụng bốn lớp trạng thái chính:

Trước khi bắt đầu, hãy đảm bảo bạn có:

Clone repo và cài đặt dependencies: GitHub repo

Nếu bạn chỉ muốn xem ứng dụng trước khi thiết lập thông tin xác thực, hãy bắt đầu với bản demo Vercel trực tiếp. Bản demo được lưu trữ sử dụng cùng giao diện người dùng và cấu trúc triển khai như repo, trong khi thiết lập cục bộ cho phép bạn tự chạy toàn bộ seed, smoke test, Vision RAG và các đường dẫn LangGraph.

Langfuse là tùy chọn cho khả năng quan sát:

Script này tạo các collections và khởi tạo Atlas Vector Search index, sau đó chờ tối đa 60 giây để index chuyển sang trạng thái READY.

Sau đó seed các tài liệu văn bản và hình ảnh:

Trong một terminal thứ hai, chạy smoke test:

Với server đang chạy trong một terminal khác, smoke test kiểm tra tình trạng MongoDB, Atlas Vector Search, hybrid search, lập chỉ mục tài liệu hình ảnh, Vision RAG, kết nối Langfish tùy chọn và thống kê collections.

Kho lưu trữ bộ nhớ nằm trong collection memory_store. Mỗi tài liệu bộ nhớ bao gồm namespace, key, payload văn bản, metadata danh mục và một embedding.

Namespaces cho phép ứng dụng phân tách các loại bộ nhớ khác nhau:

Lựa chọn thiết kế này hợp lý hóa quyền truy cập của agent vào cả dữ liệu vận hành và bộ nhớ cho các hoạt động của chính nó. Bộ nhớ agent trong sản xuất có nhiều khía cạnh: một số bộ nhớ thuộc về một người, một số thuộc về một địa điểm, một số thuộc về quy trình kinh doanh và một số thuộc về tài liệu tham khảo. Atlas cung cấp cho ứng dụng một backend duy nhất cho tất cả chúng trong khi vẫn cho phép truy xuất có phạm vi, nhờ vào mô hình dữ liệu linh hoạt của nó.

Tại thời điểm này, kho lưu trữ bộ nhớ đã được khởi tạo và seed. Collection memory_store chứa các tài liệu bộ nhớ đã được nhúng, và Atlas Vector Search index đã sẵn sàng.

Phần này cho thấy cách truy vấn trực tiếp kho lưu trữ bộ nhớ đó. Bạn không cần chạy các truy vấn này để tạo bộ nhớ; chúng là các lệnh gọi xác thực giúp bạn kiểm tra cách truy xuất hoạt động trước khi agent sử dụng cùng đường dẫn backend trong kịch bản.

Điểm cuối truy xuất đơn giản nhất là tìm kiếm vector:

Phương pháp này nhúng truy vấn với Voyage và tìm kiếm trong Atlas các bộ nhớ tương tự về mặt ngữ nghĩa.

Điểm cuối hybrid kết hợp độ tương tự vector với điểm số từ vựng trên văn bản bộ nhớ:

Phản hồi bao gồm điểm vector, điểm từ vựng và điểm hybrid kết hợp. Điều này hữu ích vì các truy vấn vận hành sự kiện thường pha trộn giữa ý định ngữ nghĩa và các thuật ngữ vận hành chính xác. "Trận đấu bị hoãn vì mưa", "đặt bàn ăn tối" và "chỗ ngồi có mái che" đều có ý nghĩa như các khái niệm, nhưng các từ chính xác vẫn mang tín hiệu mạnh mẽ.

Trong triển khai này, tìm kiếm hybrid có nghĩa là Atlas Vector Search kết hợp với điểm số từ vựng xác định trên văn bản bộ nhớ. Nó hoạt động với chỉ mục vector hiện có và dữ liệu đã được seed, vì vậy người đọc không cần tạo chỉ mục văn bản Atlas Search riêng cho hướng dẫn này. Một mở rộng tự nhiên sẽ là thêm một chỉ mục văn bản Atlas Search chuyên dụng và kết hợp các kết quả đó với truy xuất vector.

Kiến thức vận hành không phải lúc nào cũng là văn bản. Bản đồ khả năng tiếp cận, biểu đồ công suất khách sạn, ma trận dị ứng, bảng phản ứng thời tiết và sơ đồ sơ tán thường tồn tại dưới dạng hình ảnh hoặc PDF.

Kho lưu trữ này seed năm tài liệu trực quan:

Mỗi hình ảnh được nhúng với Voyage multimodal embeddings và lưu trữ trong bộ sưu tập bộ nhớ. Một truy vấn văn bản sau đó có thể truy xuất tài liệu trực quan có liên quan:

Điểm cuối truy xuất tài liệu trực quan phù hợp nhất từ Atlas và gửi nó đến Claude Vision cùng với câu hỏi của người dùng. Điều này biến tài liệu vận hành tĩnh thành ngữ cảnh agent có thể truy xuất được.

Kho lưu trữ cũng bao gồm một LangGraph proof-of-concept:

Đồ thị tuân theo cùng một câu chuyện sự kiện quần vợt như giao diện người dùng có hướng dẫn, nhưng chạy nó qua đường dẫn agent trực tiếp:

Đầu ra được tạo ra sẽ khác nhau vì Claude đang lập kế hoạch từ bộ nhớ đã truy xuất, nhưng các bộ nhớ đã seed và prompt được căn chỉnh với kịch bản trận đấu quần vợt bị hoãn vì mưa.

Langfuse là tùy chọn. Nếu bạn thêm khóa vào .env, ứng dụng sẽ phát ra tracing xung quanh các lệnh gọi truy xuất:

Kiểm tra xem máy chủ đang chạy đã được cấu hình chưa:

Chạy một truy xuất