Python: Add Azure Cosmos history provider package (#4271)

* Created cosmos history provider * add marker * Python: address Cosmos PR feedback - address provider/test/sample review feedback and cleanup typing - add cosmos integration test coverage and skip gating - add dedicated cosmos emulator jobs to python merge/integration workflows - switch cosmos workflow execution to package poe integration-tests task Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: handle empty Cosmos session id - replace default partition fallback for empty session_id - log warning and generate GUID when session_id is empty - update unit tests to validate GUID fallback behavior Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix sample * fix cross partition query --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-03-03 12:29:32 +00:00
parent 945933c351
commit c37f74f898
14 changed files with 1616 additions and 445 deletions
@@ -0,0 +1,20 @@
+# Azure Cosmos DB Package Samples
+
+This folder contains samples for `agent-framework-azure-cosmos`.
+
+| File | Description |
+| --- | --- |
+| [`cosmos_history_provider.py`](cosmos_history_provider.py) | Demonstrates an Agent using `CosmosHistoryProvider` with `AzureOpenAIResponsesClient` (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
+```
@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Samples for the Azure Cosmos history provider package."""
@@ -0,0 +1,100 @@
+# Copyright (c) Microsoft. All rights reserved.
+# ruff: noqa: T201
+
+import asyncio
+import os
+
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework_azure_cosmos import CosmosHistoryProvider
+from azure.identity.aio import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file.
+load_dotenv()
+
+"""
+This sample demonstrates CosmosHistoryProvider as an agent context provider.
+
+Key components:
+- AzureOpenAIResponsesClient configured with an Azure AI project endpoint
+- CosmosHistoryProvider configured for Cosmos DB-backed message history
+- Provider-configured container name with session_id as partition key
+
+Environment variables:
+  AZURE_AI_PROJECT_ENDPOINT
+  AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME
+  AZURE_COSMOS_ENDPOINT
+  AZURE_COSMOS_DATABASE_NAME
+  AZURE_COSMOS_CONTAINER_NAME
+Optional:
+  AZURE_COSMOS_KEY
+"""
+
+
+
+async def main() -> None:
+    """Run the Cosmos history provider sample with an Agent."""
+    project_endpoint = os.getenv("AZURE_AI_PROJECT_ENDPOINT")
+    deployment_name = os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")
+    cosmos_endpoint = os.getenv("AZURE_COSMOS_ENDPOINT")
+    cosmos_database_name = os.getenv("AZURE_COSMOS_DATABASE_NAME")
+    cosmos_container_name = os.getenv("AZURE_COSMOS_CONTAINER_NAME")
+    cosmos_key = os.getenv("AZURE_COSMOS_KEY")
+
+    if (
+        not project_endpoint
+        or not deployment_name
+        or not cosmos_endpoint
+        or not cosmos_database_name
+        or not cosmos_container_name
+    ):
+        print(
+            "Please set AZURE_AI_PROJECT_ENDPOINT, AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME, "
+            "AZURE_COSMOS_ENDPOINT, AZURE_COSMOS_DATABASE_NAME, and AZURE_COSMOS_CONTAINER_NAME."
+        )
+        return
+
+    # 1. Create an Azure credential and Responses client using project endpoint auth.
+    async with AzureCliCredential() as credential:
+        client = AzureOpenAIResponsesClient(
+            project_endpoint=project_endpoint,
+            deployment_name=deployment_name,
+            credential=credential,
+        )
+
+        # 2. Create an agent that uses the history provider as a context provider.
+        async with (
+            CosmosHistoryProvider(
+                endpoint=cosmos_endpoint,
+                database_name=cosmos_database_name,
+                container_name=cosmos_container_name,
+                credential=cosmos_key or credential,
+            ) as history_provider,
+            client.as_agent(
+                name="CosmosHistoryAgent",
+                instructions="You are a helpful assistant that remembers prior turns.",
+                context_providers=[history_provider],
+                default_options={"store": False},
+            ) as agent,
+        ):
+            # 3. Create a session (session_id is used as the partition key).
+            session = agent.create_session()
+
+            # 4. Run a multi-turn conversation; history is persisted by CosmosHistoryProvider.
+            response1 = await agent.run("My name is Ada and I enjoy distributed systems.", session=session)
+            print(f"Assistant: {response1.text}")
+
+            response2 = await agent.run("What do you remember about me?", session=session)
+            print(f"Assistant: {response2.text}")
+            print(f"Container: {history_provider.container_name}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+Assistant: Nice to meet you, Ada! Distributed systems are a fascinating area.
+Assistant: You told me your name is Ada and that you enjoy distributed systems.
+Container: <AZURE_COSMOS_CONTAINER_NAME>
+"""