在您的 Agent 中使用儲存體

儲存體是 Microsoft 365 Agents SDK 的重要元件。 這可讓 Agent 在不同工作階段之間保留交談狀態、使用者資料及其他資訊。 SDK 支援多種儲存體選項，包括：

• 記憶體內儲存體
• Azure Cosmos DB
• Azure Blob 儲存體
• 自訂儲存體提供者

主要儲存體選項

Agents SDK 提供多個內建儲存體提供者，各有其適用案例與優點。 您可以選擇最符合 Agent 需求的提供者。 您也可以實作自己的自訂儲存體提供者。

1. 記憶體儲存體

   • 適合用於測試與開發。
   • Agent 重新啟動時資料會被清除，因此不適合用於實際執行環境。
   • 資料僅存在於 Web 應用程式執行個體上，因此不適合在叢集中執行的情況。

2. Azure Cosmos DB

   • 全域分散式多模型資料庫，適合用於實際執行的 Agent。
   • 支援分割儲存體，提供延展性與效能。

3. Azure Blob 儲存體

   • 針對儲存文字或二進位檔案等非結構化資料進行最佳化。
   • 常用於儲存 Agent 狀態與逐字稿。

4. 實作 IStorage 以建立自訂儲存體選項

使用不同的儲存體提供者

記憶體儲存體

所有範例都使用 MemoryStorage。 此儲存體具揮發性，僅適合用於開發與測試。 若為實際執行案例，請使用更持久的儲存體選項，例如 Azure Cosmos DB 或 Azure Blob 儲存體。

C#

在 Program.cs 中，註冊 MemoryStorage：

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

JavaScript

import { MemoryStorage, AgentApplication, TurnState } from '@microsoft/agents-hosting'

const storage = new MemoryStorage()

const app = new AgentApplication<TurnState>({
  storage
})

Python

from microsoft_agents.hosting.core import AgentApplication, TurnState, MemoryStorage

storage = MemoryStorage()

app = AgentApplication[TurnState](
    storage=storage,
    adapter=adapter,
    authorization=authorization,
)

Azure CosmosDb 儲存體

C#

1. 新增 Microsoft.Agents.Storage.CosmosDb 的套件相依性。

2. 在 Program.cs 中，新增 (或取代現有的) IStorage 註冊，內容如下：

   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. 在 CosmosDbPartitionedStorageOptions 中深入了解。

JavaScript

1. 新增 @microsoft/agents-hosting-storage-cosmos 的套件相依性。

2. 設定並建立儲存體，然後將其傳遞至 AgentApplication：

   import { AgentApplication, TurnState } from '@microsoft/agents-hosting'
   import { CosmosDbPartitionedStorage } from '@microsoft/agents-hosting-storage-cosmos'
   
   const storage = new CosmosDbPartitionedStorage({
     databaseId: process.env.COSMOS_DATABASE_ID,
     containerId: process.env.COSMOS_CONTAINER_ID,
     cosmosClientOptions: {
       endpoint: process.env.COSMOS_ENDPOINT,
       key: process.env.COSMOS_KEY,
     }
   })
   
   const app = new AgentApplication<TurnState>({
     storage
   })
   

3. 在 CosmosDbPartitionedStorageOptions 中深入了解。

Python

1. 新增 microsoft-agents-storage-cosmos 的套件相依性。

2. 設定並建立儲存體，然後將其傳遞至 AgentApplication：

   from microsoft_agents.hosting.core import AgentApplication, TurnState
   from microsoft_agents.storage.cosmos import CosmosDBStorage, CosmosDBStorageConfig
   
   config = CosmosDBStorageConfig(
       cosmos_db_endpoint="your-cosmosdb-endpoint",
       database_id="your-database-id",
       container_id="your-container-id",
       credential=your_token_credential,
   )
   
   storage = CosmosDBStorage(config)
   
   app = AgentApplication[TurnState](
       storage=storage,
       adapter=adapter,
       authorization=authorization,
   )
   

3. 在 CosmosDBStorageConfig 中深入了解。

Azure Blob 儲存體

C#

1. 新增 Microsoft.Agents.Storage.Blobs 的套件相依性。

2. 在 Program.cs 中，新增 (或取代現有的) IStorage 註冊，內容如下：

   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);
   });
   

JavaScript

1. 新增 @microsoft/agents-hosting-storage-blob 的套件相依性。

2. 設定並建立儲存體，然後將其傳遞至 AgentApplication：

   import { AgentApplication, TurnState } from '@microsoft/agents-hosting'
   import { BlobsStorage } from '@microsoft/agents-hosting-storage-blob'
   
   const storage = new BlobsStorage(
     process.env.BLOB_CONTAINER_ID,
     process.env.BLOB_STORAGE_CONNECTION_STRING
   )
   
   const app = new AgentApplication<TurnState>({
     storage
   })
   

Python

1. 新增 microsoft-agents-storage-blob 的套件相依性。

2. 設定並建立儲存體，然後將其傳遞至 AgentApplication：

   from microsoft_agents.hosting.core import AgentApplication, TurnState
   from microsoft_agents.storage.blob import BlobStorage, BlobStorageConfig
   
   # Using a connection string
   config = BlobStorageConfig(
       container_name="agent-state",
       connection_string="your-connection-string",
   )
   
   # Or using a TokenCredential
   config = BlobStorageConfig(
       container_name="agent-state",
       url="https://your-storage-account.blob.core.windows.net",
       credential=your_token_credential,
   )
   
   storage = BlobStorage(config)
   
   app = AgentApplication[TurnState](
       storage=storage,
       adapter=adapter,
       authorization=authorization,
   )
   

3. 在 BlobStorageConfig 中深入了解。