استخدام التخزين في عاملك

يُعد التخزين مكوّنًا أساسيًا في Microsoft 365 Agents SDK. يتيح للعوامل تخزين حالة المحادثة وبيانات المستخدم ومعلومات أخرى عبر الجلسات. يدعم SDK خيارات تخزين متنوعة، بما في ذلك:

• التخزين في الذاكرة
• Azure Cosmos DB
• Azure Blob التخزين
• مزودات التخزين المخصصة

خيارات تخزين المفاتيح

يوفر Agents SDK عدة مزودات تخزين مدمجة، لكل منها حالات استخدام ومزايا خاصة بها. يمكنك اختيار مزود التخزين الأنسب لاحتياجات عاملِك. يمكنك أيضًا تنفيذ مزود تخزين مخصص.

1. تخزين الذاكرة

   • مناسب لأغراض الاختبار والتطوير.
   • يتم حذف البيانات عند إعادة تشغيل عامل، لذلك فهو غير مناسب للإنتاج.
   • البيانات متاحة فقط على مثيل تطبيق الويب، لذا لا يصلح للاستخدام ضمن عنقود.

2. Azure Cosmos DB

   • قاعدة بيانات موزعة عالميًا ومتعددة النماذج، تُعد خيارًا مثاليًا لعوامل الإنتاج.
   • يدعم التخزين المقسم لتحقيق قابلية التوسع وتحسين الأداء.

3. Azure Blob التخزين

   • تم تحسينه لتخزين البيانات غير المنظمة مثل النصوص أو الملفات الثنائية.
   • يُستخدم غالبًا لتخزين حالة عامل ونسخة مكتوبة

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 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.

Azure Blob Storage

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.