Использование хранения данных в агенте

Хранение данных — критически важный компонент Пакета SDK агентов Microsoft 365. Это позволяет агентам сохранять состояние беседы, данные пользователя и другую информацию между сеансами. Пакет SDK поддерживает различные варианты хранения данных, включая:

• Хранение в памяти
• Azure Cosmos DB
• Хранилище BLOB-объектов Azure
• Пользовательские поставщики хранения данных

Основные варианты хранения данных

Пакет SDK агентов предоставляет несколько встроенных поставщиков хранения данных, каждый из которых имеет свои собственные сценарии использования и преимущества. Вы можете выбрать вариант, который лучше всего соответствует потребностям вашего агента. Вы также можете реализовать собственный поставщик хранения данных.

1. Хранение в памяти

   • Подходит для тестирования и разработки.
   • Данные очищаются при перезапуске агента, поэтому для рабочей эксплуатации этот вариант не подходит.
   • Данные доступны только в экземпляре веб-приложения, поэтому этот вариант не подходит для использования в кластере.

2. Azure Cosmos DB

   • Глобально распределенная многомодельная база данных, идеально подходящая для рабочих агентов.
   • Поддерживает секционированное хранение данных для масштабируемости и производительности.

3. Хранилище BLOB-объектов Azure

   • Этот вариант оптимизирован для хранения неструктурированных данных, таких как текстовые или двоичные файлы.
   • Часто используется для хранения состояния агента и расшифровок.

4. Пользовательские варианты хранения с реализацией IStorage

Использование различных поставщиков хранения данных

Хранение в памяти

Во всех примерах используется MemoryStorage. Это хранилище временное и подходит только для разработки и тестирования. Для рабочих сценариев используйте более надежный вариант хранения, например Azure Cosmos DB или Хранилище BLOB-объектов Azure.

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 Cosmos DB

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.

Хранилище BLOB-объектов Azure

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.