MongoDB・Voyage・LangGraphでイベント運営エージェントを構築

このチュートリアルは、多くのエージェントデモが行き着く先から始めます。つまり、エージェントに永続的な記憶機能と運用コンテキストを与え、結果を記録できる場所を提供することです。

イベント運営者が必要とするのは、単に天候予報を要約したり汎用的な計画を立てたりするだけのエージェントではありません。必要なのは、過去のイベントで何があったかを記憶し、関連する来場者や会場の情報を取得し、現場の状況変化に対応し、その結果を次の類似ケースのための記憶として記録できるようなエージェントです。

本デモでは、MongoDB Atlas、Voyage AI の埋め込みベクトル、LangGraph を使用し、必要に応じて Langfuse によるトレーシングも追加しています。シナリオは架空の高級テニス大会「MongoDB Open」の 6 日目です。雨雲が迫り、屋内ホスピタリティエリアの収容能力に限界があります。運営者は、2 つの異なる来場者体験を守る必要があります。1 人目は初めて参加するミキコさんで、会場を最大限に活用したいと考えています。もう 1 人目はニナさんで、ホスピタリティへの高い期待を持つ特別ゲストです。エージェントは彼女の過去の履歴も取得できます。

これは顧客事例の紹介や本番環境での導入事例ではありません。実際のイベント運営の経済構造を参考に、架空のビルダーシナリオとして構築されたものです。

主要なテニス大会の動向を見れば、こうした判断がいかに重要かがわかります。2025 年の全米オープンでは観客数、視聴者数、デジタルリーチのすべての記録が更新され、選手への総報酬は 9,000 万ドルに達しました。また、米国テニス協会（USTA）によると、3 週間にわたる大会運営はニューヨーク市に対して年間 12 億ドル以上の経済効果をもたらしています。

ファンの期待も高まっています。PwC の調査では、所得層の高い米国のスポーツファン 60% が特別イベントに 250 ドル以上を支出する意向を示し、20% は 1,000 ドル以上を支払うと回答しています。

さらに気象リスクも無視できません。このため米国国勢調査局は、ビジネス動向・展望調査（Business Trends and Outlook Survey）を通じて、極端な天候が売上にもたらす金銭的インパクトを追跡する体制を整えています。

MongoDB のオープンデモエージェントは、単に妥当な計画を提示するだけではありません。現在の会場状態を読み込み、過去のイベントの記憶から情報を取得し、来場者のセグメントを区別して行動を起こします。同時に、ホスピタリティ部門のキャパシティがまだ余裕があるかを確認し、その結果を書き戻すことで、次回のトラブル発生時にはより豊富な文脈に基づいた対応が可能になります。

詳細は以下のリポジトリでご確認ください。

このデモは 3 つのレイヤーで構成されています。

• オペレーターがストーリーを追跡しやすいよう設計された、ガイド付きの決定論的 UI
• 読者が直接アクセスできる公開アプリリンクを提供する、Vercel 上でホストされたデモ環境

Atlas Vector Search、ベクトルと語彙のハイブリッド検索、視覚ドキュメント RAG、LangGraph の実行、そしてオプションの Langfuse トレースに関するライブ API エンドポイントとスクリプトを用意しました。これらは、このスタック全体がどのように連携して動作するかを実証するためのものです。

何を作るのか

このチュートリアルを終える頃には、ローカルで実行可能かつ Vercel へのデプロイも可能な、MongoDB Atlas をバックエンドに持つ FastAPI アプリケーションが完成します。

本アプリには以下の要素が含まれます：

