Azure Cosmos DB History Provider for Microsoft Agent Framework

1.0.0b260507 verified Sat May 09 auth: no python

Azure Cosmos DB history provider integration for Microsoft Agent Framework. This package stores and retrieves agent conversation history using Azure Cosmos DB. Current version is 1.0.0b260507, a beta release. Release cadence is irregular, tied to the Agent Framework development cycle.

pip install agent-framework-azure-cosmos

Common errors

error RuntimeError: This event loop is already running ↓

cause Calling an async adapter method (e.g., `adapter.store(...)`) from a synchronous context without an async runner.

fix

Ensure you call adapter methods inside an async function and await them. If running in a Jupyter notebook, use await directly; otherwise use asyncio.run(your_async_function()).

error azure.core.exceptions.ClientAuthenticationError: DefaultAzureCredential failed to retrieve a token ↓

cause No Azure credentials available in the environment (e.g., AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET not set, and no managed identity).

fix

Set environment variables for service principal or enable managed identity. Alternatively, use ClientSecretCredential with explicit credentials.

error AttributeError: module 'agent_framework_azure_cosmos' has no attribute 'AzureCosmosDBHistoryAdapter' ↓

cause Installed the wrong package (e.g., `azure-cosmos` or `agent-framework`). Hyphen confusion in package name.

fix

Install the correct package: pip install agent-framework-azure-cosmos and import from agent_framework_azure_cosmos import AzureCosmosDBHistoryAdapter.

Warnings

breaking Must use async context to call adapter methods (e.g., store / retrieve). Synchronous calls will raise RuntimeError. ↓

fix Wrap all adapter operations in `async def` and `await` calls. Use `asyncio.run()` or an event loop.

deprecated Default Azure credential fallback to managed identity; previously users relied on connection strings. Connection string support is deprecated and may be removed. ↓

fix Switch to `DefaultAzureCredential()` with appropriate RBAC roles on Cosmos DB.

gotcha The package name uses hyphens, but the Python module name uses underscores. Pip install with hyphens, import with underscores. ↓

fix `pip install agent-framework-azure-cosmos` -> `import agent_framework_azure_cosmos`

gotcha Cosmos DB account must have a container with id field partition key set to '/id' for the adapter to work correctly. ↓

fix Create container with partition key '/id' and ensure the container exists before running the adapter.

Imports

AzureCosmosDBHistoryAdapter

wrong

from agent_framework.azure_cosmos import AzureCosmosDBHistoryAdapter

correct

from agent_framework_azure_cosmos import AzureCosmosDBHistoryAdapter

Legacy structure: this package is a separate distribution, not part of agent_framework namespace.

Quickstart

Initialize the Azure Cosmos DB history adapter using DefaultAzureCredential for authentication.

import os
from azure.identity import DefaultAzureCredential
from agent_framework_azure_cosmos import AzureCosmosDBHistoryAdapter

# Use environment variables for credentials (better to use managed identity in production)
credential = DefaultAzureCredential()
account_url = os.environ.get("COSMOS_ACCOUNT_URL", "https://your-account.documents.azure.com:443/")
database_name = os.environ.get("COSMOS_DATABASE", "agent_history")
container_name = os.environ.get("COSMOS_CONTAINER", "conversations")

adapter = AzureCosmosDBHistoryAdapter(
    account_url=account_url,
    credential=credential,
    database_name=database_name,
    container_name=container_name
)
print("Adapter created successfully.")
# Use adapter with Agent Framework's Agent class