MongoDBをAgno フレームワークと統合する

MongoDBは、マルチモーダルAIエージェントを構築するためのオープンソースのPythonフレームワークであるAgnoと統合できます。Agnoは、2つのMongoDB統合を提供します。

エージェントの知識ベースを保存し、MongoDBベクトル検索で検索するベクトルデータベース。
エージェントのセッション、ユーザーのメモリ、メトリクス、評価の実行をMongoDBのコレクションに永続化するセッションおよびメモリデータベース。

いずれかの統合を単独で使用することも、両方を同じエージェントで使用することもできます。

はじめる

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

インストール

Agno には Python v3.9 以降が必要です。最新の Agno と PyMongo バージョンをインストールするには、次のコマンドを実行します。

pip install agno pymongo

このページの例では、Agno がデフォルトで使用する OpenAI モデルを使用します。OpenAI クライアントライブラリをインストールするには、次のコマンドを実行します。

pip install openai

このページのCustom configurationの例では、Voyage AIの埋め込みを使用しています。Voyage AIクライアントライブラリをインストールするには、次のコマンドを実行します。

pip install voyageai

環境変数

このページの例を実行する前に、以下の環境変数を設定してください。

接続文字列: MONGODB_URI を MongoDB 配置の接続文字列に設定します。
モデルAPIキー: OPENAI_API_KEY または VOYAGE_API_KEY を、モデルプロバイダーのAPIキーに設定します。

ベクトルデータベース

MongoVectorDb クラスは、MongoDB ベクトル検索を使用して Agno ベクトルデータベースインターフェースを実装します。エージェントにドキュメントに対するセマンティック検索機能を提供するには、このクラスのインスタンスを Agno Knowledge オブジェクトの vector_db パラメータに渡し、そのオブジェクトをエージェントの knowledge パラメータに渡します。

重要

MongoDBクラス名

Agnoは両方のMongoDBクラスをMongoDbと命名していますが、それぞれ異なるモジュールからインポートしています。agno.vectordb.mongodbからベクトルデータベースクラスを、agno.db.mongoからデータベースクラスをインポートします。名前の衝突を避けるため、AgnoはベクトルデータベースクラスをMongoVectorDbとしてもエクスポートしています。このページの例では、そのエイリアスを使用しています。

Basic initialization タブを選択すると、最小構成の例が表示されます。または、Custom configuration タブを選択すると、カスタム設定で統合を構成する方法が表示されます。

ベクトルデータベースを初期化するには、埋め込みを保存するコレクションとMongoDB接続文字列を指定します。次の例では、知識ベースを作成し、ドキュメントを追加し、エージェントにデータへのアクセス権を付与します。

import os
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.mongodb import MongoVectorDb
vector_db = MongoVectorDb(
    collection_name="agent_knowledge",
    db_url=os.environ["MONGODB_URI"],
    database="agno",
)
knowledge = Knowledge(vector_db=vector_db)
knowledge.insert(
    name="Recipes",
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
)
agent = Agent(knowledge=knowledge, search_knowledge=True)

次の例では、ハイブリッド検索を有効にし、OpenAIのデフォルトの代わりにVoyage AIを使用して埋め込みを生成し、MongoDB ベクトル検索インデックス名を指定します。

import os
from agno.agent import Agent
from agno.knowledge.embedder.voyageai import VoyageAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.mongodb import MongoVectorDb
from agno.vectordb.search import SearchType
embedder = VoyageAIEmbedder(
    id="voyage-4-large",
    dimensions=1024,
    api_key=os.environ["VOYAGE_API_KEY"],
    request_params={"output_dimension": 1024},
)
vector_db = MongoVectorDb(
    collection_name="agent_knowledge",
    db_url=os.environ["MONGODB_URI"],
    database="agno",
    embedder=embedder,
    search_type=SearchType.hybrid,
    hybrid_vector_weight=0.7,
    hybrid_keyword_weight=0.3,
    search_index_name="agno_vector_index",
)
knowledge = Knowledge(vector_db=vector_db)
agent = Agent(knowledge=knowledge, search_knowledge=True)

