Integrate MongoDB with CrewAI

You can integrate MongoDB with CrewAI to build autonomous AI agents and multi-agent applications with specialized roles, tools, and tasks. Specifically, you can leverage the MongoDB Vector Search Tool for CrewAI to enable the AI agents in your crews to retrieve relevant information from your data to help them complete tasks.

Get Started

To complete a tutorial using CrewAI and MongoDB, see Build an Agentic RAG Application with CrewAI and MongoDB.

Installation

To install the MongoDB Vector Search Tool for CrewAI, run one of the following commands depending on your Python package manager:

pip install 'crewai-tools[mongodb]'

uv add crewai-tools --extra mongodb

Note

Python version compatibility might vary from CrewAI's official documentation. At the time of writing, the crewai-tools package depends on embedchain, which requires a Python version between 3.9 and 3.13.2 (inclusive).

Usage

To use the MongoDB Vector Search Tool, initialize it and then pass it to an agent.

To initialize the tool, you must specify the following:

from crewai_tools import MongoDBVectorSearchTool
tool = MongoDBVectorSearchTool(
  connection_string="<connection-string>",
  database_name="<database-name>",
  collection_name="<collection-name>",
  # Other optional parameters...
)
# To test the tool
print(tool.run(query="<test-query>"))
# To use the tool in an agent
rag_agent = Agent(
    name="rag_agent",
    role="You are a helpful assistant that can answer questions with the help of the MongoDBVectorSearchTool.",
    goal="...",
    backstory="...",
    tools=[tool],
)

Optionally, you can customize the vector search query for the tool by specifying an instance of MongoDBVectorSearchConfig to the tool's constructor.

To learn more about vector search queries, see Run Vector Search Queries.

from crewai_tools import MongoDBVectorSearchConfig, MongoDBVectorSearchTool
# Custom query configuration
query_config = MongoDBVectorSearchConfig(
  limit = 10,
  oversampling_factor = 2,
  )
tool = MongoDBVectorSearchTool(
    database_name="example_database",
    collection_name="example_collection",
    connection_string="<connection_string>",
    query_config=query_config,
    # Other optional parameters...
)
# To test the tool
print(tool.run(query="<test-query>"))
# To use the tool in an agent
rag_agent = Agent(
    name="rag_agent",
    role="You are a helpful assistant that can answer questions with the help of the MongoDBVectorSearchTool.",
    goal="...",
    backstory="...",
    tools=[tool],
)

MongoDBVectorSearchTool Parameters

Use these parameters to configure the vector search tool.

Parameter

Necessity

Description

connection_string

Required

The connection string for your MongoDB instance. To learn more about finding your connection string, see Connect to a Cluster via Drivers.

Note

For a local deployment, your connection string should use the following format:

mongodb://localhost:<port-number>/?directConnection=true

To learn more about connection strings, see Connection Strings.

database_name

Required

The name of the MongoDB database.

collection_name

Required

The name of the MongoDB collection.

query_config

Optional

An instance of MongoDBVectorSearchConfig to customize the vector search query.

embedding_model

Optional

The OpenAI embedding model used to generate vector embeddings. Defaults to text-embedding-3-large.

vector_index_name

Optional

The name of the MongoDB Vector Search index. Defaults to vector_index.

text_key

Optional

The document field containing the text content. Defaults to text.

embedding_key

Optional

The document field where the vector embedding is stored. Defaults to embedding.

dimensions

Optional

The number of dimensions for the vector embedding. Defaults to 1536.

MongoDBVectorSearchConfig Parameters

Use these parameters to customize the vector search query.

Parameter	Necessity	Description
`limit`	Optional	The maximum number of documents to return. Defaults to `4`.
`pre_filter`	Optional	A MongoDB `$match` expression to filter documents before the vector search.
`post_filter_pipeline`	Optional	A list of MongoDB aggregation stages to apply after the vector search.
`oversampling_factor`	Optional	A multiplier for `limit` to determine the number of candidates (`numCandidates`) considered during the search. Defaults to `10`.
`include_embeddings`	bool	If True, the vector embedding of each result is included in the output. Defaults to `False`.

Tip

Also see the CrewAI MongoDB Vector Search Tool Docs

Methods

The MongoDBVectorSearchTool class provides the following methods:

add_texts(): Adds text documents to the specified MongoDB collection.
create_vector_search_index(): Creates a vector search index on the collection.
run(): Runs a vector search query on your data.

import os
from crewai_tools import MongoDBVectorSearchTool
tool = MongoDBVectorSearchTool(
  connection_string="<connection-string>",
  database_name="<database-name>",
  collection_name="<collection-name>"
)
# Example of loading text content from a local folder
texts = []
for fname in os.listdir("knowledge"):
    path = os.path.join("knowledge", fname)
    if os.path.isfile(path):
        with open(path, "r", encoding="utf-8") as f:
            texts.append(f.read())
# Method to add documents to the vector store
tool.add_texts(texts)
# Method to create the vector search index
tool.create_vector_search_index(dimensions=<number-of-dimensions>)
# Method to test the tool by running a vector search query
tool.run(query="<search-query>")

create_vector_search_index() Parameters

Use these parameters to configure the vector index.

Parameter	Necessity	Description
`dimensions`	Required	The number of dimensions for the embedding vector.
`relevance_score_fn`	Optional	The similarity metric. Either `euclidean`, `cosine`, or `dotProduct`. Defaults to `cosine`.
`auto_index_timeout`	Optional	The time in seconds to wait for the index to become ready. Defaults to `15`.

To learn more about vector search indexes, see How to Index Fields for Vector Search.

add_texts() Parameters

Use these parameters to configure how MongoDB ingests documents.

Parameter	Necessity	Description
`texts`	Required	Array of iterable text documents to add.
`metadatas`	Optional	A list of metadata documents, one for each text document.
`ids`	Optional	A list of unique IDs for each document.
`batch_size`	Optional	The number of documents to process and insert in a single batch. Defaults to `100`.

Back

Build an AI Agent