agent-framework-mongodb

MongoDB vector stores

An alpha MongoDB integration for Microsoft Agent Framework. MongoDBCollection provides async BSON CRUD and dense-vector search, MongoDBStore shares an official async PyMongo client across collections, and MongoDBSettings defines connection configuration.

Installation

pip install agent-framework-mongodb --pre

Requires Python 3.10+, PyMongo 4.13.2+, and a MongoDB deployment with MongoDB Vector Search. Search-index creation requires the corresponding database permissions.

Connection

Set MONGODB_URI and MONGODB_DATABASE_NAME; MONGODB_APP_NAME is optional. Constructors resolve explicit arguments first, then an explicitly selected .env file, then process environment variables. URIs accept str or AF SecretString and are unwrapped only for PyMongo.

You can instead inject an AsyncMongoClient and pass database_name. An injected client bypasses URI, app-name, and .env loading and always remains caller-owned. Connector-created clients are closed by close() or async context exit. Collections created by a store borrow its already-resolved client.

Example

import asyncio
from dataclasses import dataclass
from typing import Annotated

from agent_framework import Filter, VectorStoreField, vectorstoremodel
from agent_framework_mongodb import MongoDBStore


@vectorstoremodel(collection_name="articles")
@dataclass
class Article:
    id: Annotated[str, VectorStoreField("key")]
    topic: Annotated[str, VectorStoreField("data", is_indexed=True)]
    text: Annotated[str, VectorStoreField("data")]
    embedding: Annotated[list[float] | None, VectorStoreField("vector", dimensions=3)] = None


async def main() -> None:
    async with MongoDBStore() as store:
        collection = store.get_collection(Article)
        await collection.ensure_collection_exists()
        await collection.upsert(
            [Article("1", "database", "MongoDB stores BSON documents", [1, 0, 0])],
            generate_vectors=False,
        )
        results = await collection.search(
            vector=[1, 0, 0],
            filter=Filter("topic", "eq", "database"),
        )
        async for result in results:
            print(result["record"].text, result["score"])


asyncio.run(main())

Retrieval-augmented generation

VectorCollectionContextProvider exposes a vector collection to an agent as tools, so grounding an agent on MongoDB needs nothing beyond Agent Framework. Turning off the write tools keeps retrieval read-only.

from agent_framework import Agent, VectorCollectionContextProvider

knowledge_base = VectorCollectionContextProvider(
    collection,
    scope_filter=None,
    include_upsert_tool=False,
    include_get_tool=False,
    include_delete_tool=False,
)

async with Agent(client=chat_client, context_providers=[knowledge_base]) as agent:
    print((await agent.run("How long does a refund take?")).text)

As with any MongoDB record type, the model must not declare is_full_text_indexed; mark metadata you want to filter on with is_indexed instead. Newly written records become searchable asynchronously, so an ingestion path should confirm they are retrievable before querying them. See samples/mongodb_agent_rag.py for a runnable example that does both.

Capabilities and limits

• String, signed 64-bit integer, and BSON ObjectId _id values retain native identity. Only ObjectId keys can be generated. Typed ObjectId models must register an encoder and decoder that preserve ObjectId; IDs are never stringified or copied to hidden fields in storage. Agent-facing CRUD tool JSON represents ObjectId keys as validated 24-character hexadecimal strings and converts them back to native values at the collection boundary.
• Multiple top-level dense-vector fields are supported through one vector-search index per field. Use provider_annotations={"mongodb.index_name": "..."} to select an existing index name. Dimensions must be 1-8192. Metrics are cosine, dot product, and Euclidean; returned vectorSearchScore values are native normalized relevance scores where larger is better.
• ensure_collection_exists() creates missing indexes, waits for readiness, and validates existing semantic definitions. It never updates or migrates an incompatible collection or index. Newly written documents become searchable asynchronously, even after an index is queryable.
• Retrieval filters preserve whole-value equality, missing/null, direct array membership, boolean/number, and literal text semantics with server-side expressions. Collection filters require fields declared as list and reject mapping and non-list collection operands whose identity BSON cannot preserve. Vector prefilters are intentionally narrower: indexed scalar equality, range, membership, AND, and OR only. Nested paths, NOT, null/missing, list membership, and literal/analyzed text are rejected for vector search.
• Keyword-hybrid search, sparse/binary vectors, provider-side embedding generation, and automatic schema migration are not supported. A model that declares is_full_text_indexed is rejected when the collection is constructed, because there is no Search text index to back it.
• ANN defaults numCandidates to the MongoDB recommendation of 20 times skip + top, capped at MongoDB's maximum of 10,000. Explicit values must be 1-10,000 and at least skip + top; larger result windows require exact search. The vector stage selects its result window before score thresholding, skip, and limit, so selective thresholds can underfill a page. Deep offsets increase server cost; result prefixes are never materialized by the connector.
• Every record is fully validated against BSON's signed 64-bit integer and 16 MiB document limits before any batch write. PyMongo then chunks bulk writes using negotiated server limits. A server error can leave a successful prefix (ordered=True) or subset (ordered=False) persisted.

Documentation

• Microsoft Agent Framework documentation
• MongoDB Vector Search documentation
• PyMongo async documentation
• MongoDB limits and thresholds