Python: Add Cosmos DB ChatMessageStore sample example for external chat history

[aman-panjwani]

Motivation and Context

This change introduces a Cosmos DB–backed ChatMessageStore implementation that enables developers to persist agent chat history externally instead of relying on the default in-memory storage.

1. Why is this change required?
   Many production scenarios require durable and queryable chat history beyond process lifetime, especially when scaling agents horizontally or resuming long-running threads.

2. What problem does it solve?
   Existing examples only demonstrate in-memory or vector-based message storage. This contribution provides a clear, working reference for integrating Azure Cosmos DB (Core SQL API) as a persistent external store.

3. What scenario does it contribute to?

   • Persist and retrieve conversation history across sessions
   • Maintain chronological context reconstruction for resumed threads
   • Demonstrate thread-based partitioning (/thread_id) for scalable storage
   • Showcase proper async resource management for Cosmos DB and chat clients

4. Related issue (if any):
   N/A – this is a new sample addition.

---

Description

This PR adds a new sample file:
chat_store/third_party_chat_store_cosmosDB.py

Key highlights:

• Implements a lightweight, async CosmosDBChatMessageStore for the Microsoft Agent Framework.
• Uses key-based authentication with an existing Cosmos DB database and container.
• Provides:
  • Thread-scoped message persistence (partition_key=/thread_id)
  • Chronological message retrieval (ORDER BY ts ASC)
  • Thread state serialization/deserialization for persistence
  • Clean shutdown via store.aclose() and chat_client.aclose()
• Includes a minimal usage example integrating with ChatAgent and AzureOpenAIChatClient.

---

Contribution Checklist

• The code builds cleanly without any errors or warnings
• The PR follows the Contribution Guidelines
• All existing tests pass, and this sample introduces no breaking dependencies
• Is this a breaking change? No

[aman-panjwani]

@microsoft-github-policy-service agree

[nmoeller]

Hey great work! I have started to work on something similar and your works looks nice. Just a small comments from my site on this and one more thought. Feel free to implement or ignore them 😄

You could also think to add this maybe as a package so others could make easy use of you class without copying your code.

[aman-panjwani]

Thanks, @nmoeller the idea to package this is excellent and really helpful. I’m planning to implement that. In the meantime, I’ve updated the sample with your suggested changes.

[nmoeller]

Just a few fore "editorial" things. But overall looking good 👍

Could we rename third_party_chat_store_cosmosDB.py to third_party_chat_store_cosmos_db.py or third_party_chat_store_cosmosdb.py ? I did not yet found a file with upper cases in the repo.

Thanks you for working on this, nearly there !

[nmoeller]

One small thing from my side, which is again more editorial.

Thanks for working on this, let's see what the Core Team says to this as well 👍