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

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

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

本デモは、MongoDB Atlas、Voyage AI の埋め込みベクトル（embeddings）、LangGraph を用いて構築しました。必要に応じて Langfuse によるトレーシングも利用可能です。

シナリオの舞台は「MongoDB Open」という架空の高級テニス大会です。プレイ開始から 6 日目、雨雲が迫っており、屋内ホスピタリティエリアの収容能力には限界があります。運営者は、2 つの異なる来場者体験を守る必要があります。1 人目は初めて参加するミキコさん。会場を最大限に活用したいと考えています。もう 1 人目はニナさんという特別ゲストです。彼女はホスピタリティへの高い期待を持っており、エージェントは彼女の過去の履歴も取得できます。

これは顧客事例の紹介でも、実際の運用環境でのデプロイ報告でもありません。あくまで、現実のイベント運営における経済構造をモデル化した架空の構築シナリオです。

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

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

さらに気象リスクも無視できません。このため米国国勢調査局は、ビジネストレンドと展望調査を通じて、極端な天候が企業売上に与える金銭的インパクトを追跡する体制を整えています。

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

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

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

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

Atlas Vector Search、ベクトルと語彙の併用検索（vector-plus-lexical retrieval）、視覚文書 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 は、エージェントループにおける記録システム（System of Record）かつ検索層の両方として機能します。つまり、「何が変わったか」を感知し、「適切な文脈」を取得し、「行動」を実行し、「何が起きたか」を次回のイベントのために永続化するという一連の流れを支えるのです。

このデモがメモリを MongoDB に保持し、サイドカーとして扱うのではなく、エージェントの操作コンテキストを構成する要素として扱っている理由もここにあります。エージェントは単に断片を検索しているだけでなく、訪れた人の履歴や現在の会場状況、ホスピタリティ在庫、過去の雨による遅延のパターン、関連する視覚ドキュメントなど、複数の情報を同時に組み合わせて判断を下す必要があるからです。

Atlas を使えば、これらの情報は別々のシステムに散らばるのではなく、クエリ可能な状態で一つの場所に保持されます。

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

このデモでは、主に 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 と構成で動作しており、ローカル環境でセットアップすれば、シードデータの作成やスモークテスト、ビジョン RAG（Retrieval-Augmented Generation）、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-...

可観測性（Observability）のために 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、オプションの 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 と同じテニスイベントのストーリーラインに従いますが、ライブのエージェントパスを通じて処理されます。

• 知覚：過去のメモリと現在の運用状態を参照する
• 計画：取得したコンテキストを Claude に呼び出し、Mikiko と Nina 向けのペルソナ固有のアクションを生成する
• ヒット・ゲート（Hitl_gate）：V1 では提案されたアクションを自動承認しますが、本番環境ではどこで人間の承認が必要になるかを示します
• 実行：Atlas を更新するツールを実行する
• 反省：新しい推論をセマンティックメモリへ書き戻す

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 へのデプロイパスが含まれており、アプリを公開リンクとして共有できます。デプロイでは、Vercel の ASGI エントリーポイントとして api/index.py を使用し、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 が Langfuse 上に表示されるか確認してください。

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

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

UI は決定的な挙動をするように設計されています。シナリオの理解を深めるには役立ちますが、リアルタイムの運用管理コンソールとして完全な機能を備えているわけではありません。

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

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

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

次のステップ

このデモでは、エージェントスタックの有用な要素を MongoDB 内に統合しています。具体的には、運用記録、意味的な記憶（セマンティック・メモリ）、視覚ドキュメント、チェックポイント、Trace です。MongoDB Atlas を使えば、ベクトル検索やマルチモーダル検索、アプリケーションの状態管理を一つの場所でサポートしながら、これらのデータを一貫して保持できます。

このチュートリアルが役に立った場合は、ぜひご自身で独自のシナリオを作成したり、デモのリアリティを高める機能を実装してみてください。

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

GitHub リポジトリはこちらから確認できます。

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

（この記事は元々 MarkTechPost に掲載された「Build an Agentic Event Venue Operator with MongoDB Atlas, Voyage, and LangGraph」の一部です。）