• イベント運営のストーリーとライブなバックエンド検証を行う、4 つのタブからなるガイド付き UI
• 運用状態、セマンティックメモリ、エージェントの行動、LangGraph のチェックポイントを管理するための Atlas コレクション
• Atlas に保存された Voyage のマルチモーダル埋め込みベクトル
• メモリ検索のための Atlas Vector Search
• ベクトル類似度と語彙スコアを組み合わせたハイブリッド検索エンドポイント
• 視覚的な運用ドキュメントを検索し、Claude Vision へ渡すためのビジョン RAG エンドポイント
• 検索呼び出しやライブな LangGraph の実行を追跡するためのオプションの Langfuse トレーシング
• 同じく「雨延期」ストーリーに沿って動作する、実行可能な LangGraph スクリプト
• ホスト版デモ用の Vercel デプロイ設定

現在のリポジトリは、本番環境向けのプラットフォームというよりは、参照用デモとして扱うべきです。本番レベルの認証機能はなく、CI システムも用意されていません。また、LangGraph エージェント全体は公開されたホストエンドポイントではなく、スクリプトベースによる検証パスとして実装されています。

アーキテクチャ概要

このアーキテクチャの中心には、運用層と記憶層の両方を担う MongoDB Atlas があります。イベント会場運営のシナリオでは、スピードが何より重要です。利用可能なアクションの時間は限られているからです。

もし雨が 20 分後に降り出し、屋外のホスピタリティスペースが満杯になりつつあるなら、オペレーターは事後のダッシュボードや数分後のバッチサマリーを待っている時間はありません。エージェントは現在の会場状態を読み込み、関連する記憶情報を取得し、何をすべきかを判断して、結果を書き戻す必要があります。そしてそれは、ゲスト体験を守るための余地がまだ残っているうちに完了させなければなりません。

だからこそ、どのデータベースを選ぶか、どう活用するかという点は、システム設計における決定的な選択となります。運用記録、意味的な記憶、ベクトル埋め込み、視覚ドキュメント、そしてエージェントの行動は、すべて同じデータ層に存在します。エージェントが別々の分析パイプラインを待ったり、データを第 2 のベクトルデータベースに同期したり、記憶層と運用システムの内容を照合する必要はありません。

Atlas は、イベントループにおける「記録システム」としての役割と、「文脈取得」の役割を同時に果たします。つまり、何が変わったかを感知し、適切な文脈を取得し、行動を起こし、その結果を次のイベントのために永続化させるのです。

このデモがメモリを MongoDB に保持し、サイドカーとして扱うのではなく、エージェントが単なるチャンクの取得ではなく、運用コンテキストの構成を行っている理由でもあります。有用な意思決定には、訪問者の履歴、現在の会場状況、ホスピタリティ在庫、過去の雨による遅延パターン、関連する視覚ドキュメントなど、複数の要素を同時に考慮する必要があります。Atlas を利用すれば、これらの情報を別々のシステムに散在させるのではなく、クエリ可能な状態として統合して保持できます。

imageキャプション：MongoDB Atlas は、デモの運用状態、意味的メモリ、視覚ドキュメントの埋め込みベクトル、エージェントの行動、そして LangGraph のチェックポイントを 1 つのバックエンドに格納しています。

このデモでは、主に以下の 4 つの状態レイヤーを使用します。

• 運用記録：ゲスト情報、訪問履歴、会場状況、気象イベント、予約状況、イベント指標、およびエージェントの行動
• 意味的メモリ：memory_store（Voyage の埋め込みベクトルと Atlas Vector Search を利用）
• 視覚ドキュメント：運用画像を同じメモリストアに埋め込み、画像由来のマルチモーダル埋め込みやドキュメントメタデータとして扱う
• エージェント状態：LangGraph のチェックポイントおよびチェックポイント書き込み

セットアップ

作業を開始する前に、以下の準備を確認してください。

• Python 3.12 以降
• uv のインストール済み
• Vector Search が有効化された MongoDB Atlas クラスター（無料設定可能）
• Anthropic API キー（または好みの LLM を使用し、API キーを再設定することも可能）
• Voyage API キー（無料設定可能）

リポジトリをクローンして依存関係をインストールします：GitHub リポジトリ

