Usa el almacenamiento en tu agente

El almacenamiento es un componente crítico de SDK de agentes de Microsoft 365. Permite a los agentes conservar el estado de conversación, los datos de usuario y otra información entre sesiones. El SDK admite varias opciones de almacenamiento, entre las que se incluyen:

• Almacenamiento en memoria
• Azure Cosmos DB (la base de datos de Azure Cosmos)
• Azure Blob Storage (Servicio de almacenamiento de blobs de Azure)
• Proveedores de almacenamiento personalizados

Opciones de almacenamiento de claves

El SDK de agentes proporciona varios proveedores de almacenamiento integrados, cada uno con sus propios casos de uso y ventajas. Puede elegir la que mejor se adapte a las necesidades del agente. También puede implementar su propio proveedor de almacenamiento personalizado.

1. Almacenamiento en memoria

   • Adecuado para pruebas y fines de desarrollo.
   • Los datos se borran cuando se reinicia el agente, por lo que no es adecuado para producción.
   • Los datos solo están disponibles en la instancia de la aplicación web, por lo que no es adecuado cuando se ejecuta en un clúster.

2. Azure Cosmos DB (la base de datos de Azure Cosmos)

   • Una base de datos multimodelo distribuida globalmente ideal para agentes de producción.
   • Admite el almacenamiento con particiones para mejorar la escalabilidad y el rendimiento.

3. Azure Blob Storage (Servicio de almacenamiento de blobs de Azure)

   • Optimizado para almacenar datos no estructurados como archivos binarios o de texto.
   • Se usa habitualmente para el almacenamiento del estado del agente y de las transcripciones.

4. Opciones de almacenamiento personalizadas mediante la implementación IStorage

Uso de diferentes proveedores de almacenamiento

Almacenamiento en memoria

Todos los ejemplos usan MemoryStorage. Este almacenamiento es volátil y es adecuado solo para desarrollo y pruebas. En escenarios de producción, use una opción de almacenamiento más duradera, como Azure Cosmos DB o Azure Blob Storage.

C#

En Program.cs, registre 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,
)

Almacenamiento de Azure CosmosDb

C#

1. Agregue una dependencia de paquete para Microsoft.Agents.Storage.CosmosDb.

2. En Program.cs, agregue (o reemplace el registro existente de) 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. Puede encontrar más información en CosmosDbPartitionedStorageOptions.

JavaScript

1. Agregue una dependencia de paquete para @microsoft/agents-hosting-storage-cosmos.

2. Configure y cree el almacenamiento y, a continuación, páselo a 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. Puede encontrar más información en CosmosDbPartitionedStorageOptions.

Python

1. Agregue una dependencia de paquete para microsoft-agents-storage-cosmos.

2. Configure y cree el almacenamiento; a continuación, páselo a 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. Puede encontrar más información en CosmosDBStorageConfig.

Almacenamiento de blobs de Azure

C#

1. Agregue una dependencia de paquete para Microsoft.Agents.Storage.Blobs.

2. En Program.cs, agregue (o reemplace el registro existente de 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. Agregue una dependencia de paquete para @microsoft/agents-hosting-storage-blob.

2. Configure el almacenamiento y créelo; a continuación, páselo a 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. Agregue una dependencia de paquete para microsoft-agents-storage-blob.

2. Configure el almacenamiento y créelo y, a continuación, páselo a 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. Puede encontrar más información en BlobStorageConfig.