langgraph-cosmosdb-checkpointer

State-of-the-art Azure Cosmos DB checkpointer implementation for LangGraph with:

• strict config semantics (thread_id, checkpoint_ns, checkpoint_id)
• deterministic/idempotent put_writes ordering rules
• optimistic concurrency handling for special writes
• payload guardrails for Cosmos 2MB item limit (compression + chunking)

Install

pip install langgraph-cosmosdb-checkpointer

Usage

from langgraph_cosmosdb_checkpointer import CosmosDBSaver, CosmosDBSettings

settings = CosmosDBSettings(
    database_name="langgraph",
    checkpoint_container_name="checkpoints",
    writes_container_name="writes",
    blob_container_name="checkpoint_blobs",
)

saver = CosmosDBSaver.from_endpoint(
    endpoint="https://<account>.documents.azure.com:443/",
    credential="<account-key>",
    settings=settings,
)

You can also use AsyncCosmosDBSaver for async graph execution.

By default (create_containers=True), the saver creates the database and containers automatically if they don't exist.

Cosmos DB indexing policy

The writes container must have a composite index to support the multi-field sort used when loading pending writes:

ORDER BY c.task_id ASC, c.idx ASC

If you create the container using this library, it will include the required composite index. If the container already exists, Cosmos DB will keep the existing indexing policy (i.e., create_container_if_not_exists(...) will not update it), so you must update the container indexing policy in Azure or recreate the container.

Azure AD / Entra ID authentication

from_endpoint supports DefaultAzureCredential for Azure AD auth:

from azure.identity import DefaultAzureCredential
from langgraph_cosmosdb_checkpointer import CosmosDBSaver

saver = CosmosDBSaver.from_endpoint(
    endpoint="https://<account>.documents.azure.com:443/",
    credential=DefaultAzureCredential(),
)

If credential is omitted, from_endpoint will use DefaultAzureCredential() automatically.