Usare l'archiviazione nell'agente

L'archiviazione è un componente critico dell'SDK per agenti Microsoft 365. Consente agli agenti di salvare lo stato della conversazione, i dati utente e altre informazioni tra una sessione e l'altra. L'SDK supporta varie opzioni di archiviazione, tra cui:

• Archiviazione in memoria
• Azure Cosmos DB
• Spazio di Archiviazione BLOB di Azure
• Provider di archiviazione personalizzati

Opzione di archiviazione principali

L'SDK per agenti offre diversi provider di archiviazione integrati, ognuno con i propri casi d'uso e vantaggi. Puoi scegliere quello che meglio si adatta alle esigenze del tuo agente. È inoltre possibile implementare un provider di archiviazione personalizzato.

1. Archiviazione in memoria

   • Adatta per scopi di test e sviluppo.
   • I dati vengono cancellati al riavvio dell'agente, rendendola non adatta per la produzione.
   • I dati sono disponibili solo nell'istanza dell'app Web, rendendola non adatta durante l'esecuzione in un cluster.

2. Azure Cosmos DB

   • Un database multimodello distribuito a livello globale è ideale per gli agenti di produzione.
   • Supporta l'archiviazione partizionata per scalabilità e prestazioni.

3. Spazio di Archiviazione BLOB di Azure

   • Ottimizzato per l'archiviazione di dati non strutturati come file di testo o binari.
   • Comunemente usato per l'archiviazione dello stato e della trascrizione dell'agente.

4. Opzioni di archiviazione personalizzate implementando IStorage

Uso di provider di archiviazione diversi

Archiviazione in memoria

Tutti gli esempi usano MemoryStorage. Questa archiviazione è volatile e adatta solo allo sviluppo e ai test. Per scenari di produzione, usa un'opzione di archiviazione più resistente come Azure Cosmos DB o Archiviazione BLOB di Azure.

C#

In Program.cs, registra 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,
)

Archiviazione Azure Cosmos DB

C#

1. Aggiungi una dipendenza del pacchetto per Microsoft.Agents.Storage.CosmosDb.

2. In Program.cs, aggiungi o sostituisci la registrazione esistente IStorage con:

   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. Altre informazioni sono disponibili in CosmosDbPartitionedStorageOptions.

JavaScript

1. Aggiungi una dipendenza del pacchetto per @microsoft/agents-hosting-storage-cosmos.

2. Configura e crea l'archiviazione, poi passala ad 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. Altre informazioni sono disponibili in CosmosDbPartitionedStorageOptions.

Python

1. Aggiungi una dipendenza del pacchetto per microsoft-agents-storage-cosmos.

2. Configura e crea l'archiviazione, poi passala ad 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. Altre informazioni sono disponibili in CosmosDBStorageConfig.

Archiviazione BLOB di Azure

C#

1. Aggiungi una dipendenza del pacchetto per Microsoft.Agents.Storage.Blobs.

2. In Program.cs, aggiungi o sostituisci la registrazione esistente IStorage con:

   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. Aggiungi una dipendenza del pacchetto per @microsoft/agents-hosting-storage-blob.

2. Configura e crea l'archiviazione, poi passala ad 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. Aggiungi una dipendenza del pacchetto per microsoft-agents-storage-blob.

2. Configura e crea l'archiviazione, poi passala ad 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. Altre informazioni sono disponibili in BlobStorageConfig.