Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

feat(tools): add Azure DocumentDB vector search integration (#8273)

Sandeep S Nairef11fa70e2a1
diff --git a/lib/crewai-tools/README.md b/lib/crewai-tools/README.md
index e0d1ddccb..9439749f4 100644
--- a/lib/crewai-tools/README.md
+++ b/lib/crewai-tools/README.md
@@ -25,7 +25,7 @@ CrewAI provides an extensive collection of powerful tools ready to enhance your
- **File Management**: `FileReadTool`, `FileWriteTool`
- **Web Scraping**: `ScrapeWebsiteTool`, `SeleniumScrapingTool`
- **Database Integrations**: `MySQLSearchTool`
-- **Vector Database Integrations**: `MongoDBVectorSearchTool`, `QdrantVectorSearchTool`, `WeaviateVectorSearchTool`
+- **Vector Database Integrations**: [AzureDocumentDBVectorSearchTool](src/crewai_tools/tools/azure_documentdb_vector_search_tool/README.md), `MongoDBVectorSearchTool`, `QdrantVectorSearchTool`, `WeaviateVectorSearchTool`
- **API Integrations**: `SerperApiTool`, `ExaSearchTool`
- **AI-powered Tools**: `DallETool`, `VisionTool`, `StagehandTool`
diff --git a/lib/crewai-tools/pyproject.toml b/lib/crewai-tools/pyproject.toml
index 683fcff24..6d277c849 100644
--- a/lib/crewai-tools/pyproject.toml
+++ b/lib/crewai-tools/pyproject.toml
@@ -148,6 +148,10 @@ oxylabs = [
# allow it rather than pinning consumers to a single release.
"oxylabs>=2.0.0,<4",
]
+azure-documentdb = [
+ "azure-identity>=1.17.0,<2",
+ "pymongo>=4.18.2",
+]
mongodb = [
# <4.18.1 has GHSA-8fvv-fgr5-f8ch (GridFS delete treats a mapping id as a
# query). <4.18.2 has GHSA-qx36-8mw2-4r3x, GHSA-v4x9-3549-crwv, and
diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.py
index 985e401b0..dc7aadf85 100644
--- a/lib/crewai-tools/src/crewai_tools/__init__.py
+++ b/lib/crewai-tools/src/crewai_tools/__init__.py
@@ -10,6 +10,11 @@ from crewai_tools.aws.s3.writer_tool import S3WriterTool
from crewai_tools.tools.ai_mind_tool.ai_mind_tool import AIMindTool
from crewai_tools.tools.apify_actors_tool.apify_actors_tool import ApifyActorsTool
from crewai_tools.tools.arxiv_paper_tool.arxiv_paper_tool import ArxivPaperTool
+from crewai_tools.tools.azure_documentdb_vector_search_tool import (
+ AzureDocumentDBToolSchema,
+ AzureDocumentDBVectorSearchConfig,
+ AzureDocumentDBVectorSearchTool,
+)
from crewai_tools.tools.brave_search_tool.brave_image_tool import BraveImageSearchTool
from crewai_tools.tools.brave_search_tool.brave_llm_context_tool import (
BraveLLMContextTool,
@@ -234,6 +239,9 @@ __all__ = [
"AIMindTool",
"ApifyActorsTool",
"ArxivPaperTool",
+ "AzureDocumentDBToolSchema",
+ "AzureDocumentDBVectorSearchConfig",
+ "AzureDocumentDBVectorSearchTool",
"BedrockInvokeAgentTool",
"BedrockKBRetrieverTool",
"BraveImageSearchTool",
diff --git a/lib/crewai-tools/src/crewai_tools/tools/__init__.py b/lib/crewai-tools/src/crewai_tools/tools/__init__.py
index d8846f718..eeff3d9ab 100644
--- a/lib/crewai-tools/src/crewai_tools/tools/__init__.py
+++ b/lib/crewai-tools/src/crewai_tools/tools/__init__.py
@@ -1,6 +1,11 @@
from crewai_tools.tools.ai_mind_tool.ai_mind_tool import AIMindTool
from crewai_tools.tools.apify_actors_tool.apify_actors_tool import ApifyActorsTool
from crewai_tools.tools.arxiv_paper_tool.arxiv_paper_tool import ArxivPaperTool
+from crewai_tools.tools.azure_documentdb_vector_search_tool import (
+ AzureDocumentDBToolSchema,
+ AzureDocumentDBVectorSearchConfig,
+ AzureDocumentDBVectorSearchTool,
+)
from crewai_tools.tools.brave_search_tool.brave_image_tool import BraveImageSearchTool
from crewai_tools.tools.brave_search_tool.brave_llm_context_tool import (
BraveLLMContextTool,
@@ -221,6 +226,9 @@ __all__ = [
"AIMindTool",
"ApifyActorsTool",
"ArxivPaperTool",
+ "AzureDocumentDBToolSchema",
+ "AzureDocumentDBVectorSearchConfig",
+ "AzureDocumentDBVectorSearchTool",
"BraveImageSearchTool",
"BraveLLMContextTool",
"BraveLocalPOIsDescriptionTool",
diff --git a/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/README.md b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/README.md
new file mode 100644
index 000000000..0b18fb5ab
--- /dev/null
+++ b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/README.md
@@ -0,0 +1,265 @@
+# Azure DocumentDB Vector Search Tool
+
+`AzureDocumentDBVectorSearchTool` stores and retrieves text documents using
+[Azure DocumentDB's native vector search](https://learn.microsoft.com/en-us/azure/documentdb/vector-search).
+It is separate from `MongoDBVectorSearchTool`: it uses DocumentDB's
+`$search.cosmosSearch` protocol, not MongoDB Atlas `$vectorSearch`.
+This integration is not for Amazon DocumentDB or Azure Cosmos DB for NoSQL.
+
+## Installation and resource setup
+
+```shell
+pip install "crewai-tools[azure-documentdb]"
+```
+
+Create an [Azure DocumentDB cluster](https://learn.microsoft.com/en-us/azure/documentdb/quickstart-python-vector-search)
+with vector search available on your tier. Allow your application's network
+through the cluster firewall, create a database user with read/write and index
+creation permissions, and obtain the MongoDB-compatible connection string from
+the Azure portal. Use the supplied TLS and authentication parameters; do not
+disable certificate validation for Azure connections.
+
+Create your database and collection before creating an index. Index creation
+is explicit, not performed at tool initialization or on every query. The helper
+creates an IVF index; for HNSW or DiskANN, provision an index on `embedding`
+following the Azure documentation and your tier's requirements.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `AZURE_DOCUMENTDB_CONNECTION_STRING` | Database connection string; alternatively pass `connection_string` to the constructor. |
+| `OPENAI_API_KEY` | OpenAI embedding API key, unless using Azure OpenAI. |
+| `AZURE_OPENAI_ENDPOINT` | Set to select Azure OpenAI instead of OpenAI. |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI embedding API key, unless using Entra ID. |
+| `OPENAI_API_VERSION` | API version supported by your Azure OpenAI resource. |
+
+Database authentication uses the connection string, with a renewable Entra ID
+token callback when it specifies `authMechanism=MONGODB-OIDC`. Database and
+embedding access require separate permissions, even when using the same identity.
+Keep credentials in environment variables or a secret manager, never in source
+control.
+
+`embedding_model` defaults to `text-embedding-3-small` and `dimensions` to 1536.
+For Azure OpenAI, pass your **embedding deployment name** as `embedding_model`.
+Use a text-embedding-3-compatible model/deployment supporting the `dimensions`
+parameter. The same model and dimensions must be used for ingestion and queries,
+and the index dimensions must match. Changing models requires re-embedding data.
+
+## Keyless authentication with Microsoft Entra ID
+
+Enable [Entra authentication on DocumentDB](https://learn.microsoft.com/en-us/azure/documentdb/how-to-connect-role-based-access-control)
+and register your identity with database permissions to create collections and
+indexes, read/write documents, and drop test collections. Azure subscription
+Contributor alone does not grant database access. For Azure OpenAI, assign
+**Cognitive Services OpenAI User** or another role allowing embedding inference.
+Both service firewalls must allow your client to connect.
+
+For local development, use your existing Azure CLI login:
+
+```powershell
+az login --tenant "<tenant-id>"
+$env:AZURE_DOCUMENTDB_CONNECTION_STRING = "mongodb+srv://<cluster>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=MONGODB-OIDC&retrywrites=false&maxIdleTimeMS=120000"
+$env:AZURE_OPENAI_ENDPOINT = "https://<resource>.openai.azure.com"
+$env:OPENAI_API_VERSION = "2023-05-15"
+```
+
+Pass the resource's base endpoint, not the full embeddings URL. Select the
+embedding deployment with `embedding_model`:
+
+```python
+import os
+from azure.identity import AzureCliCredential
+from crewai_tools import AzureDocumentDBVectorSearchTool
+
+with AzureCliCredential(tenant_id=os.environ["AZURE_TENANT_ID"]) as credential:
+ tool = AzureDocumentDBVectorSearchTool(
+ database_name="knowledge",
+ collection_name="documents",
+ embedding_model="text-embedding-3-small",
+ azure_credential=credential,
+ )
+ try:
+ results = tool.run(query="How do AI agents collaborate?")
+ finally:
+ tool.close()
+```
+
+Set `AZURE_TENANT_ID` to the tenant used for `az login`. No client secret,
+database password, or OpenAI API key is needed for this flow.
+
+The injected `azure_credential` is used for DocumentDB OIDC and Azure OpenAI
+bearer tokens. Tokens are reacquired as needed, not stored as static passwords.
+The caller owns the injected credential and must close it after the tool.
+For production on Azure, inject `ManagedIdentityCredential`; for a service
+principal, inject `EnvironmentCredential` with `AZURE_TENANT_ID`,
+`AZURE_CLIENT_ID`, and its secret/certificate or other supported credential.
+An explicit credential avoids falling back to a different identity.
+
+If no credential is passed, an OIDC connection string selects
+`DefaultAzureCredential` automatically, and that credential is also used for
+Azure OpenAI. For a password-authenticated database with keyless Azure OpenAI,
+set `use_azure_identity=True`. The tool closes credentials it creates internally.
+The existing OpenAI/Azure OpenAI API-key path remains available when Entra is not
+selected.
+
+## Ingestion and CrewAI Agent usage
+
+```python
+import json
+import os
+
+from crewai import Agent
+from crewai_tools import (
+ AzureDocumentDBVectorSearchConfig,
+ AzureDocumentDBVectorSearchTool,
+)
+
+tool = AzureDocumentDBVectorSearchTool(
+ # Omit this argument to read AZURE_DOCUMENTDB_CONNECTION_STRING automatically.
+ connection_string=os.environ["AZURE_DOCUMENTDB_CONNECTION_STRING"],
+ database_name="knowledge",
+ collection_name="documents",
+ embedding_model="text-embedding-3-small", # Azure: use your deployment name.
+ dimensions=1536,
+ query_config=AzureDocumentDBVectorSearchConfig(limit=4),
+)
+
+try:
+ # The collection must exist; create it once using your provisioning process.
+ # On a new collection, ingest before building the vector index.
+ ids = tool.add_texts(
+ ["CrewAI orchestrates collaborative AI agents.", "DocumentDB supports vector search."],
+ metadatas=[{"category": "agents"}, {"category": "database"}],
+ ids=["crewai-intro", "documentdb-intro"], # Optional; otherwise UUIDs are generated.
+ batch_size=100,
+ )
+ tool.create_vector_search_index(similarity="COS", num_lists=1)
+ print(json.loads(tool.run(query="How do I coordinate AI agents?")))
+
+ agent = Agent(
+ role="Knowledge researcher",
+ goal="Find relevant information in our DocumentDB knowledge base",
+ backstory="You ground your answers in retrieved documents.",
+ tools=[tool],
+ verbose=True,
+ )
+ # Run your Crew with this agent before closing the tool.
+finally:
+ tool.close()
+```
+
+`add_texts` accepts an iterable of strings, including generators. It stores
+`{ "_id": "...", "text": "...", "metadata": {...}, "embedding": [...] }`.
+IDs and metadata must match the text count; duplicate IDs raise write errors
+(insertion is not an upsert). Empty input returns an empty ID list. Each batch
+gets its own embedding request and insert; earlier batches persist if a later
+batch fails. Database and embedding errors propagate to the caller.
+
+The index helper sends this native command (with your collection and dimensions):
+
+```json
+{
+ "createIndexes": "documents",
+ "indexes": [{
+ "name": "crewai_vector_index",
+ "key": {"embedding": "cosmosSearch"},
+ "cosmosSearchOptions": {
+ "kind": "vector-ivf",
+ "numLists": 1,
+ "similarity": "COS",
+ "dimensions": 1536
+ }
+ }]
+}
+```
+
+Supported similarity values are `COS`, `L2`, and `IP`. Tune `num_lists` for your
+data size according to Azure's guidance. The helper does not drop or rebuild
+existing indexes; conflicting definitions raise database errors.
+
+## Query options and output
+
+```python
+config = AzureDocumentDBVectorSearchConfig(
+ limit=5,
+ pre_filter={"metadata.category": "agents"},
+ include_score=True,
+ include_embeddings=False,
+)
+```
+
+Pass this as `query_config`. Filters run **during** vector search, not after
+limiting results. Provision scalar indexes for filter fields as required by your
+cluster, for example `collection.create_index("metadata.category")`.
+`limit` must be positive; score output defaults to enabled and embeddings to
+excluded. The tool returns a JSON array string containing the stored document
+fields and optional `score`, or `[]` when there are no matches.
+BSON-only values such as ObjectId and dates use MongoDB Extended JSON
+(`{"$oid": "..."}`, `{"$date": "..."}`), so `json.loads` always works.
+Consumers should not assume scores have the same scale across similarity metrics.
+
+## Podman Desktop end-to-end tests
+
+Start the Podman Desktop engine, then run the official open-source DocumentDB
+local image. These PowerShell commands bind the database to loopback only:
+
+```powershell
+podman pull ghcr.io/documentdb/documentdb/documentdb-local:latest
+podman run -d --name crewai-documentdb-e2e -p 127.0.0.1:10260:10260 ghcr.io/documentdb/documentdb/documentdb-local:latest --username crewai_e2e --password local_e2e_only
+$env:AZURE_DOCUMENTDB_E2E_CONNECTION_STRING = "mongodb://crewai_e2e:[email protected]:10260/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true"
+uv run --package crewai-tools --extra azure-documentdb pytest lib\crewai-tools\tests\tools\test_azure_documentdb_vector_search_e2e.py -o addopts="" -n 0
+podman rm -f crewai-documentdb-e2e
+Remove-Item Env:\AZURE_DOCUMENTDB_E2E_CONNECTION_STRING
+```
+
+The self-signed certificate exception is **only for the local test container**.
+If Windows refuses the connection while the container is healthy, WSL may not
+be forwarding its loopback port. In a separate PowerShell terminal, keep an SSH
+tunnel to the Podman machine running:
+
+```powershell
+$machine = (podman machine inspect podman-machine-default | ConvertFrom-Json)[0]
+ssh -i $machine.SSHConfig.IdentityPath -p $machine.SSHConfig.Port -o ExitOnForwardFailure=yes -N -L 127.0.0.1:10261:127.0.0.1:10260 "$($machine.SSHConfig.RemoteUsername)@127.0.0.1"
+```
+
+Use port `10261` instead of `10260` in the test connection string in the first
+terminal, and stop the tunnel with Ctrl+C after testing.
+
+The tests use a local HTTP embedding fixture through the real OpenAI SDK, so no
+cloud credentials or paid embedding calls are needed. They verify real ingestion,
+IVF index creation, similarity ordering, filters, limits, score/embedding output,
+and duplicate-ID errors. Each test creates and drops its own collection.
+Without the E2E connection variable these tests are skipped. This validates the
+DocumentDB wire protocol locally, not Azure-managed firewall, TLS, tier support,
+or a live Azure OpenAI deployment.
+
+Run the unit tests separately:
+
+```powershell
+uv run --package crewai-tools --extra azure-documentdb pytest lib\crewai-tools\tests\tools\test_azure_documentdb_vector_search_tool.py
+```
+
+## Live Azure end-to-end test
+
+This opt-in test uses actual Azure OpenAI embeddings and a unique DocumentDB
+collection. It incurs embedding charges and requires permission to create and
+delete that collection. It never drops a pre-existing collection or the database.
+
+```powershell
+$env:AZURE_DOCUMENTDB_LIVE_CONNECTION_STRING = $env:AZURE_DOCUMENTDB_CONNECTION_STRING
+$env:AZURE_DOCUMENTDB_LIVE_OPENAI_ENDPOINT = $env:AZURE_OPENAI_ENDPOINT
+$env:AZURE_DOCUMENTDB_LIVE_EMBEDDING_DEPLOYMENT = "text-embedding-3-small"
+$env:AZURE_DOCUMENTDB_LIVE_OPENAI_API_VERSION = "2023-05-15"
+$env:AZURE_DOCUMENTDB_LIVE_IDENTITY = "azure_cli"
+$env:AZURE_DOCUMENTDB_LIVE_TENANT_ID = "<tenant-id>"
+$env:AZURE_DOCUMENTDB_LIVE_DATABASE = "crewai_e2e"
+uv run --package crewai-tools --extra azure-documentdb pytest lib\crewai-tools\tests\tools\test_azure_documentdb_vector_search_e2e.py -k live_azure -o addopts="" -n 0
+```
+
+Alternatively set `AZURE_DOCUMENTDB_LIVE_IDENTITY=environment` (the default) to
+use a service principal through `EnvironmentCredential`. CLI and environment
+modes never fall back to each other. API-key environment settings are cleared
+within the test, ensuring both services authenticate with Entra tokens. The test
+verifies ingestion, indexing, similarity scores, filters, output options, and
+collection cleanup. Without the live connection variable it is skipped.
diff --git a/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/__init__.py b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/__init__.py
new file mode 100644
index 000000000..5021bd111
--- /dev/null
+++ b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/__init__.py
@@ -0,0 +1,12 @@
+from crewai_tools.tools.azure_documentdb_vector_search_tool.vector_search import (
+ AzureDocumentDBToolSchema,
+ AzureDocumentDBVectorSearchConfig,
+ AzureDocumentDBVectorSearchTool,
+)
+
+
+__all__ = [
+ "AzureDocumentDBToolSchema",
+ "AzureDocumentDBVectorSearchConfig",
+ "AzureDocumentDBVectorSearchTool",
+]
diff --git a/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/auth.py b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/auth.py
new file mode 100644
index 000000000..460aba90e
--- /dev/null
+++ b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/auth.py
@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from pymongo.auth_oidc import OIDCCallback, OIDCCallbackContext, OIDCCallbackResult
+
+
+if TYPE_CHECKING:
+ from azure.core.credentials import TokenCredential
+
+
+class DocumentDBOIDCCallback(OIDCCallback):
+ """Acquire renewable DocumentDB tokens using an Azure credential."""
+
+ def __init__(self, credential: TokenCredential) -> None:
+ """Retain the caller's Azure credential for token acquisition."""
+ self._credential = credential
+
+ def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
+ """Return a DocumentDB access token and its remaining lifetime."""
+ token = self._credential.get_token(
+ "https://ossrdbms-aad.database.windows.net/.default"
+ )
+ return OIDCCallbackResult(
+ access_token=token.token,
+ expires_in_seconds=max(0, token.expires_on - time.time()),
+ )
diff --git a/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/vector_search.py b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/vector_search.py
new file mode 100644
index 000000000..6c2e19a64
--- /dev/null
+++ b/lib/crewai-tools/src/crewai_tools/tools/azure_documentdb_vector_search_tool/vector_search.py
@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+import math
+import os
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import parse_qsl, urlsplit
+from uuid import uuid4
+
+from crewai.tools import BaseTool, EnvVar
+from openai import AzureOpenAI, OpenAI
+from pydantic import BaseModel, Field, PrivateAttr
+
+
+if TYPE_CHECKING:
+ from azure.core.credentials import TokenCredential
+ from azure.identity import DefaultAzureCredential
+ from pymongo import MongoClient
+ from pymongo.collection import Collection
+
+
+class AzureDocumentDBVectorSearchConfig(BaseModel):
+ """Options for Azure DocumentDB's native vector search."""
+
+ limit: int = Field(default=4, ge=1, description="Maximum number of results.")
+ pre_filter: dict[str, Any] | None = Field(
+ default=None,
+ description="DocumentDB filter applied during search, e.g. metadata.category.",
+ )
+ include_score: bool = Field(default=True, description="Return similarity scores.")
+ include_embeddings: bool = Field(
+ default=False, description="Return stored embedding vectors."
+ )
+
+
+class AzureDocumentDBToolSchema(BaseModel):
+ """Input accepted by the Azure DocumentDB vector search tool."""
+
+ query: str = Field(
+ ..., min_length=1, description="Text to find relevant documents for."
+ )
+
+
+class AzureDocumentDBVectorSearchTool(BaseTool):
+ """Retrieve documents using Azure DocumentDB, not MongoDB Atlas vector search.
+
+ Documents contain ``text``, ``metadata`` and ``embedding`` fields. Embeddings
+ use OpenAI, or Azure OpenAI when AZURE_OPENAI_ENDPOINT is configured.
+ """
+
+ name: str = "AzureDocumentDBVectorSearchTool"
+ description: str = (
+ "Search Azure DocumentDB for documents relevant to a natural language query."
+ )
+ args_schema: type[BaseModel] = AzureDocumentDBToolSchema
+ connection_string: str = Field(
+ default_factory=lambda: os.environ.get(
+ "AZURE_DOCUMENTDB_CONNECTION_STRING", ""
+ ),
+ min_length=1,
+ repr=False,
+ exclude=True,
+ description="Azure DocumentDB MongoDB-compatible connection string.",
+ )
+ database_name: str = Field(..., min_length=1)
+ collection_name: str = Field(..., min_length=1)
+ query_config: AzureDocumentDBVectorSearchConfig = Field(
+ default_factory=AzureDocumentDBVectorSearchConfig
+ )
+ embedding_model: str = Field(
+ default="text-embedding-3-small",
+ min_length=1,
+ description="OpenAI embedding model or Azure OpenAI deployment name.",
+ )
+ dimensions: int = Field(default=1536, ge=1)
+ vector_index_name: str = Field(default="crewai_vector_index", min_length=1)
+ connection_timeout_ms: int = Field(default=10000, ge=1)
+ use_azure_identity: bool = Field(
+ default=False,
+ description="Use renewable Entra tokens for Azure OpenAI instead of an API key.",
+ )
+ package_dependencies: list[str] = Field(
+ default_factory=lambda: ["pymongo", "azure-identity"]
+ )
+ env_vars: list[EnvVar] = Field(
+ default_factory=lambda: [
+ EnvVar(
+ name="AZURE_DOCUMENTDB_CONNECTION_STRING",
+ description="Connection string, unless passed to the constructor.",
+ required=False,
+ ),
+ EnvVar(
+ name="OPENAI_API_KEY",
+ description="OpenAI key (not required when using Azure OpenAI).",
+ required=False,
+ ),
+ EnvVar(
+ name="AZURE_OPENAI_ENDPOINT",
+ description="Set to use Azure OpenAI for embeddings.",
+ required=False,
+ ),
+ EnvVar(
+ name="AZURE_OPENAI_API_KEY",
+ description="Azure OpenAI key when using Azure OpenAI.",
+ required=False,
+ ),
+ EnvVar(
+ name="OPENAI_API_VERSION",
+ description="Azure OpenAI API version when using Azure OpenAI.",
+ required=False,
+ ),
+ ]
+ )
+
+ _client: MongoClient[dict[str, Any]] = PrivateAttr()
+ _coll: Collection[dict[str, Any]] = PrivateAttr()
+ _openai_client: OpenAI | AzureOpenAI | None = PrivateAttr(default=None)
+ _azure_credential: TokenCredential | None = PrivateAttr(default=None)
+ _owned_credential: DefaultAzureCredential | None = PrivateAttr(default=None)
+
+ def __init__(
+ self, *, azure_credential: TokenCredential | None = None, **kwargs: Any
+ ) -> None:
+ """Accept an optional Azure credential, whose lifetime the caller owns."""
+ super().__init__(**kwargs)
+ try:
+ from pymongo import MongoClient
+ except ImportError as exc:
+ raise ImportError(
+ "Install Azure DocumentDB support with "
+ "`pip install 'crewai-tools[azure-documentdb]'`."
+ ) from exc
+
+ self._azure_credential = azure_credential
+ auth_options: dict[str, Any] = {}
+ uri_options = {
+ key.lower(): value
+ for key, value in parse_qsl(urlsplit(self.connection_string).query)
+ }
+ if uri_options.get("authmechanism", "").upper() == "MONGODB-OIDC":
+ from crewai_tools.tools.azure_documentdb_vector_search_tool.auth import (
+ DocumentDBOIDCCallback,
+ )
+
+ auth_options = {
+ "authMechanismProperties": {
+ "OIDC_CALLBACK": DocumentDBOIDCCallback(
+ self._get_azure_credential()
+ )
+ }
+ }
+ self._client = MongoClient(
+ self.connection_string,
+ appname="crewai-azure-documentdb",
+ serverSelectionTimeoutMS=self.connection_timeout_ms,
+ **auth_options,
+ )
+ self._coll = self._client[self.database_name][self.collection_name]
+
+ def _get_azure_credential(self) -> TokenCredential:
+ """Reuse the injected credential or create an internally owned default."""
+ if self._azure_credential is None:
+ try:
+ from azure.identity import DefaultAzureCredential
+ except ImportError as exc:
+ raise ImportError(
+ "Entra authentication requires azure-identity. Install "
+ "`pip install 'crewai-tools[azure-documentdb]'`."
+ ) from exc
+ self._owned_credential = DefaultAzureCredential()
+ self._azure_credential = self._owned_credential
+ return self._azure_credential
+
+ def _embed_texts(self, texts: list[str]) -> list[list[float]]:
+ """Generate ordered, finite embeddings matching the configured dimensions."""
+ if self._openai_client is None:
+ if os.environ.get("AZURE_OPENAI_ENDPOINT"):
+ if self.use_azure_identity or self._azure_credential is not None:
+ from azure.identity import get_bearer_token_provider
+
+ self._openai_client = AzureOpenAI(
+ azure_ad_token_provider=get_bearer_token_provider(
+ self._get_azure_credential(),
+ "https://cognitiveservices.azure.com/.default",
+ )
+ )
+ else:
+ self._openai_client = AzureOpenAI()
+ elif self.use_azure_identity:
+ raise ValueError(
+ "AZURE_OPENAI_ENDPOINT is required when use_azure_identity=True."
+ )
+ elif os.environ.get("OPENAI_API_KEY"):
+ self._openai_client = OpenAI()
+ else:
+ raise ValueError(
+ "Set OPENAI_API_KEY, or AZURE_OPENAI_ENDPOINT, "
+ "AZURE_OPENAI_API_KEY and OPENAI_API_VERSION for embeddings."
+ )
+ response = self._openai_client.embeddings.create(
+ input=texts, model=self.embedding_model, dimensions=self.dimensions
+ )
+ embeddings = [
+ item.embedding
+ for item in sorted(response.data, key=lambda item: item.index)
+ ]
+ if len(embeddings) != len(texts) or any(
+ len(vector) != self.dimensions
+ or not all(math.isfinite(value) for value in vector)
+ for vector in embeddings
+ ):
+ raise ValueError(
+ "Embedding response must contain one finite vector per text "
+ f"with {self.dimensions} dimensions."
+ )
+ return embeddings
+
+ def create_vector_search_index(
+ self, *, similarity: Literal["COS", "L2", "IP"] = "COS", num_lists: int = 1
+ ) -> None:
+ """Create an IVF index without dropping existing indexes.
+
+ The collection must already exist. Use the same dimensions and similarity
+ for ingestion and search. Tune num_lists for larger collections.
+ """
+ if similarity not in {"COS", "L2", "IP"}:
+ raise ValueError("similarity must be COS, L2 or IP.")
+ if num_lists < 1:
+ raise ValueError("num_lists must be positive.")
+ self._coll.database.command(
+ {
+ "createIndexes": self.collection_name,
+ "indexes": [
+ {
+ "name": self.vector_index_name,
+ "key": {"embedding": "cosmosSearch"},
+ "cosmosSearchOptions": {
+ "kind": "vector-ivf",
+ "numLists": num_lists,
+ "similarity": similarity,
+ "dimensions": self.dimensions,
+ },
+ }
+ ],
+ }
+ )
+
+ def add_texts(
+ self,
+ texts: Iterable[str],
+ metadatas: list[dict[str, Any]] | None = None,
+ ids: list[str] | None = None,
+ batch_size: int = 100,
+ ) -> list[str]:
+ """Embed and insert texts, returning their IDs.
+
+ Supplied IDs are preserved; duplicates raise the database's write error.
+ Metadata is nested under ``metadata`` and cannot overwrite text or vectors.
+ Batches already inserted remain persisted if a later batch fails.
+ """
+ if batch_size < 1:
+ raise ValueError("batch_size must be positive.")
+ documents = list(texts)
+ if any(not isinstance(text, str) or not text.strip() for text in documents):
+ raise ValueError("texts must contain non-blank strings.")
+ if metadatas is not None and len(metadatas) != len(documents):
+ raise ValueError("metadatas must have the same length as texts.")
+ if ids is not None and (
+ len(ids) != len(documents)
+ or any(not isinstance(value, str) or not value for value in ids)
+ or len(set(ids)) != len(ids)
+ ):
+ raise ValueError("ids must contain one unique, non-empty string per text.")
+ result_ids = ids if ids is not None else [str(uuid4()) for _ in documents]
+ for start in range(0, len(documents), batch_size):
+ batch = documents[start : start + batch_size]
+ embeddings = self._embed_texts(batch)
+ self._coll.insert_many(
+ [
+ {
+ "_id": result_ids[start + offset],
+ "text": text,
+ "metadata": metadatas[start + offset]
+ if metadatas is not None
+ else {},
+ "embedding": vector,
+ }
+ for offset, (text, vector) in enumerate(
+ zip(batch, embeddings, strict=True)
+ )
+ ]
+ )
+ return list(result_ids)
+
+ def _run(self, query: str) -> str:
+ """Search DocumentDB and serialize matching documents as Extended JSON."""
+ from bson import json_util
+
+ if not query.strip():
+ raise ValueError("query must not be blank.")
+ config = self.query_config
+ search: dict[str, Any] = {
+ "vector": self._embed_texts([query])[0],
+ "path": "embedding",
+ "k": config.limit,
+ }
+ if config.pre_filter is not None:
+ search["filter"] = config.pre_filter
+ pipeline: list[dict[str, Any]] = [
+ {"$search": {"cosmosSearch": search, "returnStoredSource": True}}
+ ]
+ if config.include_score:
+ pipeline.append({"$addFields": {"score": {"$meta": "searchScore"}}})
+ if not config.include_embeddings:
+ pipeline.append({"$project": {"embedding": 0}})
+ return str(json_util.dumps(list(self._coll.aggregate(pipeline))))
+
+ def close(self) -> None:
+ """Release clients and internally created credentials, not caller credentials."""
+ self._client.close()
+ if self._openai_client is not None:
+ self._openai_client.close()
+ if self._owned_credential is not None:
+ self._owned_credential.close()
diff --git a/lib/crewai-tools/tests/tools/test_azure_documentdb_vector_search_e2e.py b/lib/crewai-tools/tests/tools/test_azure_documentdb_vector_search_e2e.py
new file mode 100644
index 000000000..eab741a53
--- /dev/null
+++ b/lib/crewai-tools/tests/tools/test_azure_documentdb_vector_search_e2e.py
@@ -0,0 +1,233 @@
+"""Opt-in tests against local DocumentDB or live Azure with Entra authentication."""
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import math
+import os
+from threading import Thread
+from uuid import uuid4
+
+from crewai_tools import (
+ AzureDocumentDBVectorSearchConfig,
+ AzureDocumentDBVectorSearchTool,
+)
+from pymongo.errors import BulkWriteError
+import pytest
+
+
+def documentdb_tool(monkeypatch):
+ """Use real OpenAI HTTP/SDK calls with deterministic, offline embeddings."""
+ if not os.environ.get("AZURE_DOCUMENTDB_E2E_CONNECTION_STRING"):
+ pytest.skip("Set AZURE_DOCUMENTDB_E2E_CONNECTION_STRING for local E2E tests.")
+ vectors = {
+ "apple": [1.0, 0.0, 0.0],
+ "pear": [0.8, 0.2, 0.0],
+ "truck": [0.0, 0.0, 1.0],
+ }
+ requests = []
+
+ class EmbeddingsHandler(BaseHTTPRequestHandler):
+ def do_POST(self):
+ """Validate an embedding request and return deterministic vectors."""
+ request = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+ requests.append(request)
+ assert self.path == "/v1/embeddings"
+ assert request["dimensions"] == 3
+ assert request["model"] == "text-embedding-3-small"
+ payload = json.dumps(
+ {
+ "object": "list",
+ "model": request["model"],
+ "data": [
+ {
+ "object": "embedding",
+ "index": index,
+ "embedding": vectors[text],
+ }
+ for index, text in enumerate(request["input"])
+ ],
+ "usage": {"prompt_tokens": 1, "total_tokens": 1},
+ }
+ ).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(payload)))
+ self.end_headers()
+ self.wfile.write(payload)
+
+ def log_message(self, *args):
+ """Keep the local embedding server's request logs out of test output."""
+
+ server = ThreadingHTTPServer(("127.0.0.1", 0), EmbeddingsHandler)
+ thread = Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ monkeypatch.setenv("OPENAI_API_KEY", "local-e2e-not-a-real-key")
+ monkeypatch.setenv("OPENAI_BASE_URL", f"http://127.0.0.1:{server.server_port}/v1")
+ monkeypatch.delenv("AZURE_OPENAI_ENDPOINT", raising=False)
+ tool = AzureDocumentDBVectorSearchTool(
+ connection_string=os.environ["AZURE_DOCUMENTDB_E2E_CONNECTION_STRING"],
+ database_name="crewai_e2e",
+ collection_name=f"vectors_{uuid4().hex}",
+ dimensions=3,
+ query_config=AzureDocumentDBVectorSearchConfig(limit=3),
+ )
+ collection_created = False
+ try:
+ tool._client.admin.command("ping")
+ tool._coll.database.create_collection(tool.collection_name)
+ collection_created = True
+ yield tool, requests
+ finally:
+ try:
+ if collection_created:
+ tool._coll.drop()
+ finally:
+ tool.close()
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=5)
+
+
+def test_real_documentdb_ingestion_index_and_ranked_search(documentdb_tool):
+ """Verify ingestion, IVF indexing, ranking, and optional result fields."""
+ tool, requests = documentdb_tool
+ assert tool.add_texts(
+ (text for text in ["apple", "pear", "truck"]),
+ metadatas=[{"kind": "fruit"}, {"kind": "fruit"}, {"kind": "vehicle"}],
+ ids=["apple-id", "pear-id", "truck-id"],
+ batch_size=2,
+ ) == ["apple-id", "pear-id", "truck-id"]
+ tool.create_vector_search_index()
+ tool.create_vector_search_index() # Repeating identical index creation is safe.
+ assert tool._coll.count_documents({}) == 3
+ assert "crewai_vector_index" in tool._coll.index_information()
+ results = json.loads(tool.run(query="apple"))
+ assert [doc["_id"] for doc in results] == ["apple-id", "pear-id", "truck-id"]
+ assert results[0]["text"] == "apple"
+ assert results[0]["metadata"] == {"kind": "fruit"}
+ assert all("embedding" not in doc for doc in results)
+ assert all(math.isfinite(doc["score"]) for doc in results)
+ assert results[0]["score"] > results[1]["score"] > results[2]["score"]
+ assert [request["input"] for request in requests] == [
+ ["apple", "pear"],
+ ["truck"],
+ ["apple"],
+ ]
+
+ tool.query_config = AzureDocumentDBVectorSearchConfig(
+ limit=1, include_embeddings=True, include_score=False
+ )
+ results = json.loads(tool.run(query="truck"))
+ assert len(results) == 1
+ assert results[0]["_id"] == "truck-id"
+ assert results[0]["embedding"] == [0.0, 0.0, 1.0]
+ assert "score" not in results[0]
+
+
+def test_real_documentdb_prefilter_and_duplicate_id_error(documentdb_tool):
+ """Verify native metadata filtering and duplicate-ID write failures."""
+ tool, _ = documentdb_tool
+ tool.add_texts(
+ ["apple", "pear", "truck"],
+ metadatas=[{"kind": "fruit"}, {"kind": "fruit"}, {"kind": "vehicle"}],
+ ids=["a", "b", "c"],
+ )
+ tool.create_vector_search_index()
+ tool._coll.create_index("metadata.kind")
+ tool.query_config = AzureDocumentDBVectorSearchConfig(
+ limit=2, pre_filter={"metadata.kind": "vehicle"}
+ )
+ results = json.loads(tool.run(query="apple"))
+ assert len(results) == 1
+ assert results[0]["_id"] == "c"
+ tool.query_config.pre_filter = {"metadata.kind": "missing"}
+ assert json.loads(tool.run(query="apple")) == []
+ with pytest.raises(BulkWriteError):
+ tool.add_texts(["apple"], ids=["a"])
+
+
+ not os.environ.get("AZURE_DOCUMENTDB_LIVE_CONNECTION_STRING"),
+ reason="Set AZURE_DOCUMENTDB_LIVE_CONNECTION_STRING to opt into live Azure tests.",
+)
+def test_live_azure_documentdb_and_openai_with_entra(monkeypatch):
+ """Use an explicitly selected identity without falling back to another login."""
+ from azure.identity import AzureCliCredential, EnvironmentCredential
+
+ endpoint = os.environ["AZURE_DOCUMENTDB_LIVE_OPENAI_ENDPOINT"]
+ deployment = os.environ["AZURE_DOCUMENTDB_LIVE_EMBEDDING_DEPLOYMENT"]
+ api_version = os.environ["AZURE_DOCUMENTDB_LIVE_OPENAI_API_VERSION"]
+ monkeypatch.setenv("AZURE_OPENAI_ENDPOINT", endpoint)
+ monkeypatch.setenv("OPENAI_API_VERSION", api_version)
+ monkeypatch.delenv("AZURE_OPENAI_API_KEY", raising=False)
+ monkeypatch.delenv("AZURE_OPENAI_AD_TOKEN", raising=False)
+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+ monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+ text = "CrewAI coordinates collaborative AI agents to complete research tasks."
+ identity = os.environ.get("AZURE_DOCUMENTDB_LIVE_IDENTITY", "environment")
+ if identity == "azure_cli":
+ credential = AzureCliCredential(
+ tenant_id=os.environ["AZURE_DOCUMENTDB_LIVE_TENANT_ID"]
+ )
+ elif identity == "environment":
+ credential = EnvironmentCredential()
+ else:
+ raise ValueError(
+ "AZURE_DOCUMENTDB_LIVE_IDENTITY must be azure_cli or environment."
+ )
+ with credential:
+ tool = AzureDocumentDBVectorSearchTool(
+ connection_string=os.environ["AZURE_DOCUMENTDB_LIVE_CONNECTION_STRING"],
+ database_name=os.environ.get(
+ "AZURE_DOCUMENTDB_LIVE_DATABASE", "crewai_e2e"
+ ),
+ collection_name=f"live_vectors_{uuid4().hex}",
+ embedding_model=deployment,
+ dimensions=1536,
+ azure_credential=credential,
+ query_config=AzureDocumentDBVectorSearchConfig(limit=2),
+ )
+ collection_created = False
+ try:
+ assert tool._client.admin.command("ping")["ok"] == 1
+ tool._coll.database.create_collection(tool.collection_name)
+ collection_created = True
+ assert tool.add_texts(
+ [text, "A truck transports heavy cargo along the highway."],
+ metadatas=[{"category": "agents"}, {"category": "transport"}],
+ ids=["agents", "truck"],
+ ) == ["agents", "truck"]
+ tool.create_vector_search_index()
+ tool._coll.create_index("metadata.category")
+ results = json.loads(tool.run(query=text))
+ assert len(results) == 2
+ assert results[0]["_id"] == "agents"
+ assert results[0]["score"] > 0.9
+ assert results[0]["score"] > results[1]["score"]
+ assert all("embedding" not in doc for doc in results)
+ assert tool._coll.count_documents({}) == 2
+ tool.query_config = AzureDocumentDBVectorSearchConfig(
+ limit=1,
+ pre_filter={"metadata.category": "transport"},
+ include_embeddings=True,
+ include_score=False,
+ )
+ results = json.loads(tool.run(query=text))
+ assert len(results) == 1
+ assert results[0]["_id"] == "truck"
+ assert len(results[0]["embedding"]) == 1536
+ assert all(math.isfinite(value) for value in results[0]["embedding"])
+ assert "score" not in results[0]
+ tool.query_config.pre_filter = {"metadata.category": "missing"}
+ assert json.loads(tool.run(query=text)) == []
+ finally:
+ try:
+ if collection_created:
+ tool._coll.drop()
+ assert (
+ tool.collection_name
+ not in tool._coll.database.list_collection_names()
+ )
+ finally:
+ tool.close()
diff --git a/lib/crewai-tools/tests/tools/test_azure_documentdb_vector_search_tool.py b/lib/crewai-tools/tests/tools/test_azure_documentdb_vector_search_tool.py
new file mode 100644
index 000000000..b801c9a4e
--- /dev/null
+++ b/lib/crewai-tools/tests/tools/test_azure_documentdb_vector_search_tool.py
@@ -0,0 +1,456 @@
+import builtins
+from datetime import datetime, timezone
+import json
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+from bson import ObjectId
+from crewai_tools import (
+ AzureDocumentDBToolSchema,
+ AzureDocumentDBVectorSearchConfig,
+ AzureDocumentDBVectorSearchTool,
+)
+from crewai_tools.generate_tool_specs import ToolSpecExtractor
+from crewai_tools.tools.azure_documentdb_vector_search_tool import vector_search
+from pydantic import ValidationError
+from pymongo.errors import OperationFailure
+import pytest
+
+
+def tool(monkeypatch):
+ """Provide an isolated tool with mocked database and embedding clients."""
+ monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+ monkeypatch.delenv("AZURE_OPENAI_ENDPOINT", raising=False)
+ with (
+ patch("pymongo.MongoClient"),
+ patch.object(vector_search, "OpenAI") as openai,
+ ):
+ openai.return_value.embeddings.create.side_effect = lambda **kwargs: (
+ SimpleNamespace(
+ data=[
+ SimpleNamespace(index=index, embedding=[1.0, 0.0, 0.0])
+ for index, _ in enumerate(kwargs["input"])
+ ]
+ )
+ )
+ instance = AzureDocumentDBVectorSearchTool(
+ connection_string="mongodb://localhost",
+ database_name="test",
+ collection_name="documents",
+ dimensions=3,
+ )
+ yield instance
+ instance.close()
+
+
+def test_public_schema_and_default_configuration():
+ """Verify query validation and the default search result limit."""
+ assert AzureDocumentDBToolSchema(query="hello").query == "hello"
+ assert AzureDocumentDBVectorSearchConfig().limit == 4
+ with pytest.raises(ValidationError):
+ AzureDocumentDBVectorSearchConfig(limit=0)
+ with pytest.raises(ValidationError):
+ AzureDocumentDBToolSchema(query="")
+
+
+def test_tool_is_discoverable_without_instantiation():
+ """Verify public exports and tool metadata without opening connections."""
+ from crewai_tools import tools
+
+ assert tools.AzureDocumentDBVectorSearchTool is AzureDocumentDBVectorSearchTool
+ extractor = ToolSpecExtractor()
+ extractor.extract_tool_info(AzureDocumentDBVectorSearchTool)
+ (spec,) = extractor.tools_spec
+ assert spec["name"] == "AzureDocumentDBVectorSearchTool"
+ assert spec["package_dependencies"] == ["pymongo", "azure-identity"]
+ assert spec["run_params_schema"]["required"] == ["query"]
+ assert set(spec["init_params_schema"]["required"]) == {
+ "database_name",
+ "collection_name",
+ }
+
+
+def test_connection_from_environment_and_no_secret_in_serialization(monkeypatch):
+ """Verify environment configuration and connection-string redaction."""
+ uri = "mongodb://username:private-password@localhost"
+ monkeypatch.setenv("AZURE_DOCUMENTDB_CONNECTION_STRING", uri)
+ with patch("pymongo.MongoClient") as mongo:
+ instance = AzureDocumentDBVectorSearchTool(
+ database_name="db", collection_name="docs"
+ )
+ assert instance.connection_string == uri
+ assert "private-password" not in repr(instance)
+ assert "connection_string" not in instance.model_dump()
+ assert mongo.call_args.kwargs["serverSelectionTimeoutMS"] == 10000
+ instance.close()
+
+
+def test_missing_optional_dependency_has_actionable_error(monkeypatch):
+ """Verify a missing database driver produces installation guidance."""
+ original_import = builtins.__import__
+
+ def without_pymongo(name, *args, **kwargs):
+ """Simulate an unavailable PyMongo package without blocking other imports."""
+ if name == "pymongo":
+ raise ImportError("missing pymongo")
+ return original_import(name, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "__import__", without_pymongo)
+ with pytest.raises(ImportError, match="crewai-tools\\[azure-documentdb\\]"):
+ AzureDocumentDBVectorSearchTool(
+ connection_string="mongodb://localhost",
+ database_name="db",
+ collection_name="docs",
+ )
+
+
+def test_native_ivf_index(tool):
+ """Verify the index helper sends DocumentDB's native IVF definition."""
+ tool.create_vector_search_index(num_lists=10, similarity="IP")
+ tool._coll.database.command.assert_called_once_with(
+ {
+ "createIndexes": "documents",
+ "indexes": [
+ {
+ "name": "crewai_vector_index",
+ "key": {"embedding": "cosmosSearch"},
+ "cosmosSearchOptions": {
+ "kind": "vector-ivf",
+ "numLists": 10,
+ "dimensions": 3,
+ "similarity": "IP",
+ },
+ }
+ ],
+ }
+ )
+
+
[email protected]("kwargs", [{"num_lists": 0}, {"similarity": "cosine"}])
+def test_invalid_index_options_do_not_reach_database(tool, kwargs):
+ """Verify invalid index settings fail before database access."""
+ with pytest.raises(ValueError):
+ tool.create_vector_search_index(**kwargs)
+ tool._coll.database.command.assert_not_called()
+
+
+def test_ingest_generator_batches_preserves_ids_and_metadata(tool):
+ """Verify batched generator ingestion preserves IDs and nested metadata."""
+ metadata = [{"text": "cannot overwrite"}, {"category": "two"}, {}]
+ ids = tool.add_texts(
+ (text for text in ["one", "two", "three"]),
+ metadatas=metadata,
+ ids=["a", "b", "c"],
+ batch_size=2,
+ )
+ assert ids == ["a", "b", "c"]
+ calls = tool._coll.insert_many.call_args_list
+ assert [len(call.args[0]) for call in calls] == [2, 1]
+ assert calls[0].args[0][0] == {
+ "_id": "a",
+ "text": "one",
+ "metadata": {"text": "cannot overwrite"},
+ "embedding": [1.0, 0.0, 0.0],
+ }
+ assert calls[1].args[0][0]["_id"] == "c"
+ assert metadata[0] == {"text": "cannot overwrite"}
+ assert tool._openai_client.embeddings.create.call_args.kwargs == {
+ "input": ["three"],
+ "model": "text-embedding-3-small",
+ "dimensions": 3,
+ }
+
+
+def test_generated_ids_and_empty_input(tool):
+ """Verify generated IDs are unique and empty input performs no writes."""
+ ids = tool.add_texts(["one", "two"])
+ assert len(ids) == len(set(ids)) == 2
+ assert all(isinstance(value, str) for value in ids)
+ tool._coll.insert_many.reset_mock()
+ assert tool.add_texts(iter([])) == []
+ tool._coll.insert_many.assert_not_called()
+
+
+ "texts,kwargs",
+ [
+ (["one", "two"], {"metadatas": [{}]}),
+ (["one", "two"], {"ids": ["a"]}),
+ (["one", "two"], {"ids": ["a", "a"]}),
+ (["one"], {"ids": [""]}),
+ (["one"], {"batch_size": 0}),
+ ([" "], {}),
+ ([None], {}),
+ ],
+)
+def test_invalid_ingestion_has_no_side_effects(tool, texts, kwargs):
+ """Verify invalid documents and batch options fail before external calls."""
+ with pytest.raises(ValueError):
+ tool.add_texts(texts, **kwargs)
+ tool._coll.insert_many.assert_not_called()
+ assert tool._openai_client is None
+
+
+def test_query_uses_documentdb_not_atlas_and_returns_extended_json(tool):
+ """Verify native search stages and JSON serialization of BSON values."""
+ object_id = ObjectId()
+ tool._coll.aggregate.return_value = [
+ {
+ "_id": object_id,
+ "text": "one",
+ "metadata": {"at": datetime(2026, 1, 1, tzinfo=timezone.utc)},
+ "score": 1.0,
+ }
+ ]
+ results = json.loads(tool.run(query="one"))
+ assert results[0]["_id"] == {"$oid": str(object_id)}
+ assert "$date" in results[0]["metadata"]["at"]
+ assert results[0]["score"] == 1.0
+ tool._coll.aggregate.assert_called_once_with(
+ [
+ {
+ "$search": {
+ "cosmosSearch": {
+ "vector": [1.0, 0.0, 0.0],
+ "path": "embedding",
+ "k": 4,
+ },
+ "returnStoredSource": True,
+ }
+ },
+ {"$addFields": {"score": {"$meta": "searchScore"}}},
+ {"$project": {"embedding": 0}},
+ ]
+ )
+
+
+def test_query_options(tool):
+ """Verify filters, limits, and field options shape the search pipeline."""
+ tool.query_config = AzureDocumentDBVectorSearchConfig(
+ limit=2,
+ pre_filter={"metadata.category": "one"},
+ include_embeddings=True,
+ include_score=False,
+ )
+ tool._coll.aggregate.return_value = []
+ assert json.loads(tool._run("one")) == []
+ tool._coll.aggregate.assert_called_once_with(
+ [
+ {
+ "$search": {
+ "cosmosSearch": {
+ "vector": [1.0, 0.0, 0.0],
+ "path": "embedding",
+ "k": 2,
+ "filter": {"metadata.category": "one"},
+ },
+ "returnStoredSource": True,
+ }
+ }
+ ]
+ )
+
+
+def test_blank_query_is_rejected(tool):
+ """Verify whitespace-only queries never reach the database."""
+ with pytest.raises(ValueError, match="blank"):
+ tool._run(" ")
+ tool._coll.aggregate.assert_not_called()
+
+
+def test_database_errors_propagate(tool):
+ """Verify search, ingestion, and indexing errors reach the caller."""
+ tool._coll.aggregate.side_effect = OperationFailure("index missing")
+ with pytest.raises(OperationFailure, match="index missing"):
+ tool._run("one")
+ tool._coll.insert_many.side_effect = OperationFailure("write denied")
+ with pytest.raises(OperationFailure, match="write denied"):
+ tool.add_texts(["one"])
+ tool._coll.database.command.side_effect = OperationFailure("index denied")
+ with pytest.raises(OperationFailure, match="index denied"):
+ tool.create_vector_search_index()
+
+
+def test_missing_embedding_credentials(tool, monkeypatch):
+ """Verify missing embedding credentials fail before document insertion."""
+ monkeypatch.delenv("OPENAI_API_KEY")
+ with pytest.raises(ValueError, match="OPENAI_API_KEY"):
+ tool.add_texts(["one"])
+ tool._coll.insert_many.assert_not_called()
+
+
+def test_azure_openai_uses_deployment_and_dimensions(tool, monkeypatch):
+ """Verify Azure embeddings use the configured deployment and dimensions."""
+ monkeypatch.setenv("AZURE_OPENAI_ENDPOINT", "https://example.openai.azure.com")
+ tool.embedding_model = "my-embedding-deployment"
+ with patch.object(vector_search, "AzureOpenAI") as azure:
+ azure.return_value.embeddings.create.return_value = SimpleNamespace(
+ data=[SimpleNamespace(index=0, embedding=[1.0, 0.0, 0.0])]
+ )
+ tool.add_texts(["one"])
+ azure.assert_called_once_with()
+ azure.return_value.embeddings.create.assert_called_once_with(
+ input=["one"], model="my-embedding-deployment", dimensions=3
+ )
+
+
+ "vectors", [[], [[1.0]], [[float("nan"), 0, 0]], [[float("inf"), 0, 0]]]
+)
+def test_invalid_embedding_response_prevents_write(tool, vectors):
+ """Verify missing, malformed, or non-finite vectors prevent insertion."""
+ with patch.object(vector_search, "OpenAI") as openai:
+ openai.return_value.embeddings.create.return_value = SimpleNamespace(
+ data=[
+ SimpleNamespace(index=i, embedding=vector)
+ for i, vector in enumerate(vectors)
+ ]
+ )
+ with pytest.raises(ValueError, match="finite vector"):
+ tool.add_texts(["one"])
+ tool._coll.insert_many.assert_not_called()
+
+
+def test_embeddings_are_ordered_by_response_index(tool):
+ """Verify out-of-order embedding responses stay paired with their texts."""
+ with patch.object(vector_search, "OpenAI") as openai:
+ openai.return_value.embeddings.create.return_value = SimpleNamespace(
+ data=[
+ SimpleNamespace(index=1, embedding=[0.0, 1.0, 0.0]),
+ SimpleNamespace(index=0, embedding=[1.0, 0.0, 0.0]),
+ ]
+ )
+ tool.add_texts(["one", "two"])
+ docs = tool._coll.insert_many.call_args.args[0]
+ assert docs[0]["embedding"] == [1.0, 0.0, 0.0]
+ assert docs[1]["embedding"] == [0.0, 1.0, 0.0]
+
+
+def test_close_releases_both_clients(tool):
+ """Verify closing the tool releases database and embedding connections."""
+ tool.add_texts(["one"])
+ tool.close()
+ tool._client.close.assert_called_once()
+ tool._openai_client.close.assert_called_once()
+
+
+def test_oidc_connection_uses_injected_credential_and_refreshable_callback():
+ """Verify OIDC token renewal and caller ownership of injected credentials."""
+ from azure.core.credentials import AccessToken
+ from pymongo.auth_oidc import OIDCCallbackContext
+
+ credential = MagicMock()
+ credential.get_token.side_effect = [
+ AccessToken("first-token", 200),
+ AccessToken("refreshed-token", 300),
+ ]
+ with patch("pymongo.MongoClient") as mongo:
+ instance = AzureDocumentDBVectorSearchTool(
+ connection_string="mongodb://localhost/?authMechanism=MONGODB-OIDC",
+ database_name="db",
+ collection_name="docs",
+ azure_credential=credential,
+ )
+ callback = mongo.call_args.kwargs["authMechanismProperties"]["OIDC_CALLBACK"]
+ with patch(
+ "crewai_tools.tools.azure_documentdb_vector_search_tool.auth.time.time",
+ return_value=100,
+ ):
+ first = callback.fetch(
+ OIDCCallbackContext(timeout_seconds=30, username="", version=1)
+ )
+ refreshed = callback.fetch(
+ OIDCCallbackContext(timeout_seconds=30, username="", version=1)
+ )
+ assert first.access_token == "first-token"
+ assert first.expires_in_seconds == 100
+ assert refreshed.access_token == "refreshed-token"
+ assert refreshed.expires_in_seconds == 200
+ assert credential.get_token.call_count == 2
+ credential.get_token.assert_called_with(
+ "https://ossrdbms-aad.database.windows.net/.default"
+ )
+ instance.close()
+ credential.close.assert_not_called()
+
+
+def test_default_identity_is_closed_by_tool():
+ """Verify the tool closes credentials it creates for OIDC authentication."""
+ with (
+ patch("pymongo.MongoClient"),
+ patch("azure.identity.DefaultAzureCredential") as default_credential,
+ ):
+ instance = AzureDocumentDBVectorSearchTool(
+ connection_string="mongodb://localhost/?AUTHMECHANISM=MONGODB-OIDC",
+ database_name="db",
+ collection_name="docs",
+ )
+ default_credential.assert_called_once_with()
+ instance.close()
+ default_credential.return_value.close.assert_called_once()
+
+
+def test_entra_openai_uses_renewable_token_provider(tool, monkeypatch):
+ """Verify Azure OpenAI receives a renewable bearer-token provider."""
+ monkeypatch.setenv("AZURE_OPENAI_ENDPOINT", "https://example.openai.azure.com")
+ credential = MagicMock()
+ tool._azure_credential = credential
+ with (
+ patch("azure.identity.get_bearer_token_provider") as provider,
+ patch.object(vector_search, "AzureOpenAI") as azure,
+ ):
+ azure.return_value.embeddings.create.return_value = SimpleNamespace(
+ data=[SimpleNamespace(index=0, embedding=[1.0, 0.0, 0.0])]
+ )
+ tool.add_texts(["one"])
+ provider.assert_called_once_with(
+ credential, "https://cognitiveservices.azure.com/.default"
+ )
+ azure.assert_called_once_with(azure_ad_token_provider=provider.return_value)
+ tool.close()
+ credential.close.assert_not_called()
+
+
+def test_entra_embedding_requires_azure_endpoint(tool):
+ """Verify keyless Azure embeddings require an Azure OpenAI endpoint."""
+ tool.use_azure_identity = True
+ with pytest.raises(ValueError, match="AZURE_OPENAI_ENDPOINT"):
+ tool.add_texts(["one"])
+ tool._coll.insert_many.assert_not_called()
+
+
+def test_entra_embedding_without_oidc_database_uses_default_credential(
+ tool, monkeypatch
+):
+ """Verify keyless embeddings work independently of database authentication."""
+ monkeypatch.setenv("AZURE_OPENAI_ENDPOINT", "https://example.openai.azure.com")
+ tool.use_azure_identity = True
+ with (
+ patch("azure.identity.DefaultAzureCredential") as credential,
+ patch("azure.identity.get_bearer_token_provider"),
+ patch.object(vector_search, "AzureOpenAI") as azure,
+ ):
+ azure.return_value.embeddings.create.return_value = SimpleNamespace(
+ data=[SimpleNamespace(index=0, embedding=[1.0, 0.0, 0.0])]
+ )
+ tool.add_texts(["one"])
+ credential.assert_called_once_with()
+ tool.close()
+ credential.return_value.close.assert_called_once()
+
+
+def test_oidc_token_acquisition_failure_is_not_hidden():
+ """Verify OIDC credential failures propagate without authentication fallback."""
+ from azure.core.exceptions import ClientAuthenticationError
+ from crewai_tools.tools.azure_documentdb_vector_search_tool.auth import (
+ DocumentDBOIDCCallback,
+ )
+ from pymongo.auth_oidc import OIDCCallbackContext
+
+ credential = MagicMock()
+ credential.get_token.side_effect = ClientAuthenticationError("access denied")
+ with pytest.raises(ClientAuthenticationError, match="access denied"):
+ DocumentDBOIDCCallback(credential).fetch(
+ OIDCCallbackContext(timeout_seconds=30, username="", version=1)
+ )
diff --git a/lib/crewai-tools/tool.specs.json b/lib/crewai-tools/tool.specs.json
index 8794f5675..e3094ee5d 100644
--- a/lib/crewai-tools/tool.specs.json
+++ b/lib/crewai-tools/tool.specs.json
@@ -218,6 +218,205 @@
"type": "object"
}
},
+ {
+ "description": "Search Azure DocumentDB for documents relevant to a natural language query.",
+ "env_vars": [
+ {
+ "default": null,
+ "description": "Connection string, unless passed to the constructor.",
+ "name": "AZURE_DOCUMENTDB_CONNECTION_STRING",
+ "required": false
+ },
+ {
+ "default": null,
+ "description": "OpenAI key (not required when using Azure OpenAI).",
+ "name": "OPENAI_API_KEY",
+ "required": false
+ },
+ {
+ "default": null,
+ "description": "Set to use Azure OpenAI for embeddings.",
+ "name": "AZURE_OPENAI_ENDPOINT",
+ "required": false
+ },
+ {
+ "default": null,
+ "description": "Azure OpenAI key when using Azure OpenAI.",
+ "name": "AZURE_OPENAI_API_KEY",
+ "required": false
+ },
+ {
+ "default": null,
+ "description": "Azure OpenAI API version when using Azure OpenAI.",
+ "name": "OPENAI_API_VERSION",
+ "required": false
+ }
+ ],
+ "humanized_name": "AzureDocumentDBVectorSearchTool",
+ "init_params_schema": {
+ "$defs": {
+ "AzureDocumentDBVectorSearchConfig": {
+ "description": "Options for Azure DocumentDB's native vector search.",
+ "properties": {
+ "include_embeddings": {
+ "default": false,
+ "description": "Return stored embedding vectors.",
+ "title": "Include Embeddings",
+ "type": "boolean"
+ },
+ "include_score": {
+ "default": true,
+ "description": "Return similarity scores.",
+ "title": "Include Score",
+ "type": "boolean"
+ },
+ "limit": {
+ "default": 4,
+ "description": "Maximum number of results.",
+ "minimum": 1,
+ "title": "Limit",
+ "type": "integer"
+ },
+ "pre_filter": {
+ "anyOf": [
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "DocumentDB filter applied during search, e.g. metadata.category.",
+ "title": "Pre Filter"
+ }
+ },
+ "title": "AzureDocumentDBVectorSearchConfig",
+ "type": "object"
+ },
+ "EnvVar": {
+ "properties": {
+ "default": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Default"
+ },
+ "description": {
+ "title": "Description",
+ "type": "string"
+ },
+ "name": {
+ "title": "Name",
+ "type": "string"
+ },
+ "required": {
+ "default": true,
+ "title": "Required",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "name",
+ "description"
+ ],
+ "title": "EnvVar",
+ "type": "object"
+ },
+ "ToolFailurePolicy": {
+ "description": "How an agent reacts when one of its tools reports a failure.",
+ "enum": [
+ "ignore",
+ "warn",
+ "raise"
+ ],
+ "title": "ToolFailurePolicy",
+ "type": "string"
+ }
+ },
+ "description": "Retrieve documents using Azure DocumentDB, not MongoDB Atlas vector search.\n\nDocuments contain ``text``, ``metadata`` and ``embedding`` fields. Embeddings\nuse OpenAI, or Azure OpenAI when AZURE_OPENAI_ENDPOINT is configured.",
+ "properties": {
+ "collection_name": {
+ "minLength": 1,
+ "title": "Collection Name",
+ "type": "string"
+ },
+ "connection_timeout_ms": {
+ "default": 10000,
+ "minimum": 1,
+ "title": "Connection Timeout Ms",
+ "type": "integer"
+ },
+ "database_name": {
+ "minLength": 1,
+ "title": "Database Name",
+ "type": "string"
+ },
+ "dimensions": {
+ "default": 1536,
+ "minimum": 1,
+ "title": "Dimensions",
+ "type": "integer"
+ },
+ "embedding_model": {
+ "default": "text-embedding-3-small",
+ "description": "OpenAI embedding model or Azure OpenAI deployment name.",
+ "minLength": 1,
+ "title": "Embedding Model",
+ "type": "string"
+ },
+ "query_config": {
+ "$ref": "#/$defs/AzureDocumentDBVectorSearchConfig"
+ },
+ "use_azure_identity": {
+ "default": false,
+ "description": "Use renewable Entra tokens for Azure OpenAI instead of an API key.",
+ "title": "Use Azure Identity",
+ "type": "boolean"
+ },
+ "vector_index_name": {
+ "default": "crewai_vector_index",
+ "minLength": 1,
+ "title": "Vector Index Name",
+ "type": "string"
+ }
+ },
+ "required": [
+ "database_name",
+ "collection_name"
+ ],
+ "title": "AzureDocumentDBVectorSearchTool",
+ "type": "object"
+ },
+ "name": "AzureDocumentDBVectorSearchTool",
+ "package_dependencies": [
+ "pymongo",
+ "azure-identity"
+ ],
+ "run_params_schema": {
+ "description": "Input accepted by the Azure DocumentDB vector search tool.",
+ "properties": {
+ "query": {
+ "description": "Text to find relevant documents for.",
+ "minLength": 1,
+ "title": "Query",
+ "type": "string"
+ }
+ },
+ "required": [
+ "query"
+ ],
+ "title": "AzureDocumentDBToolSchema",
+ "type": "object"
+ }
+ },
{
"description": "A tool that performs image searches using the Brave Search API. Results are returned as structured JSON data.",
"env_vars": [
diff --git a/uv.lock b/uv.lock
index 0006265fb..bbfc084fb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1737,6 +1737,10 @@ dependencies = [
apify = [
{ name = "langchain-apify" },
]
+azure-documentdb = [
+ { name = "azure-identity" },
+ { name = "pymongo" },
+]
beautifulsoup4 = [
{ name = "beautifulsoup4", version = "4.13.5", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
{ name = "beautifulsoup4", version = "4.15.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
@@ -1898,6 +1902,8 @@ requires-dist = [
{ name = "playwright", marker = "extra == 'bedrock'", specifier = ">=1.52.0" },
{ name = "psycopg2-binary", marker = "extra == 'postgresql'", specifier = ">=2.9.10" },
{ name = "pygithub", marker = "extra == 'github'", specifier = "==1.59.1" },
+ { name = "azure-identity", marker = "extra == 'azure-documentdb'", specifier = ">=1.17.0,<2" },
+ { name = "pymongo", marker = "extra == 'azure-documentdb'", specifier = ">=4.18.2" },
{ name = "pymongo", marker = "extra == 'mongodb'", specifier = ">=4.18.2" },
{ name = "pymupdf", specifier = "~=1.26.6" },
{ name = "pymysql", marker = "extra == 'mysql'", specifier = ">=1.1.1" },
@@ -1924,7 +1930,7 @@ requires-dist = [
{ name = "weaviate-client", marker = "extra == 'weaviate-client'", specifier = ">=4.10.2" },
{ name = "youtube-transcript-api", specifier = "~=1.2.2" },
]
-provides-extras = ["apify", "beautifulsoup4", "bedrock", "browserbase", "composio-core", "contextual", "couchbase", "databricks-sdk", "daytona", "e2b", "exa-py", "firecrawl-py", "github", "hyperbrowser", "linkup-sdk", "mcp", "mongodb", "multion", "mysql", "oracledb", "oxylabs", "patronus", "postgresql", "qdrant-client", "rag", "scrapegraph-py", "scrapfly-sdk", "selenium", "serpapi", "singlestore", "snowflake", "spider-client", "sqlalchemy", "stagehand", "tavily-python", "weaviate-client", "xml"]
+provides-extras = ["apify", "azure-documentdb", "beautifulsoup4", "bedrock", "browserbase", "composio-core", "contextual", "couchbase", "databricks-sdk", "daytona", "e2b", "exa-py", "firecrawl-py", "github", "hyperbrowser", "linkup-sdk", "mcp", "mongodb", "multion", "mysql", "oracledb", "oxylabs", "patronus", "postgresql", "qdrant-client", "rag", "scrapegraph-py", "scrapfly-sdk", "selenium", "serpapi", "singlestore", "snowflake", "spider-client", "sqlalchemy", "stagehand", "tavily-python", "weaviate-client", "xml"]
[[package]]
name = "cryptography"