mongodb-developer/event-venue-operator

# 活动场馆运营 Agent 基于 MongoDB Atlas 构建的 Agentic 活动场馆运营 Agent 演示。展示了三层记忆架构（长期、短期、共享）、结合 Voyage AI 多模态 embeddings 的混合检索、可选的 Langfuse 追踪，以及在顶级网球锦标赛因雨延迟场景下基于角色细分的 Agent 决策。 **在线演示：** [event-venue-operator.vercel.app](https://event-venue-operator.vercel.app/) ## 这是什么 这是一个为探索者在 MongoDB 上实践 Agentic 模式而提供的演示种子。展示了如何建模 Agent 记忆、从过往活动中检索模式，并按角色类型细分操作——所有这些都由单个 Atlas 集群提供支持。 场景叙述：一个 AI 运营 Agent 正在第 6 天监控一场网球锦标赛。即将下大雨。Agent 读取实时的场馆状态，通过向量搜索从过往活动中检索模式，规划特定于角色的操作（引导初次来访的游客前往空闲球场；为高级访客预订带顶棚的餐饮区），并将结果写回长期记忆。 可见的 UI 在设计上是确定性的，以保证演示的可靠性。后端的验证点是真实的：Atlas 设置、种子记忆、Voyage embeddings、混合搜索、Atlas Vector Search、视觉文档 RAG、可选的 Langfuse 可观测性，以及可运行的 LangGraph Agent 路径。 ## 这不是什么 这不是一个生产级的 Agentic 平台。这里仅对模式进行了演示；生产环境的加固（CI、生产级可观测性、错误恢复、实时操作员审批）有意不在本教程的范围内。 ## 三种交互方式 ### 1. 舞台演示（确定性 UI） ``` uv run python -m event_venue_operator.server ``` 打开 http://127.0.0.1:8000。依次体验三个选项卡的叙述，然后使用第四个选项卡进行实时后端验证： - **Tab 1 — 场馆运营**（下午 2:15）：带有球场、款待服务和 KPI 的实时仪表板。天气指示器显示 90 分钟后将有降雨。 - **Tab 2 — 场景（下雨）**：逐步的 Agent 演练。五个步骤：READ 短期记忆、READ 长期记忆（向量搜索）、PLAN、ACT（Agent 项目出现在访客视图中）、WRITE（记忆更新）。在 Mikiko（初次来访者，蓝色）和 Nina（高级访客，紫色）之间切换。 - **Tab 3 — 最终结果**（晚上 10:00）：每日总结。收入、留存率、声誉提升。为未来活动写入的记忆模式。 - **Tab 4 — 实时后端**：对 Atlas 运行实时检索调用，并在配置后发出可选的 Langfuse 追踪。 UI 的数值是硬编码的，以确保舞台演示效果可预测。请使用下方的 API 端点和脚本来测试实时后端。 ### 2. 实时 Agent（真实 LangGraph 执行） ``` uv run python scripts/run_poc.py ``` 端到端运行完整的 LangGraph 链： 1. **perceive** — 从 Atlas 读取（通过向量搜索获取访客记忆 + 整体模式） 2. **plan** — 调用 Claude Sonnet 4.6 生成行程安排 3. **hitl_gate** — 保留审批插入点并在 V1 中自动批准 4. **act** — 执行工具（update_itinerary, book_reservation） 5. **reflect** — 将新的推断写回记忆库 Agent 的决策是非确定性的，取决于检索到的记忆，但种子场景现在遵循与舞台 UI 相同的 Mikiko/Nina 网球因雨延迟的故事情节。 配置 Langfuse 密钥后，此脚本会发出运行级别的 `langgraph.run_agent` 观察，以便可以在 UI 之外验证实时 Agent 路径。 ### 3. API 探索 FastAPI 服务器暴露了用于直接与记忆库交互的端点： - `GET /api/search?q=...&namespace=guests` — 对记忆进行 Atlas Vector Search - `GET /api/hybrid-search?q=...&namespace=guests` — 对记忆进行向量+词法混合检索 - `POST /api/unified-search` — 跨 namespace 搜索并结合用户画像事实 - `POST /api/vision-rag/query` — 向量搜索 + Claude Vision 读取操作文档 - `GET /api/debug/embed?text=...` — 直接查看 Voyage embeddings - `GET /api/observability/status` — 确认是否配置了 Langfuse 追踪 ## 设置 ### 前提条件 - Python 3.12+ - 启用了 Atlas Vector Search 的 MongoDB Atlas 集群 - Anthropic API key - Voyage AI API key ### 安装 ``` git clone https://github.com/mikikob-mongodb/event-venue-operator.git cd event-venue-operator uv sync ``` ### 配置 ``` cp .env.example .env # 编辑 .env: MONGODB_URI, ANTHROPIC_API_KEY, VOYAGE_API_KEY # 可选: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST ``` ### 初始化 Atlas ``` uv run python scripts/setup_atlas.py # 等待约 60 秒以构建 vector index ``` ### 种子数据 ``` uv run python scripts/seed_data.py uv run python scripts/seed_visual_docs.py ``` ### 运行 ``` # Stage 演示 uv run python -m event_venue_operator.server # Live agent uv run python scripts/run_poc.py ``` ### 验证 在一个终端中运行服务器的情况下，执行： ``` uv run python scripts/smoke_test.py ``` 冒烟测试会检查 MongoDB 健康状况、Atlas Vector Search、混合搜索、视觉文档索引、Vision RAG、Langfuse 连接以及集合统计信息。 ## 架构 - **前端**：位于 `static/index.html` 的原生 HTML/JS（三个选项卡的故事流加上实时后端验证选项卡） - **后端**：位于 `src/event_venue_operator/server.py` 的 FastAPI - **Agent**：位于 `src/event_venue_operator/graph.py` 的 LangGraph 链 (perceive -> plan -> hitl_gate -> act -> reflect) - **数据**：MongoDB Atlas (memory_store, guests, visits, venue_status, weather_events, venues, reservations, agent_actions) - **Embeddings**：Voyage AI `voyage-multimodal-3.5`（1024d，跨模态文本+图像） - **LLM**：Claude Sonnet 4.6（plan 节点），Claude Sonnet 4.5（vision RAG） - **可观测性**：当配置了 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY` 时，针对检索端点和实时 LangGraph 运行的可选 Langfuse 追踪 ## 记忆层 | 层级 | 存储 | 检索方式 | |---|---|---| | 长期记忆 | 带有 Voyage embeddings 的 `memory_store` 集合 | Atlas Vector Search 和混合检索 | | 短期记忆 | `venue_status`, `weather_events` 集合 | 直接文档查找 | | 共享记忆 | `agent_actions` 集合 | Agent 与子 Agent 的协调日志 | ## 用户画像 - **Mikiko 初次来访者**（蓝色，`#60a5fa`）— 首次到访，关注比赛，正在探索场地 - **Nina 高级访客**（紫色，`#a78bfa`）— 拥有高级访问权限，有接待服务记录，偏好带顶棚的座位 ## 仓库结构 ``` event-venue-operator/ ├── src/event_venue_operator/ # Package: server, agent, db, config, seed ├── scripts/ # Setup, seeding, POC runner, visual doc generation ├── static/ # Stage demo HTML + visual documents └── docs/ # Architecture notes and feature inventory ``` ## 范围边界 - 舞台 UI 在设计上是引导式/静态的；API 端点和脚本用于测试实时后端的验证点。 - Change stream 监听器作为扩展路径存在，但 V1 教程并未将它们接入 UI。 - `hitl_gate` 作为生产审批的占位符包含在图结构中，但 V1 会自动批准操作。 - CI、评估测试框架、生产环境错误处理和部署加固不在此教程仓库的范围内。 ## 延伸阅读 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 设计决策 - [docs/LANGGRAPH.md](docs/LANGGRAPH.md) — 实时 Agent 演练 - [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) — 可选的 Langfuse 设置和验证 - [docs/VERCEL.md](docs/VERCEL.md) — 托管预览部署计划 - [docs/features.md](docs/features.md) — 当前功能清单 ## 许可证 MIT 许可证。详情请参阅 LICENSE 文件。

标签：AI智能体, LangChain, MongoDB, 向量搜索, 检索增强生成, 活动运营管理, 轻量级, 逆向工具