埋め込みモデルを指定した場合、AgnoはMongoDB ベクトル検索インデックスを作成する際に、その埋め込みモデルが生成する次元数を使用します。request_params辞書は、プロバイダー固有のキーワード引数を埋め込み呼び出しに渡します。Voyage AIの場合、output_dimensionは可変次元をサポートするモデルに対して返されるベクトルのサイズを制御します。

Knowledge オブジェクトを作成すると、Agno はコレクションが既に存在するかどうかを検証します。そうでない場合、Agno がコレクションと MongoDB ベクトル検索インデックスを作成します。コレクションが存在する場合、個別に削除した場合でも Agno はインデックスが存在するかどうかを確認しません。

インデックスを作成した後、Agno はインデックスがコレクションに表示されるまで待機します。ただし、インデックスのステータスを確認しません。そのため、インデックスの構築が完了するまでは、その直後に実行されるクエリは結果を返さない可能性があります。

MongoVectorDb クラスは、次のパラメーターを受け入れます。

Parameter	必要性	説明
`collection_name`	必須	ドキュメントとその埋め込みを保存するコレクションの名前。
`db_url`	任意	MongoDB 配置の接続文字列。デフォルトは `mongodb://localhost:27017/` です。接続文字列の検索についてさらに学ぶには、クライアントライブラリ経由でクラスターに接続するを参照してください。
`client`	任意	既存の`MongoClient`インスタンス。このパラメータを指定すると、Agnoは`db_url`を無視します。
`database`	任意	コレクションを保持するデータベースの名前。デフォルトは `agno` です。
`embedder`	任意	Agnoがドキュメントとクエリを埋め込むために使用する埋め込みモデル。デフォルトは `OpenAIEmbedder()` です。
`distance_metric`	任意	MongoDB ベクトル検索インデックスが使用する類似度関数。現在サポートされているのは、デフォルト値の`Distance.cosine`のみです。
`search_type`	任意	取得戦略。`SearchType.vector` または `SearchType.hybrid` を受け入れます。デフォルトは `SearchType.vector` です。
`hybrid_vector_weight`	任意	ハイブリッド検索がセマンティック検索結果に適用する重み。デフォルトは `0.5` です。
`hybrid_keyword_weight`	任意	ハイブリッド検索がキーワード検索結果に適用する重み。デフォルトは `0.5` です。
`hybrid_rank_constant`	任意	Reciprocal Rank Fusionスコアを計算する前に、ハイブリッド検索が各ランクに加算する定数。デフォルトは `60` です。
`search_index_name`	任意	コレクション上の MongoDB ベクトル検索インデックスの名前。デフォルトは `vector_index_1` です。
`wait_until_index_ready_in_seconds`	任意	AgnoがMongoDB Vector Searchインデックスを作成した後、インデックス名がコレクションの検索インデックスに表示されるまで待機するかどうか。待機するにはこのパラメーターを正の数に設定し、待機をスキップするには `None` に設定します。非同期メソッドでは、この値を秒単位のタイムアウトとして使用します。デフォルトは `3` です。
`wait_after_insert_in_seconds`	任意	Agnoがドキュメントを挿入した後に待機する時間（秒単位）。デフォルトは `3` です。
`max_pool_size`	任意	ドライバーの接続プール内の最大接続数。デフォルトは `100` です。
`retry_writes`	任意	ドライバーがサポートされている書き込み (write)操作を再試行するかどうか。デフォルトは `True` です。
`cosmos_compatibility`	任意	Agno が MongoDB ベクトル検索形式ではなく、Azure Cosmos DB for MongoDB vCore 形式でインデックスを作成するかどうか。デフォルトは `False` です。
`name`, `description`, `id`	任意	ベクトルデータベースインスタンスの識別用メタデータ。`id` を指定しない場合、Agno は、接続文字列、データベース名、およびコレクション名からそれを導出します。

