Edit

Azure Cosmos DB

Azure Cosmos DB supports two distinct context-provider patterns in Agent Framework. Choose the provider based on whether you need an exact transcript or extracted long-term knowledge.

Pattern Provider Behavior
Conversation history CosmosChatHistoryProvider (.NET) or CosmosHistoryProvider (Python) Persists complete messages so a session can resume after a restart or on another application instance.
Long-term memory CosmosMemoryContextProvider (Python) Extracts facts, procedural knowledge, episodic memories, and summaries, then retrieves relevant memories for later runs.

Persist conversation history

Install the packages

dotnet add package Microsoft.Agents.AI.CosmosNoSql --prerelease
dotnet add package Azure.Identity

Configure Cosmos DB chat history

Use the managed-identity extension to attach CosmosChatHistoryProvider to ChatClientAgentOptions.

using Azure.Identity;
using Microsoft.Agents.AI;

var options = new ChatClientAgentOptions
{
    ChatOptions = new() { Instructions = "You are a helpful assistant." }
}.WithCosmosDBChatHistoryProviderUsingManagedIdentity(
    accountEndpoint: Environment.GetEnvironmentVariable("AZURE_COSMOS_ENDPOINT")!,
    databaseId: Environment.GetEnvironmentVariable("AZURE_COSMOS_DATABASE_NAME")!,
    containerId: Environment.GetEnvironmentVariable("AZURE_COSMOS_CONTAINER_NAME")!,
    tokenCredential: new DefaultAzureCredential());

AIAgent agent = chatClient.AsAIAgent(options);

The default state initializer creates a conversation ID. Supply a CosmosChatHistoryProvider.State initializer when your application needs explicit conversation, tenant, and user routing. When tenant and user IDs are present, the provider uses a hierarchical partition key.

Warning

DefaultAzureCredential is convenient for development. In production, prefer a specific credential such as ManagedIdentityCredential.

Install the package

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

Configure CosmosHistoryProvider

The Python provider accepts either an Azure credential or an account key and uses the session_id as the partition key.

# 1. Create an Azure credential and a CosmosHistoryProvider for agent context
async with (
    AzureCliCredential() as credential,
    CosmosHistoryProvider(
        endpoint=cosmos_endpoint,
        database_name=cosmos_database_name,
        container_name=cosmos_container_name,
        credential=cosmos_key or credential,
    ) as history_provider,
    # 2. Create an agent that uses Cosmos for persisted conversation history.
    Agent(
        client=FoundryChatClient(
            project_endpoint=project_endpoint,
            model=model,
            credential=credential,
        ),
        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}")

Persist the serialized AgentSession in trusted application storage when clients need to recover the same session identifier later.

Note

Azure Cosmos DB history storage isn't currently available for Agent Framework Go. Implement a custom history provider or see the Agent Framework Go repository for the latest status.

Add long-term semantic memory

Note

The Azure Cosmos DB long-term memory provider is currently available for Python. Use the conversation-history provider above when a .NET application needs exact transcript persistence.

Prerequisites

  • An Azure Cosmos DB account and database.
  • A Microsoft Foundry project with chat and embedding model deployments.
  • Azure identity access to both resources.

Install the packages

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

Configure the memory provider

The same Foundry project can supply the chat model, embeddings, and memory extraction model. Attach the provider through context_providers.

def _build_agent(provider: CosmosMemoryContextProvider, credential: DefaultAzureCredential) -> Agent:
    """Build an agent that uses the memory provider and the same Foundry endpoint for chat."""
    return Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_ENDPOINT"],
            model=os.getenv("CHAT_MODEL", "gpt-4o-mini"),
            credential=credential,
        ),
        name="Memory Assistant",
        instructions="You are a helpful assistant with long-term memory about the user.",
        context_providers=[provider],
    )


async def user_scoped_memory() -> None:
    """Memory scoped to a stable user id, so it persists across sessions and threads."""
    credential = DefaultAzureCredential()
    provider = CosmosMemoryContextProvider(
        cosmos_endpoint=os.environ["COSMOS_ENDPOINT"],
        foundry_endpoint=os.environ["FOUNDRY_ENDPOINT"],
        embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
        chat_model=os.getenv("CHAT_MODEL", "gpt-4o-mini"),
        credential=credential,
    )
    agent = _build_agent(provider, credential)

    async with provider:
        session = agent.create_session()
        # Provider state is scoped by source id; set a stable user id there so memory
        # persists across sessions rather than being limited to this one.
        session.state.setdefault(provider.source_id, {})["user_id"] = "alice"
        first = await agent.run("I love hiking and I'm allergic to peanuts.", session=session)
        print("Assistant:", first.text)

        # A brand-new session for the same user still recalls the earlier facts.
        new_session = agent.create_session()
        new_session.state.setdefault(provider.source_id, {})["user_id"] = "alice"
        recall = await agent.run("What do you remember about me?", session=new_session)
        print("Assistant:", recall.text)

        # Let background extraction finish and persist before the client closes.
        await provider.flush()

A stable user_id keeps memory available across sessions and threads. Without one, the provider scopes memory to the current session ID.

Memory processing

Memory extraction runs in the background after each turn. Use the provider as an async context manager or call flush() before shutdown so pending extraction completes before the clients close.

The provider also supports custom extraction prompts, processor cadence, confidence thresholds, memory types, and retrieval limits.

Note

Azure Cosmos DB long-term memory isn't currently available for Agent Framework Go. See the Agent Framework Go repository for the latest status.

Production considerations

  • Derive user, tenant, and session identifiers from authenticated application identity.
  • Choose partition keys that distribute traffic while enforcing tenant isolation.
  • Keep Cosmos DB and model resources in approved regions and apply least-privilege RBAC.
  • Configure time-to-live, backup, retention, and deletion policies for both transcripts and extracted memories.
  • Filter or redact sensitive content before persistence, and don't use extracted memories directly for authorization decisions.

Next steps

Browse context provider integrations

Go deeper:

  • Last updated on