إعلام العاملين

باستخدام وحدة الإعلامات، يمكنك إنشاء عوامل تستجيب للأحداث والإعلامات من تطبيقات Microsoft 365. باستخدام دعم الإشعارات، يمكن للوكلاء استقبال ومعالجة التنبيهات عندما يتفاعل المستخدمون معهم عبر البريد الإلكتروني أو تعليقات المستندات أو سيناريوهات تعاونية أخرى.

سير عمل الإشعارات

اتبع سير العمل هذا لتمكين الإعلامات لتطبيق عامل الذكاء الاصطناعي:

  1. تثبيت حزم الإعلامات.

  2. استيراد مكونات الإشعارات

    • استيراد فئات الإعلامات ومُعَالِجِي الإشعارات.
    • استيراد أنواع الأنشطة ومعرفات القنوات.

  3. تسجيل معالجات الإشعارات

    • استخدم أساليب معالج الإعلام لتسجيل المسارات.
    • تكوين معالجات لأنواع محددة من الإخطارات، مثل البريد الإلكتروني أو وورد أو إكسل أو باور بوينت.

  4. معالجة الإعلامات في التعليمات البرمجية للعامل

    • يتلقى العامل إعلامات من تطبيقات Microsoft 365.
    • التعامل مع الإعلامات الواردة والاستجابة بشكل مناسب.

أنواع الإخطار

يدعم Agent 365 SDK أنواع الإشعارات التالية:

نوع الإشعار الوصف معرف القناة الفرعية
البريد الإلكتروني يتلقى الوكيل بريداً إلكترونياً يُذكر أو يُخاطب فيه email
Word تم ذكر العامل في تعليق في مستند Word word
Excel تم ذكر العامل في تعليق في مستند Excel excel
PowerPoint تم ذكر العامل في تعليق في مستند PowerPoint powerpoint
أحداث دورة الحياة إعلامات دورة حياة العامل (تم إنشاء هوية المستخدم، إلحاق حمل العمل، حذف المستخدم) غير متاح

أحداث دورة حياة العامل

تمكن أحداث دورة حياة العامل العامل من الاستجابة لأحداث نظام محددة تتعلق بإدارة هوية مستخدم العامل. يدعم SDK حاليا ثلاثة أحداث دورة حياة:

نوع الحدث معرف الحدث الوصف
تم إنشاء هوية المستخدم agenticUserIdentityCreated يتم تشغيله عند إنشاء هوية مستخدم عامل
تم تحديث إلحاق حمل العمل agenticUserWorkloadOnboardingUpdated يتم تفعيله عند تحديث حالة إدماج حمل العمل لمستخدم الوكيل
تم حذف المستخدم agenticUserDeleted يتم تشغيله عند حذف هوية مستخدم عامل

باستخدام هذه الأحداث، يمكن للوكلاء تنفيذ مهام التهيئة أو عمليات التنظيف أو إدارة الحالة استجابة لتغييرات دورة حياة المستخدم.

مرجع حمولة الإشعار

عندما يتلقى وكيلك إشعارا، تحتوي الحمولة على بيانات منظمة خاصة بنوع الإشعار. فهم هذه الحمولات يساعدك على استخراج المعلومات التي تحتاجها لمعالجة الإشعارات بفعالية.

حمولة إشعار البريد الإلكتروني

عندما يرسل المستخدم بريدا إلكترونيا إلى وكيلك أو يذكر وكيله في بريد إلكتروني، يتلقى وكيله إشعارا عبر البريد الإلكتروني بالبنية التالية:

{
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2026-02-06T17:45:20.740Z",
  "channelId": "agents",
  "serviceUrl": "http://localhost:56150/_connector",
  "recipient": {
    "id": "AgentName@contoso.onmicrosoft.com",
    "name": "My Agent",
    "agenticUserId": "<agentic-user-id>",
    "agenticAppId": "<agentic-app-id>",
    "tenantId": "<tenant-id>",
    "role": "agenticUser"
  },
  "conversation": {
    "id": "<conversation-id>",
    "conversationType": "personal",
    "tenantId": "<tenant-id>"
  },
  "from": {
    "id": "sender@contoso.onmicrosoft.com",
    "name": "Sender Name",
    "role": "user"
  },
  "type": "message",
  "channelData": {
    "tenant": {
      "id": "<tenant-id>"
    }
  },
  "locale": "en-US",
  "name": "emailNotification",
  "entities": [
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "emailNotification",
      "id": "<email-id>",
      "conversationId": "<conversation-id>",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\">Your email message content here</div>\n</body>"
    }
  ]
}

