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.mdindex 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.tomlindex 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, anddiff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.pyindex 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 S3WriterToolfrom crewai_tools.tools.ai_mind_tool.ai_mind_tool import AIMindToolfrom crewai_tools.tools.apify_actors_tool.apify_actors_tool import ApifyActorsToolfrom 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 BraveImageSearchToolfrom 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__.pyindex 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 AIMindToolfrom crewai_tools.tools.apify_actors_tool.apify_actors_tool import ApifyActorsToolfrom 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 BraveImageSearchToolfrom 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.mdnew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.jsonindex 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.lockindex 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"