Python: Add Azure Cosmos history provider package

python/packages/azure-ai-search/tests/test_aisearch_context_provider.py

@@ -1297,7 +1297,6 @@ def test_text_only_messages(self) -> None:
         assert result[0].content[0].text == "hello"
 
     def test_image_uri_content(self) -> None:
-        from agent_framework import Content
 
         img = Content.from_uri(uri="https://example.com/photo.png", media_type="image/png")
         messages = [Message(role="user", contents=[img])]
@@ -1309,7 +1308,6 @@ def test_image_uri_content(self) -> None:
         assert result[0].content[0].image.url == "https://example.com/photo.png"
 
     def test_mixed_text_and_image_content(self) -> None:
-        from agent_framework import Content
 
         text = Content.from_text("describe this image")
         img = Content.from_uri(uri="https://example.com/img.jpg", media_type="image/jpeg")
@@ -1319,15 +1317,13 @@ def test_mixed_text_and_image_content(self) -> None:
         assert len(result[0].content) == 2
 
     def test_skips_non_text_non_image_content(self) -> None:
-        from agent_framework import Content
 
         error = Content.from_error(message="oops")
         messages = [Message(role="user", contents=[error])]
         result = AzureAISearchContextProvider._prepare_messages_for_kb_search(messages)
         assert len(result) == 0  # message had no usable content
 
     def test_skips_empty_text(self) -> None:
-        from agent_framework import Content
 
         empty = Content.from_text("")
         messages = [Message(role="user", contents=[empty])]
@@ -1341,7 +1337,6 @@ def test_fallback_to_msg_text_when_no_contents(self) -> None:
         assert result[0].content[0].text == "fallback text"
 
     def test_data_uri_image(self) -> None:
-        from agent_framework import Content
 
         img = Content.from_data(data=b"\x89PNG", media_type="image/png")
         messages = [Message(role="user", contents=[img])]
@@ -1352,7 +1347,6 @@ def test_data_uri_image(self) -> None:
         assert isinstance(result[0].content[0], KnowledgeBaseMessageImageContent)
 
     def test_non_image_uri_skipped(self) -> None:
-        from agent_framework import Content
 
         pdf = Content.from_uri(uri="https://example.com/doc.pdf", media_type="application/pdf")
         messages = [Message(role="user", contents=[pdf])]
@@ -1568,9 +1562,7 @@ def test_references_become_annotations(self) -> None:
                 KnowledgeBaseMessage(role="assistant", content=[KnowledgeBaseMessageTextContent(text="answer")]),
             ],
             references=[
-                KnowledgeBaseWebReference(
-                    id="ref-1", activity_source=0, url="https://example.com", title="Example"
-                ),
+                KnowledgeBaseWebReference(id="ref-1", activity_source=0, url="https://example.com", title="Example"),
             ],
         )
         result = AzureAISearchContextProvider._parse_messages_from_kb_response(response)

python/packages/azure-cosmos/AGENTS.md

@@ -0,0 +1,28 @@
+# Azure Cosmos DB Package (agent-framework-azure-cosmos)
+
+Azure Cosmos DB history provider integration for Agent Framework.
+
+## Main Classes
+
+- **`CosmosHistoryProvider`** - Persistent conversation history storage backed by Azure Cosmos DB
+
+## Usage
+
+```python
+from agent_framework_azure_cosmos import CosmosHistoryProvider
+
+provider = CosmosHistoryProvider(
+    endpoint="https://<account>.documents.azure.com:443/",
+    credential="<key-or-token-credential>",
+    database_name="agent-framework",
+    container_name="chat-history",
+)
+```
+
+Container name is configured on the provider. `session_id` is used as the partition key.
+
+## Import Path
+
+```python
+from agent_framework_azure_cosmos import CosmosHistoryProvider
+```

python/packages/azure-cosmos/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/azure-cosmos/README.md

@@ -0,0 +1,38 @@
+# Get Started with Microsoft Agent Framework Azure Cosmos DB
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-azure-cosmos --pre
+```
+
+## Azure Cosmos DB History Provider
+
+The Azure Cosmos DB integration provides `CosmosHistoryProvider` for persistent conversation history storage.
+
+### Basic Usage Example
+
+```python
+from azure.identity.aio import DefaultAzureCredential
+from agent_framework_azure_cosmos import CosmosHistoryProvider
+
+provider = CosmosHistoryProvider(
+    endpoint="https://<account>.documents.azure.com:443/",
+    credential=DefaultAzureCredential(),
+    database_name="agent-framework",
+    container_name="chat-history",
+)
+```
+
+Credentials follow the same pattern used by other Azure connectors in the repository:
+
+- Pass a credential object (for example `DefaultAzureCredential`)
+- Or pass a key string directly
+- Or set `AZURE_COSMOS_KEY` in the environment
+
+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.

python/packages/azure-cosmos/agent_framework_azure_cosmos/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._history_provider import CosmosHistoryProvider
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "CosmosHistoryProvider",
+    "__version__",
+]