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

MongoDBとStrandsエージェントを統合する

MongoDBを Strands Agents と統合できます 、AIエージェント構築のためのオープンソースPython SDK。strands -mongodb このパッケージを使用すると、以下のクラスのバックエンドとしてMongoDBデプロイメントを使用できます。

  • MongoDBStorageは、エージェントセッション、コンテキスト管理、およびトランスクリプトをMongoDBに永続化します。

  • MongoDBMemoryStoreは、意味、キーワード、またはその両方の組み合わせによって事実を保存および呼び出します。

Strands AgentsでMongoDBを使用するように設定するためのチュートリアルを完了するには、 「MongoDB Strands Agents統合の開始」を参照してください。

strands-mongodbパッケージとMongoDBStorageおよびMongoDBMemoryStoreクラスの依存関係をインストールするには、次のコマンドを実行します。

pip install 'strands-mongodb[all]'

このコマンドは、次の依存関係をインストールします。

  • strands-mongodbStrandsエージェント向けのMongoDB統合パッケージ。

  • strands-agentsStrands Agents SDK。このパッケージにはv 1.54以降が必要です。

  • pymongoMongoDB 用の公式 Python ドライバです。このパッケージはバージョン4.14以降が必要です。

  • pymongo-search-utilsMongoDBのベクトル検索機能を利用するためのユーティリティです。このパッケージはバージョン0.3以降が必要です。

  • opentelemetry-apiPython 用の OpenTelemetry API。このパッケージはバージョン1.30以降が必要です。

  • typing-extensionsPython の型付け機能をバックポートしました。このパッケージはバージョン4.13.2以降が必要です。

または、以下のいずれかのコマンドを実行して、個々のクラスの依存関係をインストールしてください。

pip install 'strands-mongodb[storage]' # MongoDBStoragepip install 'strands-mongodb[memory]' # MongoDBMemoryStore

MongoDB接続を設定するには、 MongoDBConfig辞書をMongoDBStorageまたはMongoDBMemoryStoreクラスに渡します。プロセスごとに1つのMongoDBConfig辞書を作成し、使用するすべてのクラスに渡すことで、1つの接続プールを共有できます。

接続を設定するには、既存のクライアントを指定するか、接続文字列を指定できます。対応する例を表示するには、 Existing clientまたはConnection stringタブを選択してください。

from pymongo import AsyncMongoClientfrom strands_mongodb.types import MongoDBConfig client = AsyncMongoClient("<connection-string>")connection: MongoDBConfig = { "client": client, "database": "agents",}

注意

パッケージはクライアントの所有権を取得しません。クライアントを閉じるのはあなたの責任です。

AsyncMongoClientの詳細については、 「MongoClient の作成」を参照してください。

MongoDBStorageクラスを使用すると、エージェントの永続データを MongoDB に保存できます。設定が完了すると、SDK はエージェントのセッション、コンテキスト管理データ、およびトランスクリプトを、ローカルファイルやメモリではなく、MongoDB コレクションのドキュメントとして保存します。永続データは文字列キーで保存され、各キーがドキュメントの_id値になります。そのため、読み取りおよび書き込み操作では主キーによるルックアップが実行されます。

このセクションでは、 MongoDBStorageクラスが提供するメソッドの設定方法と使用方法について説明します。

このクラスを設定するには、 MongoDBConfig辞書とコレクション名をMongoDBStorageコンストラクタに渡します。次の例では、永続データをMongoDBに書き込み、このデータを取得し、指定されたプレフィックスで始まるキーを一覧表示し、データを削除します。

import asyncio from strands_mongodb import MongoDBStorage async def main() -> None: storage = MongoDBStorage(connection, collection="storage") try: await storage.write("notes/colony", b"emperor penguins live in Antarctica") print(await storage.read("notes/colony")) print(await storage.list("notes/")) await storage.delete("notes/colony") finally: await storage.close() asyncio.run(main())

エージェントがこのクラスを使用するように構成する方法については、 「エージェントの構成」を参照してください。