حمولة إعلام تعليق المستند (Word وExcel وPowerPoint)

عندما يذكر مستخدم وكيلك في تعليق داخل مستند Word أو Excel أو PowerPoint، يتلقى وكيلك إعلام تعليق WPX (Word أو PowerPoint أو Excel):

{
  "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "timestamp": "2026-02-06T17:46:02.248Z",
  "channelId": "agents",
  "serviceUrl": "http://localhost:56150/_connector",
  "recipient": {
    "id": "AgentName@contoso.onmicrosoft.com",
    "name": "My Agent",
    "agenticUserId": "<agentic-user-id>",
    "agenticAppId": "<agentic-app-id>",
    "tenantId": "<tenant-id>",
    "role": "agenticUser"
  },
  "conversation": {
    "id": "<conversation-id>",
    "conversationType": "personal",
    "tenantId": "<tenant-id>",
    "topic": "<document-topic>"
  },
  "from": {
    "id": "sender@contoso.onmicrosoft.com",
    "name": "Sender Name",
    "role": "user"
  },
  "type": "message",
  "channelData": {
    "tenant": {
      "id": "<tenant-id>"
    },
    "productContext": "Word"
  },
  "locale": "en-US",
  "textFormat": "plain",
  "text": "<at>My Agent</at> - Please review this section\n",
  "attachments": [
    {
      "contentUrl": "<document-url>",
      "name": "<document-name>",
      "content": {
        "uniqueId": "<document-unique-id>",
        "fileType": "docx"
      },
      "contentType": "application/vnd.microsoft.teams.file.download.info"
    }
  ],
  "entities": [
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "mentioned": {
        "id": "AgentName@contoso.onmicrosoft.com",
        "name": "@My Agent"
      },
      "text": "<at>My Agent</at>",
      "type": "mention"
    },
    {
      "id": "Word",
      "type": "productInfo"
    },
    {
      "parentCommentId": "<parent-comment-id>",
      "commentId": "<comment-id>",
      "documentId": "<document-id>",
      "type": "wpxcomment"
    }
  ]
}

إضافة إعلامات إلى وكيلك

اتبع هذه الخطوات لتمكين معالجة الإعلامات في الوكيل الحالي:

استيراد مكونات الإشعارات

أضف عمليات الاستيراد هذه إلى ملف العامل الخاص بك:

from microsoft_agents_a365 import AgentApplication
from microsoft_agents_a365.notifications import (
    AgentNotification,
    AgentNotificationActivity,
    NotificationTypes
)
from microsoft_agents.activity import ChannelId
from microsoft_agents.hosting.core import Authorization, TurnContext
  • AgentApplication: الفئة الأساسية لإنشاء تطبيقات Agent365. يوفر وظائف أساسية لأنشطة التوجيه وإدارة الحالة ومعالجة الطلبات.
  • AgentNotification: فئة لتسجيل معالجات الإعلامات باستخدام أساليب ديكوراتور. يوفر on_agent_notification() وon_email() وon_word() ومزخرفات أخرى ملائمة.
  • AgentNotificationActivity: التغليف يحتوي على بيانات إخطار مفصلة توفر خاصيات مكتوبة مثل email_notification و wpx_comment_notification التي تحتوي على بيانات تعريف خاصة بالإخطار مثل المعرفات وتفاصيل المحادثة ومراجع المستند.
  • NotificationTypes: عدد أنواع الإعلامات المدعومة مثل EMAIL_NOTIFICATION، WPX_COMMENT.
  • ChannelId: يستخدم لتحديد قنوات الإعلام، على سبيل المثال، ChannelId(channel="agents", sub_channel="*").
  • التخويل: سياق التخويل لمعالجة الإعلامات.
  • TurnContext: سياق الدورة الحالية للمحادثة من Agents SDK.

تسجيل معالجات الإشعارات في الوكيل الخاص بك

أضف معالجات الإشعارات إلى تهيئة الوكيل الخاص بك:

