Agents SDK storage overview

Storage is a critical component of the Microsoft Agents SDK, enabling agents to persist conversation state, user data, and other information across sessions. It supports various storage options, including in-memory storage, Azure Cosmos DB, Azure Blobs Storage, and allows for custom storage providers.

Key storage options

1. Memory Storage

   • Suitable for testing and development purposes.
   • Data is cleared when the agent restarts, making it unsuitable for production.
   • Data is only availble on the webapp instance, making it unsuitable when running in a cluster.

2. Azure Cosmos DB

   • A globally distributed, multi-model database ideal for production agents.
   • Supports partitioned storage for scalability and performance.

3. Azure Blob Storage

   • Optimized for storing unstructured data like text or binary files.
   • Commonly used for agent state and transcript storage.

4. Custom storage options can be provided by implementing IStorage

Using different storage providers

Memory storage

All samples use MemoryStorage

For .NET, In Program.cs, register MemoryStorage

builder.Services.AddSingleton<IStorage, MemoryStorage>();

Azure CosmosDb storage

For .NET:

1. Add a package dependency for Microsoft.Agents.Storage.CosmosDb

2. In Program.cs, add (or replace existing) IStorage registration with:

   builder.Services.AddSingleton<IStorage>(sp =>
   {
         var options = new CosmosDbPartitionedStorageOptions()
         {
            CosmosDbEndpoint = "your-cosmosdb-endpoint",
            DatabaseId = "your-database-id",
            ContainerId = "your-container-id",
   
            // Get a TokenCredential from your defined Connections
            TokenCredential = sp.GetService<IConnections>().GetConnection("ServiceConnection").GetTokenCredential()
         };
   
         return new CosmosDbPartitionedStorage(options);
   });
   

3. For more details, see CosmosDbPartitionedStorageOptions.

Azure blob storage

For .NET:

1. Add a package dependency for Microsoft.Agents.Storage.Blobs

2. In Program.cs, add (or replace existing) IStorage registration with:

   builder.Services.AddSingleton<IStorage>(sp =>
   {
      // Get a TokenCredential from your defined Connections
      var tokenCredential = sp.GetService<IConnections>().GetConnection("ServiceConnection").GetTokenCredential();
   
      return new BlobsStorage(
         new Uri("{{your-blobs-storage-endpoint}}/agent-state"),
         tokenCredential);
   });