Python: Integrate azure-cosmos into core, lazy loading, and root samples

python/packages/azure-cosmos/AGENTS.md

@@ -21,7 +21,17 @@ provider = CosmosHistoryProvider(
 
 Container name is configured on the provider. `session_id` is used as the partition key.
 
-## Import Path
+## Import Paths
+
+Lazy-loading namespace (recommended):
+
+```python
+from agent_framework.azure_cosmos import CosmosHistoryProvider
+```
+
+Also available via the Azure umbrella namespace (`from agent_framework.azure import CosmosHistoryProvider`).
+
+Direct package import:
 
 ```python
 from agent_framework_azure_cosmos import CosmosHistoryProvider

python/packages/azure-cosmos/README.md

@@ -35,4 +35,4 @@ Container naming behavior:
 - Container name is configured on the provider (`container_name` or `AZURE_COSMOS_CONTAINER_NAME`)
 - `session_id` is used as the Cosmos partition key for reads/writes
 
-See `samples/cosmos_history_provider.py` for a runnable package-local example.
+See [`samples/02-agents/context_providers/azure_cosmos/`](../../samples/02-agents/context_providers/azure_cosmos/) for runnable examples.

python/packages/azure-cosmos/samples/README.md

@@ -1,20 +1,5 @@
 # Azure Cosmos DB Package Samples
 
-This folder contains samples for `agent-framework-azure-cosmos`.
+Samples for `agent-framework-azure-cosmos` have moved to the root samples directory:
 
-| File | Description |
-| --- | --- |
-| [`cosmos_history_provider.py`](cosmos_history_provider.py) | Demonstrates an Agent using `CosmosHistoryProvider` with `FoundryChatClient` (configured against an Azure AI Foundry project endpoint), provider-configured container name, and `session_id` partitioning. |
-
-## Prerequisites
-
-- `AZURE_COSMOS_ENDPOINT`
-- `AZURE_COSMOS_DATABASE_NAME`
-- `AZURE_COSMOS_CONTAINER_NAME`
-- `AZURE_COSMOS_KEY` (or equivalent credential flow)
-
-## Run
-
-```bash
-uv run --directory packages/azure-cosmos python samples/cosmos_history_provider.py
-```
+[`samples/02-agents/context_providers/azure_cosmos/`](../../../samples/02-agents/context_providers/azure_cosmos/)

python/packages/core/agent_framework/azure/__init__.py

@@ -14,6 +14,7 @@
     "AgentResponseCallbackProtocol": ("agent_framework_durabletask", "agent-framework-durabletask"),
     "AzureAISearchContextProvider": ("agent_framework_azure_ai_search", "agent-framework-azure-ai-search"),
     "AzureAISearchSettings": ("agent_framework_azure_ai_search", "agent-framework-azure-ai-search"),
+    "CosmosHistoryProvider": ("agent_framework_azure_cosmos", "agent-framework-azure-cosmos"),
     "AzureAISettings": ("agent_framework_azure_ai", "agent-framework-azure-ai"),
     "AzureAIInferenceEmbeddingClient": ("agent_framework_azure_ai", "agent-framework-azure-ai"),
     "AzureAIInferenceEmbeddingOptions": ("agent_framework_azure_ai", "agent-framework-azure-ai"),

python/packages/core/agent_framework/azure_cosmos/__init__.py

@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Azure Cosmos DB integration namespace for optional Agent Framework connectors.
+
+This module lazily re-exports objects from:
+- ``agent-framework-azure-cosmos``
+
+Supported classes:
+- CosmosHistoryProvider
+"""
+
+import importlib
+from typing import Any
+
+IMPORT_PATH = "agent_framework_azure_cosmos"
+PACKAGE_NAME = "agent-framework-azure-cosmos"
+_IMPORTS = ["CosmosHistoryProvider"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _IMPORTS:
+        try:
+            return getattr(importlib.import_module(IMPORT_PATH), name)
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                f"The '{PACKAGE_NAME}' package is not installed, please do `pip install {PACKAGE_NAME}`"
+            ) from exc
+    raise AttributeError(f"Module {IMPORT_PATH} has no attribute {name}.")
+
+
+def __dir__() -> list[str]:
+    return _IMPORTS

python/packages/core/pyproject.toml

@@ -31,17 +31,16 @@ dependencies = [
 
 [project.optional-dependencies]
 all = [
-    "mcp>=1.24.0,<2",
     "agent-framework-a2a",
     "agent-framework-ag-ui",
-    "agent-framework-azure-ai-search",
     "agent-framework-anthropic",
-    "agent-framework-openai",
-    "agent-framework-claude",
     "agent-framework-azure-ai",
+    "agent-framework-azure-ai-search",
+    "agent-framework-azure-cosmos",
     "agent-framework-azurefunctions",
     "agent-framework-bedrock",
     "agent-framework-chatkit",
+    "agent-framework-claude",
     "agent-framework-copilotstudio",
     "agent-framework-declarative",
     "agent-framework-devui",
@@ -52,9 +51,11 @@ all = [
     "agent-framework-lab",
     "agent-framework-mem0",
     "agent-framework-ollama",
+    "agent-framework-openai",
     "agent-framework-orchestrations",
     "agent-framework-purview",
     "agent-framework-redis",
+    "mcp>=1.24.0,<2",
 ]
 
 [tool.uv]

python/samples/02-agents/context_providers/azure_cosmos/README.md

@@ -0,0 +1,50 @@
+# Azure Cosmos DB Context Provider Examples
+
+The Azure Cosmos DB context provider enables persistent conversation history for your agents using Azure Cosmos DB. It uses `session_id` as the partition key for efficient multi-session support.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`cosmos_history_provider.py`](cosmos_history_provider.py) | Demonstrates an Agent using `CosmosHistoryProvider` with `FoundryChatClient` (configured against an Azure AI Foundry project endpoint), provider-configured container name, and `session_id` partitioning. |
+
+## Prerequisites
+
+### Required resources
+
+1. An Azure Cosmos DB account with a database and container
+2. Python environment with Agent Framework Azure Cosmos extra installed
+3. Azure AI Foundry project endpoint and model deployment
+
+### Install the package
+
+```bash
+pip install "agent-framework-azure-cosmos"
+```
+
+### Environment variables
+
+- `FOUNDRY_PROJECT_ENDPOINT` (required): Azure AI Foundry project endpoint
+- `FOUNDRY_MODEL` (required): Foundry model deployment name
+- `AZURE_COSMOS_ENDPOINT` (required): Azure Cosmos DB endpoint
+- `AZURE_COSMOS_DATABASE_NAME` (required): Cosmos DB database name
+- `AZURE_COSMOS_CONTAINER_NAME` (required): Cosmos DB container name
+- `AZURE_COSMOS_KEY` (optional): Cosmos DB key (falls back to Azure CLI credential)
+
+## How to run
+
+1. Set the required environment variables:
+
+```bash
+export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
+export FOUNDRY_MODEL="<deployment-name>"
+export AZURE_COSMOS_ENDPOINT="https://<account>.documents.azure.com:443/"
+export AZURE_COSMOS_DATABASE_NAME="<database>"
+export AZURE_COSMOS_CONTAINER_NAME="<container>"
+```
+
+2. Run the example:
+
+```bash
+uv run python samples/02-agents/context_providers/azure_cosmos/cosmos_history_provider.py
+```

python/packages/azure-cosmos/samples/cosmos_history_provider.py → python/samples/02-agents/context_providers/azure_cosmos/cosmos_history_provider.py

@@ -4,12 +4,11 @@
 import asyncio
 import os
 
+from agent_framework.azure_cosmos import CosmosHistoryProvider
 from agent_framework.foundry import FoundryChatClient
 from azure.identity.aio import AzureCliCredential
 from dotenv import load_dotenv
 
-from agent_framework_azure_cosmos import CosmosHistoryProvider
-
 # Load environment variables from .env file.
 load_dotenv()