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 の作成」を参照してください。
from strands_mongodb.types import MongoDBConfig
connection: MongoDBConfig = { "connection_string": "<connection-string>", "database": "agents",}接続文字列の検索の詳細については、「クライアントライブラリを使用したクラスターへの接続」を参照してください。
MongoDBストレージ
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クラスが提供するメソッドの一覧です。
方式 | 説明 | パラメーター | 戻り値 |
|---|---|---|---|
| 永続データをバイト列としてキーに格納し、既存の値を上書きします。 |
|
|
| キーに格納されているバイト列を返します。 |
|
|
| キーを1つ削除します。存在しないキーを削除しても、このメソッドはエラーを発生させません。 |
|
|
| 指定された接頭辞で始まるキーの名前を昇順で返します。キーのみを返し、格納されている値は返しません。 |
|
|
| デフォルトでは、このメソッドは保存されたキー名をクエリと共通する単語の数に基づいてランク付けします。代わりに保存された値を検索するには、 |
|
|
| 指定された接頭辞で始まるすべてのキーを削除します。 |
|
|
| 同じコレクション内のプレフィックスにスコープされた新しい |
|
|
|
| なし |
|
| 同じ | なし |
|
MongoDBStorageインスタンスをAgentに渡すと、エージェントのセッションサブシステムとコンテキストサブシステムがwrite() 、 read() 、 delete() 、 list() 、 search()を呼び出します。 ensure_indexes() 、 close() 、 namespace() 、 delete_prefix()は自分で呼び出します。
MongoDBMemoryStore
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クラスが提供するメソッドの一覧です。
方式 | 説明 | パラメーター | 戻り値 |
|---|---|---|---|
| このストアのスコープ内に1つのメモリを格納します。書き込みはスコープ、ストア名、および内容に基づいて重複排除されるため、同じ事実を再度追加しても2つ目のドキュメントは作成されません。 |
|
|
| クエリに最も一致するメモリを関連性の高い順に返します。クエリごとのフィルタ、制限、またはベクトルを指定するには、プレーンな文字列または |
|
|
| デプロイメントがサポートする検索機能を識別し、このストアのインデックスを作成します。このメソッドは、 | なし |
|
| 検索結果で |
|
|
| このストアが読み取れるすべてのメモリを削除します。このメソッドを使用するには、 | なし |
|
| 同じ | なし |
|
このストアを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_configTrueに設定されている場合にのみ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キーに事前に計算されたベクトルを渡します。
権限
以下の表は、データベースユーザーがさまざまな操作を行うために必要な権限を示しています。
特権 | 必要 | 必要な場合 |
|---|---|---|
両方のクラスで、すべての読書 | 常に | |
| 書き込み可能なストアまたはストレージインスタンスの場合は常に | |
照合チェックでは、すべての | 常に | |
インデックスの検証 | 常に | |
インデックスの作成 |
|
これらの権限を付与するには、ストレージおよびメモリコレクションにスコープを設定したカスタムロールを作成します。
注意
デフォルトでは、 initialize()メソッドとensure_indexes()メソッドは、パッケージが必要とするインデックスがまだ存在しない場合に、それらを作成します。本番環境のアプリケーションは、多くの場合、 createIndex 、 createCollection 、 createSearchIndexes権限を持たないユーザーとして実行されるか、インデックスの作成を別のデプロイメント手順に任せます。その場合は、 MongoDBConfigディクショナリのensure_indexesキーをFalseに設定します。これにより、パッケージはインデックスを作成する代わりに、インデックスを検証するようになります。
追加リソース
Strands AgentsをMongoDBで使用する方法の詳細については、以下のリソースを参照してください。
ストランドエージェントドキュメント
ストランド・モンゴDB GitHubリポジトリ
ストランド・モンゴDB PyPIで公開中