AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

MongoDBと Google ADK の統合

MongoDB は、 AIエージェントを構築するためのオープンソースPythonフレームワークである Google ADK と統合できます。この統合は 3 つのコンポーネントを提供します。

  • MongoDbToolset は、エージェントにMongoDB ベクトル検索とハイブリッド検索ツールを提供します

  • MongoDbSessionService は、 MongoDBでエージェントのセッション、イベント、状態を永続化します。

  • MongoDbMemoryService は、キーワードベースの長期メモリ呼び出しのためにセッション イベントをMongoDBに保存します。

はじめる

MongoDB を使用するように Google ADK を構成するチュートリアルを完了するには、「 MongoDB Google ADK 統合を使い始める 」を参照してください。

インストール

Google ADK とMongoDB の依存関係をインストールするには、次のコマンドを実行します。

pip install "google-adk[mongodb]"

このコマンドは、 PyMongoドライバーもインストールします。統合にはPyMongo v4.9 以降が必要です。

使用法

このセクションでは、 MongoDB をGoogle ADK と統合するために使用できる 3 つのコンポーネントについて説明します。

MongoDbToolset

MongoDbToolset は、 MongoDBデータベースにアクセスできる次の読み取り専用検索ツールを含むツールクラスです。

  • mongodb_vector_search: 埋め込み類似性によってドキュメントをランク付けします

  • mongodb_hybrid_search: その類似性ランキングと全文ランキングを組み合わせた

重要

必要なインデックス

上記の検索ツールを使用するには、「 インデックス ガイドライン 」セクションで説明されているインデックスを作成する必要があります。

これらのツールのいずれかを呼び出す際、エージェントモデルはプレーンテキスト クエリをツール引数として渡します。どちらのツールもこのテキストを内部的に埋め込むため、モデルはベクトルを生成したり処理したりしません。

ツールセットをMongoDBデータベースにバインドする例を表示するには、ご希望の接続方法に対応するタブを選択します。

次の例は、接続文字列を使用してツールセットを構成する方法を示しています。

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",)
agent = Agent(    model="gemini-2.5-flash",    name="product_search_agent",    instruction=(        "Search the products collection with your MongoDB tools."    ),    tools=[toolset],)

接続文字列 の検索方法の詳細については、「 クライアント ライブラリ経由でクラスターに接続する 」を参照してください。

モデルは呼び出しごとにコレクションを選択するため、エージェントの指示でターゲットコレクションに名前を付けます。これがツールセットがアクセスできるデータに与える影響については、「 コレクション選択 」セクションを参照してください。

埋め込みモデルの認証情報は、認証情報を検出するための Google Cloud の標準メカニズムであるアプリケーションのデフォルト認証情報から取得されます。 MongoDBの認証情報は、 接続文字列から取得されます。

設定を構成する

MongoDbToolSettings は、 MongoDbToolset が使用する埋め込みモデル、インデックス名、検索制限を構成する設定クラスです。このクラスのインスタンスを MongoDbToolset の settings パラメータに渡して、次の例に示すように、デフォルトを上書きします。

from google.adk.integrations.mongodb import MongoDbToolsetfrom google.adk.integrations.mongodb import MongoDbToolSettings
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",    settings=MongoDbToolSettings(default_limit=8, max_results=20),)

埋め込みモード

ベクトル検索を実行中前に、 ツールセットはクエリテキストを埋め込みます。Atlas Automated Embedding Atlas がクエリを自動的に埋め込むようにするには []タブを選択します。または、デフォルトの埋め込み動作を表示するには []タブを選択します。Google embedding models

Atlas 自動埋め込みを使用するには、MongoDbToolSettings 構成クラスで use_mongodb_auto_embedding パラメータを True に設定します。次の例に、この構成を示します。