Copy CodeCopiedUse a different Browser

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

cd event-venue-operator

uv sync

まずは本格的な環境構築の前に、アプリの動作を確認したい場合は Vercel 上のライブデモを覗いてみましょう。ホスト版のデモはリポジトリと同じ UI と構成を採用していますが、ローカル環境でセットアップすれば、シード処理やスモークテスト、Vision RAG、LangGraph のパスを実際に動かして検証できます。

環境変数ファイルを作成します:

cp .env.example .env

必要な値を以下のように設定してください:

MONGODB_URI=mongodb+srv://:@.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 を使用しますが、必須ではありません:

LANGFUSE_PUBLIC_KEY=

LANGFUSE_SECRET_KEY=

LANGFUSE_HOST=https://cloud.langfuse.com

Atlas の初期化を行います:

uv run python scripts/setup_atlas.py

このスクリプトはコレクションの作成と Atlas Vector Search インデックスの開始を行い、インデックスが「READY」状態になるまで最大 60 秒待機します。

次に、テキストデータと視覚ドキュメントをシード（初期化）します:

uv run python scripts/seed_data.py

uv run python scripts/seed_visual_docs.py

アプリを起動します:

uv run python -m event_venue_operator.server

ブラウザで http://127.0.0.1:8000/ にアクセスしてください。

別のターミナルウィンドウを開き、スモークテストを実行します:

別のブラウザを使用してください

uv run python scripts/smoke_test.py

サーバーは別ターミナルで稼働させておき、スモークテストを実行します。これにより、MongoDB の健全性、Atlas Vector Search、ハイブリッド検索機能、視覚ドキュメントインデックス化、Vision RAG（Retrieval-Augmented Generation）、オプションの Langfuse 連携設定、およびコレクション統計が確認されます。

UI の操作手順

UI には 4 つのタブがあります。

1. イベント運営ダッシュボード

イベントのコンテキストを設定します。具体的には、テニストーナメント開催中、雨雲接近、ホスピタリティ上の制約、そして 2 種類の訪問者ペルソナという状況です。

1. シナリオウォークスルー

エージェントが現在の状態を読み取り、長期記憶から情報を取得。その後、対象者に合わせた行動を計画し、運営者の代理として実行、その結果を再度メモリに書き込みます。

1. 1 日の最終成果

顧客維持率（リテンション）、収益、評判、そして新たに生成された記憶パターンがここに集約されます。

1. バックエンドのリアルタイム検証

Atlas を対象とした検証呼び出し機能です。ブラウザからベクトル検索やハイブリッド検索をトリガーでき、Langfuse のキーが設定されている場合は、関連するトレーシング情報を出力します。

メモリストアの構築

メモリストアは memory_store コレクション内に存在します。各メモリ文書には、名前空間（namespace）、キー、テキストペイロード、カテゴリメタデータ、そして埋め込みベクトルが含まれます。

名前空間を用いることで、アプリ内で異なる種類の記憶を明確に区別できます。

• （"guests", guest_id）：訪問者固有の記憶用
• （"fleet", event_id）：運営者全体向けのイベントパターン用
• （"docs", event_id）：視覚的な運用ドキュメント用

この設計により、エージェントは運用データと自身の操作履歴（メモリ）へのアクセスを一元化できます。実環境におけるエージェントのメモリには多様な側面があります。個人に紐づくもの、場所に関連するもの、業務プロセス固有のもの、あるいは参照ドキュメントに基づくものなどです。Atlas は柔軟なデータモデルを活用することで、これらすべてのデータを単一のバックエンドで管理しつつ、必要な範囲での検索（スコープ付き取得）も可能にします。

ベクトル検索とハイブリッド検索によるメモリ取得の検証

この時点で、メモリストアは初期化され、サンプルデータが読み込まれています。memory_store コレクションには埋め込み形式のメモリドキュメントが格納されており、Atlas Vector Search のインデックスも利用可能です。

