Utilizar o armazenamento no seu agente

O armazenamento é um componente crítico do SDK de Agentes do Microsoft 365. Permite que os agentes persistam o estado da conversa, is dados do utilizador e outras informações ao longo das sessões. O SDK suporta várias opções de armazenamento, incluindo:

• Armazenamento na memória
• Azure Cosmos DB
• Armazenamento de Blobs do Azure
• Fornecedores de armazenamento personalizados

Principais opções de armazenamento

O SDK de Agentes fornece vários fornecedores de armazenamento incorporados, cada um com os seus próprios casos de utilização e benefícios. Pode escolher aquele que melhor se adequa às necessidades do seu agente. Também pode implementar o seu próprio fornecedor de armazenamento personalizado.

1. Armazenamento de memória

   • Adequado para fins de teste e desenvolvimento.
   • Os dados são limpos quando o agente é reiniciado, tornando-os inadequados para produção.
   • Os dados só estão disponíveis na instância de aplicação Web, tornando-os inadequados quando executados num cluster.

2. Azure Cosmos DB

   • Uma base de dados multimodelo distribuída globalmente, ideal para agentes de produção.
   • Suporta armazenamento particionado para escalabilidade e desempenho.

3. Armazenamento de Blobs do Azure

   • Otimizado para armazenar dados não estruturados, como texto ou ficheiros binários.
   • Comumente utilizado para armazenamento do estado e de transcrições do agente.

4. Opções de armazenamento personalizadas por meio da implementação de IStorage

Utilizar diferentes fornecedores de armazenamento

Armazenamento de memória

Todos os exemplos utilizam MemoryStorage. Este armazenamento é volátil e adequado apenas para desenvolvimento e teste. Para cenários de produção, utilize uma opção de armazenamento mais durável como o Azure Cosmos DB ou o Armazenamento de Blobs do Azure.

C#

Em Program.cs, registe 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,
)

Armazenamento do Azure Cosmos DB

C#

1. Adicione uma dependência de pacote para Microsoft.Agents.Storage.CosmosDb.

2. Em Program.cs, adicione (ou substitua o existente) o registo IStorage por:

   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. Saiba mais em CosmosDbPartitionedStorageOptions.

JavaScript

1. Adicione uma dependência de pacote para @microsoft/agents-hosting-storage-cosmos.

2. Configure e crie o armazenamento, em seguida, transmita-o ao 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. Saiba mais em CosmosDbPartitionedStorageOptions.

Python

1. Adicione uma dependência de pacote para microsoft-agents-storage-cosmos.

2. Configure e crie o armazenamento, em seguida, transmita-o ao 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. Saiba mais em CosmosDBStorageConfig.

Armazenamento de blobs do Azure

C#

1. Adicione uma dependência de pacote para Microsoft.Agents.Storage.Blobs.

2. Em Program.cs, adicione (ou substitua o existente) o registo IStorage por:

   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. Adicione uma dependência de pacote para @microsoft/agents-hosting-storage-blob.

2. Configure e crie o armazenamento, em seguida, transmita-o ao 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. Adicione uma dependência de pacote para microsoft-agents-storage-blob.

2. Configure e crie o armazenamento, em seguida, transmita-o ao 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. Saiba mais em BlobStorageConfig.