class YourAgent(AgentApplication):
    def __init__(self, app):
        # Create notification handler
        agent_notification = AgentNotification(app)
        
        # Register handler for all notifications
        @agent_notification.on_agent_notification(
            ChannelId(channel="agents", sub_channel="*")
        )
        async def handle_all_notifications(context, state, notification):
            # Route based on notification type
            if notification.notification_type == NotificationTypes.EMAIL_NOTIFICATION:
                await self.handle_email_notification(context, state, notification)
            elif notification.notification_type == NotificationTypes.WPX_COMMENT:
                await self.handle_comment_notification(context, state, notification)
            else:
                await context.send_activity('Notification type not yet implemented.')

تنفيذ معالجات إشعارات محددة

إضافة طرق معالجة لكل نوع من أنواع الإشعارات:

class YourAgent(AgentApplication):
    # ... __init__ from above ...
    
    async def handle_email_notification(self, context, state, notification):
        """Handle email notifications"""
        email = notification.email_notification
        
        if not email:
            await context.send_activity('No email data found')
            return
        
        # Process the email
        await context.send_activity(
            f'Received email notification. Email ID: {email.id}'
        )
        
        # Your email processing logic here
    
    async def handle_comment_notification(self, context, state, notification):
        """Handle document comment notifications"""
        comment = notification.wpx_comment_notification
        
        if not comment:
            await context.send_activity('No comment data found')
            return
        
        # Process the comment
        await context.send_activity(
            f'Received comment notification. Document ID: {comment.document_id}'
        )
        
        # Your comment processing logic here

تحديد المرسل

يتضمن كل نشاط إشعار Activity.From. يملأ النظام الأساسي A365 هذه الخاصية بالهوية الأساسية للمرسل، لذلك لا تحتاج إلى أي استدعاءات API أو الحصول على الرمز المميز. الوصول إليه داخل أي معالج إعلام:

async def handle_email_notification(self, context, state, notification):
    from_prop = context.activity.from_property
    logger.info(
        "Notification from — DisplayName: '%s', UserId: '%s', AadObjectId: '%s'",
        getattr(from_prop, "name", None) or "(unknown)",
        getattr(from_prop, "id", None) or "(unknown)",
        getattr(from_prop, "aad_object_id", None) or "(none)",
    )
    display_name = getattr(from_prop, "name", None) or "unknown"
    # Use display_name in your response or LLM prompt

Activity.from_property هو مثيل فئة ChannelAccount يحتوي على الخصائص التالية:

الخاصية الوصف
name ‏‫اسم العرض‬
id معرف مستخدم القناة
aad_object_id معرف عنصر Entra

Important

اسم العرض هو نص يتحكم فيه المستخدم. تنظيف النص (إزالة أحرف التحكم، وضمان الحد الأقصى للطول) قبل إدخاله في عبارات الأنظمة اللغوية الكبيرة (LLM) لمنع هجمات حقن الأوامر.

Tip

استخدم aadObjectId مع Graph API Microsoft لاسترداد بيانات ملف التعريف الموسع (المسمى الوظيفي والمدير والقسم) عندما يكون لدى وكيلك الأذونات المناسبة.

معالجات الإشعارات المتخصصة

بعد إعداد توجيه الإعلام الأساسي، قم باستخدام طرق المعالجة المتخصصة لمزيد من التحكم التفصيلي. باستخدام هذه الطرق، يمكنك:

  • تسجيل وحدات تحكم متعددة لنفس نوع الإشعار.
  • تعيين أولوية المعالج باستخدام الترتيب.
  • إعداد المصادقة التلقائية لكل معالج.

ملاحظة

بالنسبة لمعظم حالات الاستخدام، يكون نمط المعالج العام كافيًا. استخدم هذه المعالجات المتخصصة عندما تحتاج إلى توجيه متقدم أو معالجات متعددة لنوع الإعلام نفسه.

معالج متخصص لجميع الإعلامات

تسجيل المزيد من المعالجات التي تعالج جميع أنواع الإعلامات:

from microsoft_agents_a365.notifications import (
    AgentNotification,
    NotificationTypes
)
from microsoft_agents.activity import ChannelId

# Create notification handler
agent_notification = AgentNotification(app)

