Xây dựng AI Agent quản lý sự kiện với MongoDB Atlas, Voyage và LangGraph

Giới thiệu

Hướng dẫn này bắt đầu từ nơi mà hầu hết các bản demo về tác nhân (agent) dừng lại: cung cấp cho tác nhân bộ nhớ bền vững, ngữ cảnh vận hành và 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 tác nhân có khả năng tóm tắt dự báo thời tiết hay tạo ra một kế hoạch chung chung. Người điều hành cần một tác nhân có thể ghi nhớ những gì đã xảy ra tại các sự kiện trước đó, truy xuất ngữ cảnh liên quan đến khách tham quan và địa điểm, phản hồi các thay đổi vận hành trực tiếp, và ghi lại kết quả như một bộ nhớ cho tình huống tương tự tiếp theo.

Chúng tôi đã xây dựng bản demo điều hành địa điểm sự kiện này với MongoDB Atlas, Voyage AI embeddings, LangGraph và tính năng theo dõi tùy chọn Langfuse. Kịch bản demo là MongoDB Open, một giải đấu quần vợt cao cấp giả định vào ngày thi đấu thứ 6. Trời sắp mưa, sức chứa tại các khu vực có mái che bị hạn chế và người điều hành cần bảo vệ hành trình của hai nhóm khách tham quan khác nhau: Mikiko, một người tham dự lần đầu đang cố gắng tận dụng tối đa thời gian tại sân, và Nina, một khách mời cao cấp với những kỳ vọng về dịch vụ khách hàng và một lịch sử mà tác nhân 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 bản triển khai thực tế. Đây là một kịch bản xây dựng giả định 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ỡ các kỷ lục về số lượng người tham dự, lượt xem và phạm vi tiếp cận kỹ thuật số, đồng thời cung cấp 90 triệu USD tổng tiền thưởng cho người chơi; USTA cũng cho biết giải US Open kéo dài ba tuần tạo ra hơn 1,2 tỷ USD 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 lớn: PwC nhận thấy rằng 60% người hâm mộ thể thao có thu nhập cao tại Hoa Kỳ sẵn sàng chi hơn 250 USD cho một sự kiện đặc biệt, và 20% sẵn sàng chi hơn 1.000 USD. Thời tiết tạo thêm một tầng rủi ro, đó là lý do tại sao Cục Thống kê 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 đối với doanh số kinh doanh thông qua Khảo sát Triển vọng và Xu hướng Kinh doanh.

Tác nhân demo MongoDB Open không chỉ tạo ra một kế hoạch hợp lý. Nó đọc trạng thái địa điểm hiện tại, 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, khi sức chứa dịch vụ khách hàng vẫn còn, nó ghi lại kết quả để các sự cố tiếp theo có thể được xử lý với nhiều ngữ cảnh hơn. Xem kho lưu trữ đầy đủ tại đây.

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

Những gì bạn sẽ xây dựng

Đến cuối hướng dẫn này, 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.

Ứng dụng bao gồm:

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à toàn bộ tác nhân LangGraph vẫn là một lộ trình xác thực dựa trên tập lệnh thay vì một điểm cuối công khai được lưu trữ.

Tổng quan kiến trúc

Kiến trúc tập trung vào MongoDB Atlas như là lớp vận hành và lớp bộ nhớ. Tốc độ rất quan trọng trong kịch bản điều hành địa điểm sự kiện vì khoảng thời gian hữu ích để hành động rất ngắn. Nếu trời sắp mưa trong 20 phút nữa và không gian có mái che đang dần đầ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 đó. Tác nhân cần đọc trạng thái địa điểm hiện tại, 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 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. Các bản ghi vận hành, bộ nhớ ngữ nghĩa, vector embeddings, tài liệu trực quan và các hành động của tác nhân đều nằm trong cùng một lớp dữ liệu. Tác nhân không cần phải chờ đợi một đường ống phân tích riêng biệt, đồng bộ hóa dữ liệu vào cơ sở dữ liệu vector thứ hai, hoặc đố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 lưu trữ hồ sơ vừa là lớp truy xuất cho vòng lặp tác nhân: nhận thức những gì đã thay đổi, truy xuất ngữ cảnh phù hợp, thực hiện hành động và lưu trữ 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ụ. Tác nhân không chỉ truy xuất các đoạn dữ liệu; nó đang soạn thảo ngữ cảnh vận hành. Một quyết định hữu ích có thể cần lịch sử khách tham quan, trạng thái địa điểm hiện tại, hàng tồn kho dịch vụ khách hàng, các mô hình trì hoãn do mưa trước đó và các tài liệu trực quan liên quan cùng một lúc. Với Atlas, những phần đó 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:

Thiết lập

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

Sao chép kho lưu trữ và cài đặt các phụ thuộc: GitHub repo

Nếu bạn chỉ muốn kiểm tra ứ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 tuyến. Bản demo được lưu trữ sử dụng cùng giao diện người dùng và hình thức triển khai như kho lưu trữ, trong khi thiết lập cục bộ cho phép bạn tự chạy toàn bộ quá trình seed, kiểm tra smoke test, Vision RAG và các lộ trình LangGraph.

Tạo tệp môi trường của bạn:

Thêm các giá trị bắt buộc:

Langfuse là tùy chọn để quan sát:

Khởi tạo Atlas:

Tập lệnh này tạo các bộ sưu tập (collections) và khởi động chỉ mục Atlas Vector Search, sau đó đợi tối đa 60 giây để chỉ mục chuyển sang trạng thái READY.

Sau đó seed văn bản và tài liệu trực quan:

Khởi động ứng dụng:

Mở http://127.0.0.1:8000/.

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

Với máy chủ đang chạy trong một terminal khác, smoke test sẽ kiểm tra tình trạng của MongoDB, Atlas Vector Search, tìm kiếm lai (hybrid search), lập chỉ mục tài liệu trực quan, Vision RAG, kết nối Langfuse tùy chọn và số liệu thống kê bộ sưu tập.

Hướng dẫn giao diện người dùng

Giao diện người dùng có bốn tab:

Xây dựng kho lưu trữ bộ nhớ

Kho lưu trữ bộ nhớ nằm trong bộ sưu tập memory_store. Mỗi tài liệu bộ nhớ bao gồm một không gian tên (namespace), khóa, nội dung văn bản, siêu dữ liệu danh mục và một embedding.

Các không gian tên cho phép ứng dụng tách biệt các loại bộ nhớ khác nhau:

Lựa chọn thiết kế này giúp hợp lý hóa quyền truy cập của tác nhân 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ớ tác nhân trong môi trường 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ề một quy trình kinh doanh và một số thuộc về các 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 theo phạm vi, nhờ vào mô hình dữ liệu linh hoạt của nó.

Kiểm tra truy xuất bộ nhớ với Vector và Hybrid Search

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