ベクトルデータベースのメソッド

Knowledgeクラスは、知識ベースにコンテンツを追加するとき、またはエージェントが知識ベースを検索するときに、次のメソッドを呼び出します。これらのメソッドを直接呼び出すのは、Knowledgeオブジェクトの外部でドキュメントをマネージドしている場合のみにしてください。

書き込み (write)または検索操作をユーザー1人のドキュメントに制限するには、user_id 値を操作メソッドに渡します。

方式	説明
`search(query, limit, filters, min_score, user_id)`	`query`を埋め込み、最大`limit`件の一致するドキュメントを返します。`search_type`を`SearchType.hybrid`に設定すると、Agnoはキーワード検索も実行し、2つの結果セットをマージします。`filters` パラメーターは、メタデータフィルターの辞書を受け入れます。代わりにAgnoフィルター式のリストを渡すと、MongoDB統合がそれらをサポートしていないため、Agnoは警告をログに記録し、フィルターを適用しません。
`insert(content_hash, documents, filters, user_id)`	`documents` 内の各ドキュメントを埋め込み、そのドキュメントをコレクションに挿入します。Agno は、各ドキュメントの `_id` 値をドキュメントコンテンツのハッシュから導出します。
`upsert(content_hash, documents, filters, user_id)`	`content_hash`を共有するドキュメントを置き換え、`documents`のドキュメントを挿入します。コンテンツが変更されたドキュメントを更新するには、このメソッドを使用します。
`delete()`	コレクションからすべてのドキュメントを削除しますが、コレクションとそのMongoDB ベクトル検索インデックスは保持されます。
`delete_by_id(id)`	指定された `_id` 値を持つドキュメントを削除します。
`delete_by_name(name)`	指定された `name` 値を持つドキュメントを削除します。
`delete_by_metadata(metadata)`	`meta_data`フィールドが指定されたキーと値のペアと一致するドキュメントを削除します。
`drop()`	コレクションとMongoDB ベクトル検索インデックスを削除します。
`exists()`	コレクションが存在する場合は、`True` を返します。
`get_count()`	コレクション内のドキュメント数を返します。

Tip

非同期メソッド

前の表で説明した各メソッドには、対応する非同期メソッドがあります。

search(): 使用する async_search()
insert(): 使用する async_insert()
upsert(): 使用する async_upsert()
drop(): 使用する async_drop()
exists(): 使用する async_exists()

セッションおよびメモリデータベース

agno.db.mongo モジュールの MongoDb クラスは、Agno データベースインターフェースを実装しています。エージェントのセッション、ユーザーメモリ、メトリクス、評価実行を MongoDB に永続化するには、このクラスのインスタンスを Agent、Team、または Workflow オブジェクトの db パラメータに渡します。

データベースを初期化するには、お使いの MongoDB 接続文字列を指定します。次の例では、セッション履歴をMongoDBに保存し、その履歴をモデルコンテキストに含めるエージェントを作成します。

import os
from agno.agent import Agent
from agno.db.mongo import MongoDb
db = MongoDb(db_url=os.environ["MONGODB_URI"])
agent = Agent(db=db, add_history_to_context=True)

次の例では、データベース名と、セッション、メモリ、メトリクスを保存するコレクションの名前を指定します。

import os
from agno.agent import Agent
from agno.db.mongo import MongoDb
db = MongoDb(
    db_url=os.environ["MONGODB_URI"],
    db_name="agno_prod",
    session_collection="agent_sessions",
    memory_collection="agent_memories",
    metrics_collection="agent_metrics",
)
agent = Agent(db=db, add_history_to_context=True)

Agnoは、設定したコレクションへの最初の書き込み (write)時に、各コレクションを作成します。

MongoDb クラスは、次のパラメーターを受け入れます。

