---
id: agent-framework-azure-cosmos
version: "1.0.0b260730"
license: unclear
license_treatment: permissive
maintenance: active
---

# agent-framework-azure-cosmos — Azure Cosmos DB history provider integration for Microsoft Agent Framework.

License: permissive · Maintenance: active · Downloads: 239.5K/mo

## What it is and what it does

This package bridges the Microsoft Agent Framework and Azure Cosmos DB, offering two main storage backends: CosmosHistoryProvider for persisting multi-turn conversation history, and CosmosCheckpointStorage for durable workflow state. Both support multiple authentication modes (managed identity, account keys, environment variables) and auto-create their database and container on first use.

It is designed for developers building agent applications that need to survive process restarts or maintain long-running conversation context. The package integrates directly with the agent-framework-core runtime and relies on the azure-cosmos client library for all Cosmos DB operations.

Use it for:

- Store multi-turn conversation history for chatbots or virtual agents across user sessions.
- Enable workflow pause-and-resume by checkpointing agent state to Cosmos DB between supersteps.
- Build production agent systems with managed identity authentication for secure, credential-less deployment.
- Persist agent conversation context for audit, compliance, or analytics purposes.
- Scale agent applications by offloading session state to a managed NoSQL database.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides Azure Cosmos DB integration for the Microsoft Agent Framework, enabling persistent storage of conversation history and workflow checkpoints.

Yes, if you are building agent applications on the Microsoft Agent Framework and need durable storage for conversation history or workflow checkpoints. The package is actively maintained, has low install friction, carries no known vulnerabilities, and is MIT-licensed. It is still in beta (1.0.0b260730), so expect potential API changes before a stable release.

## Install

pip install agent-framework-azure-cosmos
uv add agent-framework-azure-cosmos
poetry add agent-framework-azure-cosmos

## Installing agent-framework-azure-cosmos

Before you install: Low install friction with a pure-Python wheel. Active maintenance—released 15 days ago with recent commits. Depends on agent-framework-core and azure-cosmos, both standard Azure SDK packages.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

pip install agent-framework-azure-cosmos --pre

from azure.identity.aio import DefaultAzureCredential
from agent_framework_azure_cosmos import CosmosHistoryProvider

provider = CosmosHistoryProvider(
    endpoint="https://.documents.azure.com:443/",
    credential=DefaultAzureCredential(),
    database_name="agent-framework",
    container_name="chat-history",
)

Requires Python 3.10 or later and an active Azure Cosmos DB account with endpoint and credentials.

Verify before relying:

- Whether the package works with Python 3.14 in practice (classifier lists it but it's a future release).
- Performance characteristics and cost implications of storing large conversation histories or frequent checkpoint writes in Cosmos DB.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 239.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

azure cosmos db agent framework, conversation history storage azure, workflow checkpoint persistence, agent framework cosmos integration, durable workflow checkpointing, cosmos db history provider, azure-integration, agent-framework, workflow-persistence

[View on SkillFed](https://skillfed.io/packages/agent-framework-azure-cosmos) · [View on PyPI](https://pypi.org/project/agent-framework-azure-cosmos/)