# Register handler for all notifications
@agent_notification.on_agent_notification(
    ChannelId(channel="agents", sub_channel="*")
)
async def handle_all_notifications(context, state, notification):
    if notification.notification_type == NotificationTypes.EMAIL_NOTIFICATION:
        if notification.email_notification:
            await context.send_activity(f"Received email: {notification.email_notification.id}")
    elif notification.notification_type == NotificationTypes.WPX_COMMENT:
        if notification.wpx_comment_notification:
            await context.send_activity(f"Received comment: {notification.wpx_comment_notification.comment_id}")

معالج متخصص لإشعارات البريد الإلكتروني

إضافة المزيد من معالجات التنبيهات خصيصاً لإشعارات البريد الإلكتروني:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Use the convenience method for email notifications
@agent_notification.on_email()
async def handle_email(context, state, notification):
    email = notification.email_notification
    
    if not email:
        await context.send_activity('No email found')
        return
    
    # Process the email
    email_id = email.id
    conversation_id = email.conversation_id
    
    # Send response
    await context.send_activity('Thank you for your email!')

معالجات متخصصة لتعليقات المستندات

تسجيل معالجات إضافية لإعلامات التعليقات في Word وExcel وPowerPoint:

from microsoft_agents_a365.notifications import AgentNotification

# Create notification handler
agent_notification = AgentNotification(app)

# Use convenience methods for document notifications
@agent_notification.on_word()
async def handle_word(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        document_id = comment.document_id
        comment_id = comment.comment_id
        await context.send_activity(f'Processing Word comment: {comment_id}')

@agent_notification.on_excel()
async def handle_excel(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        await context.send_activity('Processing Excel comment')

@agent_notification.on_powerpoint()
async def handle_powerpoint(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        await context.send_activity('Processing PowerPoint comment')

معالجات متخصصة لأحداث دورة الحياة

تسجيل المزيد من المعالجات لأحداث دورة حياة العامل، مثل إنشاء هوية المستخدم، وإلحاق حمل العمل، وحذف المستخدم:

from microsoft_agents_a365.notifications import AgentNotification

# Create notification handler
agent_notification = AgentNotification(app)

# Handle all lifecycle events
@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
    lifecycle_notification = notification.agent_lifecycle_notification
    if lifecycle_notification:
        event_type = lifecycle_notification.lifecycle_event_type
        
        if event_type == "agenticUserIdentityCreated":
            await context.send_activity('User identity created')
        elif event_type == "agenticUserWorkloadOnboardingUpdated":
            await context.send_activity('Workload onboarding completed')
        elif event_type == "agenticUserDeleted":
            await context.send_activity('User identity deleted')

تكوين متقدم

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

أولوية المعالج وترتيبه

عند استخدام معالجات متخصصة متعددة، حدد ترتيب الأولوية باستخدام قيم الرتبة. تشير قيم الرتبة الأدنى إلى أولوية أعلى:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Higher priority handler (processed first)
@agent_notification.on_email(rank=100)
async def high_priority_email(context, state, notification):
    # Handle with high priority
    pass

# Lower priority handler (processed after higher priority)
@agent_notification.on_email(rank=200)
async def low_priority_email(context, state, notification):
    # Handle with lower priority
    pass

معالجات المصادقة

تكوين معالجات تسجيل الدخول التلقائي للإعلامات التي تتطلب المصادقة:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Handler with automatic authentication
@agent_notification.on_email(auto_sign_in_handlers=['agentic'])
async def authenticated_email(context, state, notification):
    # Authentication is handled automatically
    pass

التعليمة البرمجية العينة

للحصول على أمثلة عملية كاملة لمعالجة الإعلامات عبر كافة الأطر الداعمة، راجع عينات العامل 365.

اختبر وكيلك مع الإشعارات

بعد تنفيذ معالجات الإعلامات، اختبر العامل الخاص بك للتأكد من أنه يتلقى أنواع الإعلامات المختلفة ويعالجها بشكل صحيح. اتبع دليل الاختبار لإعداد البيئة الخاصة بك، ثم ركز بشكل أساسي على قسم Test with notification activities للتحقق من صحة إعلاماتك باستخدام المصادقة الوكيلة.

مراقبة معالجة الإعلامات

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

  • Last updated on