ここでは、そのメモリストアを直接クエリする方法を示します。メモリの作成自体にこれらのクエリを実行する必要はありません。あくまで、シナリオ実行中にエージェントが同じバックエンド経路を利用する前に、検索機能がどのように動作するかを検証するための確認用呼び出しです。

最もシンプルな取得エンドポイントはベクトル検索です：

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

このコマンドは、Voyage によってクエリを埋め込み（エンベッド）、Atlas 内で意味的に類似したメモリを検索します。

一方、ハイブリッドエンドポイントは、テキストの語彙的スコアリングとベクトル類似度の両方を組み合わせて検索を行います：

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

レスポンスにはベクトルスコア、レキシカル（語彙）スコア、そしてこれらを組み合わせたハイブリッドスコアが含まれています。これはイベント運営のクエリにおいて、意味的な意図と正確な運用用語が混在するケースに対応するために有用です。「降雨による試合延期」「夕食会の予約」「屋根付きの座席」はすべて概念として重要ですが、それでも正確な単語自体が強力なシグナルとなる場合があります。

今回の実装では、ハイブリッド検索とは「Atlas Vector Search」と「メモリ内のテキストに対する決定論的な語彙スコアリング」を組み合わせることを意味します。既存のベクトルインデックスと初期データを活用するため、本チュートリアルで別途 Atlas Search のテキストインデックスを作成する必要はありません。より自然な拡張方法として、専用の Atlas Search テキストインデックスを追加し、その結果をベクトル検索の結果と組み合わせるアプローチも考えられます。

視覚的 RAG の追加

運用知識は常にテキストで記述されているわけではありません。アクセシビリティマップ、ホスピタリティの収容能力チャート、アレルゲン行列、天候対応シート、避難図などは、画像や PDF として存在していることが一般的です。

本リポジトリには、5 つの視覚ドキュメントが初期データとして用意されています：

uv run python scripts/seed_visual_docs.py

各画像は Voyage のマルチモーダル埋め込みでエンコードされ、メモリコレクションに保存されます。その後、テキストクエリを用いて関連する視覚ドキュメントを検索することが可能です。

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}'

このエンドポイントは、Atlas から最も関連性の高いドキュメントを検索し、ユーザーの質問とともに Claude Vision へ送信します。これにより、静的な運用資料がエージェントが参照できるコンテキストへと変換されます。

LangGraph エージェントパスの実行

リポジトリには、LangGraph の概念実証（PoC）も含まれています。

uv run python scripts/run_poc.py

このグラフは、ガイド付き UI と同じテニスイベントのストーリーラインに従いますが、ライブのエージェントパスを通じて実行されます。具体的には以下のフローになります。

• perceive: 過去の記憶と現在の運用状態を参照する
• plan: 取得したコンテキストを Claude に渡して、Mikiko と Nina 向けの役割に応じたアクションを生成する
• Hitl_gate: V1 では提案されたアクションを自動承認しますが、本番環境ではどこで人間の承認が必要になるかを示します
• act: Atlas を更新するためのツールを実行する
• reflect: 新しい推論をセマンティックメモリへ書き戻す

Claude は取得した記憶に基づいて計画を立てるため、生成される出力は毎回異なります。ただし、初期化された記憶とプロンプトはテニスの雨による試合延期というシナリオに合わせて調整されています。

オプションの Langfuse 観測機能の追加

Langfuse は必須ではありません。.env ファイルにキーを追加すれば、検索呼び出し周りのトレーシングが出力されます。

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

実行中のサーバーが正しく設定されているか確認するには、以下を実行します。

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

Live Backend タブから検索リクエストを実行するか、/api/search または /api/hybrid-search エンドポイントを使って呼び出し、その後 Langfuse で api.search や api.hybrid_search という名前のトレースを確認してください。

