diff --git a/python/packages/azure-cosmos/AGENTS.md b/python/packages/azure-cosmos/AGENTS.md index 7cb0c2c717..440750872f 100644 --- a/python/packages/azure-cosmos/AGENTS.md +++ b/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 diff --git a/python/packages/azure-cosmos/README.md b/python/packages/azure-cosmos/README.md index 198376bcbb..a4072adcee 100644 --- a/python/packages/azure-cosmos/README.md +++ b/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. diff --git a/python/packages/azure-cosmos/samples/README.md b/python/packages/azure-cosmos/samples/README.md index e3714139e4..ff72e59d1a 100644 --- a/python/packages/azure-cosmos/samples/README.md +++ b/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/) diff --git a/python/packages/core/agent_framework/azure/__init__.py b/python/packages/core/agent_framework/azure/__init__.py index 27a9dc7e3a..3cce4d2153 100644 --- a/python/packages/core/agent_framework/azure/__init__.py +++ b/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"), diff --git a/python/packages/core/agent_framework/azure_cosmos/__init__.py b/python/packages/core/agent_framework/azure_cosmos/__init__.py new file mode 100644 index 0000000000..dd35365057 --- /dev/null +++ b/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 diff --git a/python/packages/core/pyproject.toml b/python/packages/core/pyproject.toml index f002567381..7060aa208f 100644 --- a/python/packages/core/pyproject.toml +++ b/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] diff --git a/python/packages/devui/samples/README.md b/python/packages/devui/samples/README.md deleted file mode 100644 index d4ad6f6b83..0000000000 --- a/python/packages/devui/samples/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# DevUI Samples - Moved - -**The DevUI samples have been relocated to the main samples folder for better consistency and discoverability.** - -## New Location - -All DevUI samples are now located at: - -``` -python/samples/02-agents/devui/ -``` - -## Available Samples - -- **weather_agent** - Basic OpenAI weather agent -- **weather_agent_azure** - Azure OpenAI weather agent -- **foundry_agent** - Azure AI Foundry weather agent -- **spam_workflow** - Email spam detection workflow -- **fanout_workflow** - Complex fan-in/fan-out data processing workflow -- **in_memory_mode.py** - In-memory entity registration example - -## Quick Start - -```bash -cd ../../samples/02-agents/devui -python in_memory_mode.py -``` - -Or for directory discovery: - -```bash -cd ../../samples/02-agents/devui -devui -``` - -## Learn More - -See the [DevUI samples README](../../../samples/02-agents/devui/README.md) for detailed documentation. diff --git a/python/packages/devui/samples/__init__.py b/python/packages/devui/samples/__init__.py deleted file mode 100644 index 50801e55c7..0000000000 --- a/python/packages/devui/samples/__init__.py +++ /dev/null @@ -1,3 +0,0 @@ -# Copyright (c) Microsoft. All rights reserved. - -"""Examples package for Agent Framework DevUI.""" diff --git a/python/samples/02-agents/context_providers/azure_cosmos/README.md b/python/samples/02-agents/context_providers/azure_cosmos/README.md new file mode 100644 index 0000000000..f31d5603f7 --- /dev/null +++ b/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://.services.ai.azure.com/api/projects/" +export FOUNDRY_MODEL="" +export AZURE_COSMOS_ENDPOINT="https://.documents.azure.com:443/" +export AZURE_COSMOS_DATABASE_NAME="" +export AZURE_COSMOS_CONTAINER_NAME="" +``` + +2. Run the example: + +```bash +uv run python samples/02-agents/context_providers/azure_cosmos/cosmos_history_provider.py +``` diff --git a/python/packages/azure-cosmos/samples/cosmos_history_provider.py b/python/samples/02-agents/context_providers/azure_cosmos/cosmos_history_provider.py similarity index 98% rename from python/packages/azure-cosmos/samples/cosmos_history_provider.py rename to python/samples/02-agents/context_providers/azure_cosmos/cosmos_history_provider.py index 67235cbf14..fc8459e878 100644 --- a/python/packages/azure-cosmos/samples/cosmos_history_provider.py +++ b/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() diff --git a/python/uv.lock b/python/uv.lock index 23d3297009..e1e74bfd49 100644 --- a/python/uv.lock +++ b/python/uv.lock @@ -360,6 +360,7 @@ all = [ { name = "agent-framework-anthropic", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, { name = "agent-framework-azure-ai", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, { name = "agent-framework-azure-ai-search", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, + { name = "agent-framework-azure-cosmos", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, { name = "agent-framework-azurefunctions", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, { name = "agent-framework-bedrock", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, { name = "agent-framework-chatkit", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, @@ -388,6 +389,7 @@ requires-dist = [ { name = "agent-framework-anthropic", marker = "extra == 'all'", editable = "packages/anthropic" }, { name = "agent-framework-azure-ai", marker = "extra == 'all'", editable = "packages/azure-ai" }, { name = "agent-framework-azure-ai-search", marker = "extra == 'all'", editable = "packages/azure-ai-search" }, + { name = "agent-framework-azure-cosmos", marker = "extra == 'all'", editable = "packages/azure-cosmos" }, { name = "agent-framework-azurefunctions", marker = "extra == 'all'", editable = "packages/azurefunctions" }, { name = "agent-framework-bedrock", marker = "extra == 'all'", editable = "packages/bedrock" }, { name = "agent-framework-chatkit", marker = "extra == 'all'", editable = "packages/chatkit" },