以下の表は、 MongoDBStorageクラスが提供するメソッドの一覧です。

方式
説明
パラメーター
戻り値

write()

永続データをバイト列としてキーに格納し、既存の値を上書きします。 ttl_secondsを設定した場合、このメソッドは書き込むドキュメントにexpires_atフィールドも追加します。

key: データを保存するキー。
data : 保存するバイト数。

None

read()

キーに格納されているバイト列を返します。

key読むための鍵。

bytes、またはキーが存在しない場合はNone

delete()

キーを1つ削除します。存在しないキーを削除しても、このメソッドはエラーを発生させません。

key: 削除するための鍵。

None

list()

指定された接頭辞で始まるキーの名前を昇順で返します。キーのみを返し、格納されている値は返しません。

query: 一致させるキーの接頭辞。

list[str]

search()

デフォルトでは、このメソッドは保存されたキー名をクエリと共通する単語の数に基づいてランク付けします。代わりに保存された値を検索するには、 MongoDBStorageのsearch_strategyパラメータを、SDK のベクトル検索用のKeywordSearchStrategyまたはMongoDBVectorSearchStrategyなど、値を読み取る戦略に設定します。

query検索対象のテキスト。

list[StorageSearchResult]

delete_prefix()

指定された接頭辞で始まるすべてのキーを削除します。

prefix: 削除するキーの接頭辞。

intこれは削除された文書の数を示します

namespace()

同じコレクション内のプレフィックスにスコープされた新しいMongoDBStorageを返します。元の接続プール、コレクション、TTL、および検索戦略を共有します。このメソッドは同期的に動作します。

prefix: 新しいインスタンスのスコープを指定するプレフィックス。

MongoDBStorage

ensure_indexes()

ttl_secondsが必要とするTTLインデックスを作成または検証します。このメソッドは起動時に一度だけ呼び出してください。

なし

None

close()

同じMongoDBConfigディクショナリを共有するすべてのインスタンスの接続プールを解放します。このメソッドは、プロセス終了時に一度だけ呼び出してください。

なし

None

MongoDBStorageインスタンスをAgentに渡すと、エージェントのセッションサブシステムとコンテキストサブシステムがwrite() 、 read() 、 delete() 、 list() 、 search()を呼び出します。 ensure_indexes() 、 close() 、 namespace() 、 delete_prefix()は自分で呼び出します。

MongoDBMemoryStoreクラスを使用すると、エージェントの長期記憶を MongoDB に保存できます。設定が完了すると、エージェントは事実を MongoDB コレクションに保存し、意味、キーワード、またはその両方に基づいて事実を取得します。ストアは、意味検索には MongoDB Vector Search を、キーワード検索には MongoDB Search を使用します。

MongoDB ベクター検索を使用するには、MongoDB はデータのベクトル埋め込みとクエリの埋め込みを比較します。デフォルトでは、MongoDB がこれらの埋め込みを自動的に生成するため、ベクトルや埋め込みプロバイダーの API キーを管理する必要はありません。

このセクションでは、 MongoDBMemoryStoreクラスが提供するメソッドの設定方法と使用方法について説明します。

このクラスを設定するには、名前とMongoDBConfig辞書をMongoDBMemoryStoreコンストラクタに渡します。

この例では、メモリ ストアを作成し、メモリを追加してから、意味に基づいてメモリを検索します。また、 MongoDBMemoryStoreをインスタンス化する際に、以下のオプション パラメータも設定します。

  • scope: メモリ ストアのアクセスを、指定されたscopeフィールド値を格納するドキュメントに制限します。この例ではスコープ"user-abc"を使用しています。

  • writableメモリストアへの書き込み操作を有効にします。

import asyncio from strands_mongodb import MongoDBMemoryStore async def main() -> None: store = MongoDBMemoryStore( name="preferences", config=connection, scope="user-abc", writable=True ) try: await store.add("Studies emperor penguins in Antarctica.") results = await store.search("Which animals does this researcher observe?") for entry in results: print(f"search type: {entry.metadata['_search_type']}") print(f"score: {entry.metadata['_relevance_score']}") print(f"content: {entry.content}") finally: await store.close() asyncio.run(main())

