Python: Add Azure Cosmos DB NoSQL vector store connector

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Azure Cosmos DB for NoSQL provides native vector indexing and VectorDistance queries, but Agent Framework does not yet expose it through the shared Python vector-store abstractions. This adds the Cosmos DB for NoSQL portion of the Phase 6 connector roadmap so applications can keep vectors and JSON records together while using Agent Framework's common CRUD, filtering, and search APIs.

This contribution is intentionally limited to Azure Cosmos DB for NoSQL. It does not add Azure DocumentDB, Cosmos DB for MongoDB, MongoDB query dialects, server-side embedding, full-text search, or hybrid search.

Description & Review Guide

• What are the major changes? Extends the existing beta agent-framework-azure-cosmos package with CosmosCollection, CosmosStore, and AzureCosmosSettings; adds lazy agent_framework.azure exports; derives immutable container vector/index policies from vector-store definitions; and implements batch CRUD, portable filter translation, and native vector search. Records require an application-provided string key stored as id, with the container partitioned by /id, so key get/delete operations remain unambiguous point operations. Supported vector element types are float32, int8, and uint8, with flat, quantizedFlat, and DiskANN indexes and cosine, dot-product, and Euclidean metrics. Float16 is rejected before service I/O, and Euclidean search is supported without score thresholds because direct VectorDistance predicates do not reliably enforce Euclidean cutoffs.
• What is the impact of these changes? Cosmos DB for NoSQL users gain parameterized server-side filters and vector queries, bounded paging, raw provider score semantics, request-charge/activity metadata, strict item/key/vector preflight, semantic validation of existing container policies, and explicit client/database/container ownership behavior. Existing history-provider and checkpoint-storage APIs and lifecycle behavior are preserved. The package documentation, typing marker, dependency floor, unit coverage, credential-gated integration coverage, and Azure namespace tests are updated. Managed validation used RBAC-only Azure authentication against a disposable database and containers in a vector-enabled serverless account; all disposable resources and the temporary account-scoped role assignment were removed afterward.
• What do you want reviewers to focus on? Please focus on the /id partition-key contract, immutable policy reconciliation, JSON/filter semantic preservation, SQL identifier/value safety, cross-partition partial-write behavior, client ownership, and the fail-fast float16 and Euclidean-threshold boundaries.

Related Issue

Related to #4168 and #1188.

This is the Azure Cosmos DB for NoSQL-only partial contribution. It intentionally does not close either umbrella issue because the remaining Phase 6 connectors, including the separate Mongo-compatible surfaces, are still outstanding. No open pull request uses this head branch.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above). This remains unchecked because Python: Phase 6: Vector Store Connectors — Tier 2 (MongoDB, Cosmos DB, Pinecone, Chroma, Weaviate) #4168 and Python SDK : Add native vector database connectors and retrieval patterns #1188 are shared umbrella issues that this NoSQL-only partial contribution intentionally does not close.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Dependency compatibility, identifier validation, policy normalization, service limits, and vector paging need correction.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds the Azure Cosmos DB for NoSQL vector-store connector as part of the Phase 6 roadmap.

Changes:

• Implements vector CRUD, filtering, search, policy validation, and lifecycle management.
• Exposes Cosmos vector APIs through the Azure namespace.
• Adds documentation plus unit and integration coverage.

File summaries

File	Description
python/uv.lock	Updates the Cosmos SDK dependency.
python/packages/core/tests/core/test_azure_namespace.py	Tests lazy Cosmos exports.
python/packages/core/agent_framework/azure/__init__.pyi	Types the new exports.
python/packages/core/agent_framework/azure/__init__.py	Adds lazy namespace mappings.
python/packages/azure-cosmos/tests/azure_cosmos/test_vector_store.py	Adds comprehensive unit tests.
python/packages/azure-cosmos/tests/azure_cosmos/test_vector_store_integration.py	Adds live-service coverage.
python/packages/azure-cosmos/README.md	Documents connector usage and constraints.
python/packages/azure-cosmos/pyproject.toml	Updates metadata and dependencies.
python/packages/azure-cosmos/AGENTS.md	Documents package capabilities.
python/packages/azure-cosmos/agent_framework_azure_cosmos/py.typed	Marks the package as typed.
python/packages/azure-cosmos/agent_framework_azure_cosmos/_vector_store.py	Implements the connector.
python/packages/azure-cosmos/agent_framework_azure_cosmos/__init__.py	Exports the public APIs.
python/AGENTS.md	Updates the package catalog.

Review details

Suppressed comments (1)

python/packages/azure-cosmos/agent_framework_azure_cosmos/_vector_store.py:383

• This accepts values 10–24, but the current Cosmos container schema requires indexingSearchListSize to be at least 25. These values therefore fail only when the service creates the DiskANN container instead of failing fast.

        if type(indexing_list_size) is not int or not 10 <= indexing_list_size <= 500:
            raise ValueError("indexing_search_list_size must be an integer between 10 and 500.")

• Files reviewed: 11/13 changed files
• Comments generated: 6
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 60dba97cb472
Model: gpt-5.6-sol-fast

Overview

The review found 3 verified inline finding(s).

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (2 high, 1 medium) across 2 files. Details are attached to the affected lines below.

Affected areas: python/packages/azure-cosmos/agent_framework_azure_cosmos/__init__.py, python/packages/azure-cosmos/agent_framework_azure_cosmos/_vector_store.py

[Eduard van Valkenburg (eavanvalkenburg)]

Addressed the suppressed vector-index limit finding in 786f4a282: indexing_search_list_size now validates the current service range 25..500 before I/O. The same change aligns quantization_byte_size with 4..min(512, dimensions) and adds accepted/rejected boundary coverage.