Parameter	必要性	説明
`db_url`	条件付き	MongoDB 配置の接続文字列。`db_client` を指定しない場合に必要です。
`db_client`	条件付き	既存の`MongoClient`インスタンス。`db_url` を指定しない場合は必須です。両方を指定した場合、Agno は `db_url` を無視します。
`db_name`	任意	コレクションを保持するデータベースの名前。デフォルトは `agno` です。
`session_collection`	任意	エージェント、チーム、およびワークフローのセッションを保存するコレクションの名前。デフォルトは `agno_sessions` です。
`runs_collection`	任意	実行するものを保存するコレクションの名前。実行するごとに1つのドキュメントが作成されます。デフォルトは `agno_runs` です。`session_collection` を指定してもこのパラメータを指定しない場合、Agno はセッションコレクション名から `agent_sessions_runs` のような名前を作成します。
`memory_collection`	任意	ユーザーの記憶を保存するコレクションの名前。デフォルトは `agno_memories` です。
`metrics_collection`	任意	集計された使用状況メトリクスを保存するコレクションの名前。デフォルトは `agno_metrics` です。
`eval_collection`	任意	評価の実行を保存するコレクションの名前。デフォルトは `agno_eval_runs` です。
`knowledge_collection`	任意	ナレッジコンテンツのメタデータを保存するコレクションの名前。デフォルトは `agno_knowledge` です。
`traces_collection`, `spans_collection`	任意	トレースとスパンを保存するコレクションの名前。デフォルトでは、 `agno_traces` と `agno_spans` になります。
`schedules_collection`, `schedule_runs_collection`	任意	予定と予定の実行を保存するコレクションの名前。デフォルトは `agno_schedules` と `agno_schedule_runs` です。
`learnings_collection`	任意	学習内容を保存するコレクションの名前。デフォルトは `agno_learnings` です。
`id`	任意	データベースインスタンスの識別子。このパラメータを指定しない場合、Agnoは接続文字列とデータベース名からそれを導出します。

エージェントが実行する際、Agnoは本セクションで説明するセッション、メモリ、メトリクスのコレクションを自動的に読み取り、書き込み (write)を行います。Agnoは、各コレクションが必要になったときに作成します。以下のように、MongoDbインスタンスでメソッドを直接呼び出すこともできます。

upsert_session() および get_sessions() の読み取り/書き込み (write)セッション。
upsert_user_memory() 単一のユーザーメモリに書き込み (write)ます。
get_metrics() 集計された使用メトリクスを読み取ります。
upsert_sessions() また、既存のセッション履歴をupsert_memories() MongoDB に移行する場合など、1 回の操作で多くのレコードを書き込み (write) ます。
close() クライアント接続を解放します。アプリケーションがシャットダウンするときに、このメソッドを呼び出します。

検索インデックス

Agno が初めてベクトルコレクションを作成するとき、コレクション上に MongoDB ベクトル検索インデックスも作成します。インデックス名は search_index_name パラメータの値であり、デフォルトは vector_index_1 です。このインデックスを手動で作成または検査することもできます。詳しく学ぶには、「MongoDB ベクトル検索インデックスの作成」を参照してください。

このインデックスは以下の定義を使用します。ここで、numDimensions はエンベッダーが生成する次元数と一致し、similarity は distance_metric の値と一致します。

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1536,
      "similarity": "cosine"
    },
    {
      "type": "filter",
      "path": "user_id"
    }
  ]
}

Agnoは、単一のエンドユーザーのドキュメントに検索範囲を絞り込めるように、user_idフィールドをフィルターフィールドとしてインデックス化します。

ハイブリッド検索には、MongoDB Searchインデックスは必要ありません。Agnoは、キーワード検索をcontentフィールドに対する正規式クエリとして実行し、その結果をMongoDB ベクトル検索の結果と相互ランク融合（Reciprocal Rank Fusion）を使用して結合します。