MongoDBMemoryStore クエリに回答するために、以下の検索タイプを使用します。

  • 意味に基づいて一致するベクトル検索。

  • キーワードによるテキスト検索。

  • ハイブリッド検索とは、両方の検索タイプを組み合わせたものです。

MongoDBConfig辞書内のsearch_typeキーは、ストアが使用する検索タイプを制御します。デフォルト値の"auto" 、デプロイメントがサポートするすべての検索タイプを準備し、利用可能な最も高い検索タイプを優先します。

このデプロイメントでは両方のインデックスが準備されるため、 search_typeの値が"auto"の場合はハイブリッド検索が使用されます。ハイブリッド検索はベクトル検索とは異なる方法で結果をランク付けするため、両者のスコアを直接比較することはできません。ベクトル検索用に設定したmin_scoreまたはmax_score値は、保持したい結果を除外する可能性があります。

エージェントがこのクラスを使用するように構成する方法については、 「エージェントの構成」を参照してください。

以下の表は、 MongoDBMemoryStoreクラスが提供するメソッドの一覧です。

方式
説明
パラメーター
戻り値

add()

このストアのスコープ内に1つのメモリを格納します。書き込みはスコープ、ストア名、および内容に基づいて重複排除されるため、同じ事実を再度追加しても2つ目のドキュメントは作成されません。

content: メモリのテキスト。
metadata : メモリとともに保存するオプションのキーと値のペア。

MongoDBAddResultこれにはids 、 inserted 、 duplicatesが含まれます。

search()

クエリに最も一致するメモリを関連性の高い順に返します。クエリごとのフィルタ、制限、またはベクトルを指定するには、プレーンな文字列またはMongoDBSearchQuery辞書を受け入れます。

query: 検索するテキスト、またはMongoDBSearchQuery辞書。
options : オプションの SDK 検索オプション、例: max_search_results 。

list[MemoryEntry]各エントリのメタデータには、 _relevance_score 、 _search_type 、 _scope 、 _idが含まれます。

initialize()

デプロイメントがサポートする検索機能を識別し、このストアのインデックスを作成します。このメソッドは、 MemoryManagerおよびメモリの読み書きを行うすべてのメソッドによって自動的に呼び出されます。

なし

None

delete()

検索結果で_idと表示されるメモリを1つ削除します。このメソッドを使用するには、 writable Trueに設定する必要があります。

memory_id検索結果の_id値。

int(文書が削除された場合は1 、一致する文書がない場合は0となる)

delete_all()

このストアが読み取れるすべてのメモリを削除します。このメソッドを使用するには、 writable Trueに設定する必要があります。

なし

intは、削除されたドキュメントの数を示します

close()

同じMongoDBConfigディクショナリを共有するすべてのインスタンスの接続プールを解放します。

なし

None

このストアをMemoryManagerに登録すると、エージェントはinitialize() 、 search()呼び出し、有効化するとadd()を呼び出します。SDKのMemoryStoreインターフェースには削除や接続のメソッドがないため、 delete() 、 delete_all() 、 close()は自分で呼び出す必要があります。

エージェントは、セッションと長期記憶を同じ MongoDB 環境に保存するように構成できます。この構成により、エージェントは実行時にデータを自動的に保存および取得できます。

エージェントを設定するには、 MongoDBConfig辞書をMongoDBStorageとMongoDBMemoryStoreコンストラクタの両方に渡し、結果として得られたインスタンスをAgentコンストラクタに渡します。

次の例では、セッションとメモリの両方にMongoDBを使用するエージェントを作成します。