Langfuse のキーが設定されている場合、ライブの LangGraph スクリプトはランレベルで langgraph.run_agent 観測値も出力します。これにより、API レイヤーとエージェントパスの両方で観測機能（オバザビリティ）が正しく動作しているか検証できます。

チュートリアルという文脈では、設定を厳格な要件にするのではなく、観測機能がどこに位置づけられるかを示すための有用な手法と言えます。

ホスト版デモを Vercel にデプロイする

リポジトリには Vercel へのデプロイパスが含まれており、アプリを公開デモリンクとして共有できます。デプロイでは api/index.py を Vercel の ASGI エントリーポイントとし、vercel.json でリクエストを FastAPI にルーティングします。また、ローカル環境の Python 3.12 ツールチェーンのために .python-version ファイルも用意されています。Vercel の Python ランタイムも 3.12 に設定し、ビルド時に pyproject.toml から依存関係をインストールするように確認してください。

ホスト版デモを構成するには、Vercel で以下の環境変数を設定します：

MONGODB_URI=
MONGODB_DATABASE=event_venue_operator
MONGODB_APP_NAME=devrel-tutorial-agentic_retrieval-memory-marktechpost
VOYAGE_API_KEY=

Langfuse のキーは必須ではありません。ホスト版でビジョン RAG や他の LLM 依存エンドポイントを意図的に公開する場合のみ、ANTHROPIC_API_KEY を追加してください。完全な LangGraph パスの検証は、未認証の公開エンドポイントを経由するのではなく、scripts/run_poc.py スクリプトを通じてローカル環境で行われます。

デプロイ後は、以下の手順で動作を確認してください：

• ルートパス（/）を開き、ガイド付き UI が正常に読み込まれることを確認します。

/api/health にアクセスして、MongoDB が正常に稼働しているか確認してください。

Live Backend タブを使用して、ベクトル検索を実行します。

同様に Live Backend タブでハイブリッド検索も試せます。

Langfuse のキーが設定されている場合は、Trace（追跡情報）が表示されるか確認しましょう。

本番環境での注意点と制約事項

このデモは意図的に範囲を限定しています。

UI は決定論的な挙動をするため、シナリオの理解には役立ちますが、リアルタイム運用管理コンソールとしての完全な機能を持つものではありません。

初期データ（シードデータ）は合成されたものです。検索パターンのデモンストレーションには十分ですが、実際の生産環境データを代表するものとして扱うべきではありません。

現在のプロジェクトでは、本番認証、レート制限、テナント分離、シークレット管理、CI/CD などは実装されていません。これらの機能は、実際に運用されるアプリケーション向けにこのパターンを適用する前に必須となります。

Vector Search ワークフローのテストには Atlas Free クラスターでも実行可能です。ただし、Free クラスターは小規模な開発やテスト用途を想定したものです。本格的なプロトタイピングや本番ワークロードでは、データ量とクエリボリュームに合わせて適切な Atlas の有料プランを選択してください。

次のステップ

このデモでは、エージェントスタックの有用な要素をデータとして保持しています。具体的には、運用記録、セマンティックメモリ（意味的記憶）、視覚ドキュメント、チェックポイント、そして追跡情報です。MongoDB Atlas はこれらすべてのデータを一元管理しつつ、ベクトル検索やマルチモーダル検索、アプリケーション状態の維持も可能にします。

このチュートリアルを楽しんでいただけた方は、ぜひ独自のシナリオを作成したり、デモをより現実味のあるものにするための機能を追加したりしてみてください。

さらに詳しく学びたい方は、GenAI Showcase の他のチュートリアルをご覧ください。また、MongoDB University ではエージェントやメモリに関する詳細も紹介しています。

GitHub リポジトリはこちらです。

※本記事の技術リソースおよびプロモーションサポートを提供いただいた MongoDB チームに感謝いたします。

この投稿は MarkTechPost に掲載された「Build an Agentic Event Venue Operator with MongoDB Atlas, Voyage, and LangGraph」の続編です。