from google.adk.integrations.mongodb import MongoDbToolsetfrom google.adk.integrations.mongodb import MongoDbToolSettings
toolset = MongoDbToolset(    connection_string="<connection_string>",    database_name="products_db",    settings=MongoDbToolSettings(        use_mongodb_auto_embedding=True,        mongodb_auto_embedding_model="voyage-4",  # optional    ),)

この構成では、ツールセットは Google 埋め込み呼び出しを実行しません。代わりに、ベクトル検索ステージはクエリテキストを受け取り、Atlas はインデックスに構成された Vyage AIモデルを使用して埋め込みを生成します。検索フィールドはautoEmbed タイプとしてインデックス付けする必要があります。

Tip

プレビュー機能

Atlas 自動埋め込み は、自己管理型配置のプレビュー機能として利用することもできます。詳細については、「 auto埋め込みタイプについて 」を参照してください。

コレクションの選択

モデルは呼び出しごとにコレクションを選択するため、データベースにバインドされたツールセットは、 検索インデックス を持つそのデータベース内のすべてのコレクションにアクセスします。 database_name パラメータをエージェントが読み取りを許可されているデータのみを含むデータベースに設定し、他のデータを 別のデータベースに保存します。

tool_filter パラメーターはツール全体を選択し、呼び出し引数を受け取らないため、モデルがアクセスできるコレクションを制限しません。コレクション許可リストを強制するには、代わりに before_tool_callback フックを使用します。これは 呼び出し引数を受け取ります。

from google.adk.agents import Agentfrom google.adk.integrations.mongodb import MongoDbToolset

def allow_products_only(tool, args, tool_context):  if tool.name.startswith("mongodb_") and args.get("collection_name") != "products":    return {        "status": "ERROR",        "error_details": "Only the products collection may be searched.",    }  return None

agent = Agent(    name="product_search_agent",    instruction="Answer questions about products.",    tools=[        MongoDbToolset(            connection_string="<connection_string>",            database_name="products_db",        )    ],    before_tool_callback=allow_products_only,)

コールバックが辞書を返す場合、ADK は検索ツールを実行しません。代わりに、その辞書がツール独自の出力であるかのようにエージェントに送信されます。 None を返すと、検索ツールは通常どおり実行できます。

MongoDbSessionService

MongoDbSessionService は、セッション、イベント、およびアプリ- 、ユーザー - 、およびセッション範囲の状態をMongoDBに保存します。これを Runnerオブジェクトに渡して、エージェントの永続的なチャット履歴を構成します（次の例に示すように）。

from google.adk.integrations.mongodb import MongoDbSessionServicefrom google.adk.runners import Runner
session_service = MongoDbSessionService(    connection_string="<connection_string>",    database_name="my_app",)
runner = Runner(    agent=agent,    app_name="my_app",    session_service=session_service,)

ドキュメントドキュメント

MongoDbSessionService は、次のコレクションにデータを保存します。

コレクション
_id 値
内容

sessions

<app_name>/<user_id>/<session_id>

JSONのセッション範囲内の状態、タイムスタンプ、および楽観的な同時実行性リダイレクト番号

events

<app_name>/<user_id>/<session_id>/<event_id>

完全に直列化されたイベント

app_states

<app_name>

アプリスコープの状態

user_states

<app_name>/<user_id>

ユーザースコープの状態

Google ADK は、状態キーの app: または user: プレフィックスを持つ、アプリ、ユーザー、または現在のセッションに状態をスコープ設定します。 MongoDbSessionService は各値を対応するコレクションに保存し、保存されたキーからプレフィックスを削除します。これにより、キー app:theme で設定された値は theme として app_statesコレクションに保存されます。

注意

各コレクションの stateフィールドには、そのキーと値がネイティブのMongoDBドキュメントとしてではなく、 JSONでエンコードされた string として保存されます。その結果、.や$など、 MongoDB がドキュメントフィールド名に禁止している文字を含む状態キーは、データの損失や破損なく保存および取得されます。

同時実行モデル

サービスの同時実行モデルは、配置タイプによって異なります。

  • レプリカセット、シャーディングされたクラスター、または Atlas クラスターでは、すべてのマルチドキュメントの書込み (write) はトランザクション内で実行されるため、コミットまたは中止はアトミックに行われます。

  • スタンドアロンのmongod、またはトランザクションをサポートしていない配置では、サービスは セッションドキュメントのオプティミスティック同時実行のリビルド チェックを使用して、順次書込みにフォールバックします。

単一プロセス内では、セッションごとのロックによって同じセッションへの同時書込みが防止されます。このロックは、アプリケーションの複数のインスタンスが同時に同じセッションに書き込まれる場合など、複数のプロセスには影響しません。

複数のプロセスにわたってセッション ドキュメントの改訂チェックにより、データの破損を防止します。 2 つの書込みが競合する場合、最初に完了する書込みの変更番号は増加し、もう 1 つの書込みはその変更チェックに失敗します。アプリケーションはこの障害をキャッチし、セッションを現在の状態にするために再ロードして、書き込みを再試行する必要があります。

MongoDbMemoryService

MongoDbMemoryService はセッション イベントをメモリコレクションに保存し、キーワード一致で検索します。次の例に示すように、セッション全体の長期メモリを構成するには、それを Runnerオブジェクトに渡します。

from google.adk.integrations.mongodb import MongoDbMemoryServicefrom google.adk.runners import Runner
memory_service = MongoDbMemoryService(    connection_string="<connection_string>",    database_name="my_app",)
runner = Runner(    agent=agent,    app_name="my_app",    memory_service=memory_service,)

Runnerオブジェクトはメモリ サービスの add_session_to_memory() メソッドを呼び出して、セッションのイベントをメモリに取り込みます。取り込まれた各イベントは、 memories_collection パラメータによって構成される メモリコレクションにメモリドキュメントとして保存されます。これらのドキュメントには、イベントのテキスト コンテンツから抽出された小文字の キーワードが含まれています。

Considerations

メモリ サービスを使用する場合は、次の動作を考慮してください。

  • メモリを検索すると、このサービスは キーワード配列がクエリの キーワードと交差するドキュメントを返します。

  • 取り込みは冪等です。セッションを再取り込むと、サービスはそのメモリを重複させるのではなく、上書きします。

  • 検索はキーワード検索を実行し、埋め込みモデル、Google 認証情報、またはベクトルインデックスを必要としません。その結果、メモリ取得はMongoDBデプロイでも機能します。

インデックス ガイドライン

このセクションでは、 MongoDBと Google ADK を統合するために必要なインデックスについて説明し、パフォーマンス向上のための推奨インデックスが含まれています。

必要な MongoDbToolset インデックス

エージェントが検索する各コレクションには次のインデックスが必要です。

  • 埋め込みを保存するフィールドのMongoDB ベクトル検索インデックス。フィールドは vector 型としてインデックス付けされます。 Atlas 自動埋め込みを使用する場合は、代わりにフィールドを autoEmbed タイプとしてインデックス。

  • 検索するテキストを保存するフィールドのMongoDB Searchインデックス（mongodb_hybrid_search ツールを使用する場合

MongoDbToolset はこれらのインデックスを名前で読み取り、作成しません。これらのインデックスの作成方法については、「 MongoDB ベクトル検索インデックスとMongoDB Search インデックスの作成 」を参照してください。

推奨サービスインデックス

ほとんどの読み取りとすべての書込みでは、 MongoDB が自動的にインデックスを作成する _idフィールドが使用されます。ただし、次の読み取りパターンでは _idフィールドは使用されないため、インデックスがない限りコレクションスキャンが必要になります。

  • セッションのイベントをアプリ、ユーザー、セッション別でタイムスタンプ順に並べ替えて読み取ります。

  • キーワード配列に一致するアプリとユーザーでメモリを検索します。

デフォルトでは 、MongoDbSessionService と MongoDbMemoryService は初めて使用するときに次の推奨インデックスを作成します。

コレクション
Index
インデックス付きフィールドとソート順序

events

app_user_session_ts

(app_name, user_id, session_id, timestamp DESC, revision DESC)

sessions

app_user

(app_name, user_id)

memories

app_user_keywords

(app_name, user_id, keywords) (multikey)

ensure_indexes パラメータを False に設定すると、サービスはこれらの推奨インデックスを作成しません。

注意

インデックス作成は偶数であるため、ensure_indexes パラメータはデフォルト値の True に設定したままにできます。このパラメータでは、 MongoDBユーザーは sessions、events、memories コレクションに対して createIndexアクションを保持する必要があります。

権限ガイドライン

管理者ユーザーを 1 人使用する代わりに、2 人の個別のデータベースユーザーを使用して、各コンポーネントに必要な範囲に特権を限定することをお勧めします。

次の表では、2 人のデータベースユーザーに推奨される最小特権構成について説明しています。

データベースユーザー
で使用
最小特権

検索ユーザー（読み取り専用）

MongoDbToolset

find エージェントが検索する各コレクションに対して

状態ユーザー（読み取り/書込み）

MongoDbSessionService, MongoDbMemoryService

*find insertupdateremovesessionseventsコレクションと コレクションでは、 、 、
find、 *insert updateapp_states、user_states 、{ では 、 、 ではmemories コレクション
*ensure_indexes TruecreateIndexsessionsをevents に設定すると、 、 、memories コレクションに アクションが追加されます

重要

前の表の特権は、Atlas の組み込みロールではなく、 MongoDB のアクションです。これらを付与するには、リスト内のコレクションにスコープを設定して、各ユーザーに対してカスタムロールを作成します。

追加リソース

MongoDBで Google ADK を使用する方法の詳細については、次のリソースを参照してください。

戻る
OpenAI エージェント SDK
次へ
はじめる
このページを評価

項目一覧