from strands import Agentfrom strands.memory import MemoryManagerfrom strands.session import SnapshotSessionManagerfrom strands_mongodb import MongoDBStorage, MongoDBMemoryStore store = MongoDBMemoryStore( name="preferences", config=connection, scope="user-abc", writable=True,) agent = Agent( model=your_model, storage=MongoDBStorage(connection), session_manager=SnapshotSessionManager(session_id="support-ticket-4127"), memory_manager=MemoryManager(stores=[store], add_tool_config=True),)

次の考慮事項が適用されます。

  • エージェントがメモリを保存できるようにするには、 writableキーをTrueに設定します。

  • MemoryManagerクラスは常にモデルにsearch_memoryツールを提供しますが、 add_tool_config Trueに設定されている場合にのみadd_memoryツールを提供します。モデルにメモリを保存するタイミングを決定させたい場合は、 add_tool_configパラメータを有効にしてください。

  • add_tool_configパラメータは、渡されたストアが書き込み可能でない場合、 ValueError例外を発生させます。

  • storageパラメータだけではセッションは保存されません。 session_idで指定した値でセッションを保存するには、 session_managerを設定する必要があります。

MongoDBMemoryStore ensure_indexesキーをFalseに設定しない限り、初回使用時に 2 つの検索インデックスが作成されます。

MongoDB ベクター検索インデックスは、 MongoDBConfigディクショナリのvector_index_nameキーによって命名され、以下の定義を持ちます。

{ "fields": [ { "type": "autoEmbed", "path": "content", "model": "voyage-4-lite", "modality": "text" }, { "type": "filter", "path": "scope" }, { "type": "filter", "path": "store_name" } ]}

注意

デフォルトでは、この MongoDB ベクトル検索インデックスはautoEmbedタイプを使用します。これは、MongoDB に埋め込みを自動的に生成するように指示するものです。

MongoDB検索インデックスは、 MongoDBConfig辞書のtext_index_nameキーによって命名され、以下の定義を持ちます。

{ "mappings": { "dynamic": false, "fields": { "content": [{ "type": "string" }] } }}

これらのインデックスを手動で作成する方法の詳細については、 「MongoDB ベクトル検索インデックスの作成」および「MongoDB 検索インデックスの作成」を参照してください。

独自のベクトル埋め込みを指定するには、 MongoDBConfig辞書のembedding_dimensionsとsimilarityキーを設定してください。 embedding_modelキーは設定しないでください。この設定により、MongoDBはcontentフィールドを型としてインデックスするのではなく、 embeddingフィールドautoEmbed vector型としてインデックスします。

次に、以下のいずれかの方法でベクトルを指定してください。

  • embedderオブジェクトをMongoDBMemoryStoreコンストラクタに渡すと、ストアにメモリと文字列クエリを埋め込むように指示します。

  • search()メソッドを呼び出すときは、 MongoDBSearchQueryディクショナリのvectorキーに事前に計算されたベクトルを渡します。

以下の表は、データベースユーザーがさまざまな操作を行うために必要な権限を示しています。

特権
必要
必要な場合

両方のクラスで、すべての読書

常に

write()、 add() 、 delete() 、および同様の方法

書き込み可能なストアまたはストレージインスタンスの場合は常に

照合チェックでは、すべてのinitialize()呼び出しがインデックスの前に実行されることを確認します。

常に

インデックスの検証

常に

インデックスの作成

ensure_indexesがTrueに設定されている場合のみ、そのデフォルト値は

これらの権限を付与するには、ストレージおよびメモリコレクションにスコープを設定したカスタムロールを作成します。

注意

デフォルトでは、 initialize()メソッドとensure_indexes()メソッドは、パッケージが必要とするインデックスがまだ存在しない場合に、それらを作成します。本番環境のアプリケーションは、多くの場合、 createIndex 、 createCollection 、 createSearchIndexes権限を持たないユーザーとして実行されるか、インデックスの作成を別のデプロイメント手順に任せます。その場合は、 MongoDBConfigディクショナリのensure_indexesキーをFalseに設定します。これにより、パッケージはインデックスを作成する代わりに、インデックスを検証するようになります。

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