एजेंटों को सूचित करना

Notifications मॉड्यूल का उपयोग करके, आप ऐसे एजेंट बना सकते हैं जो Microsoft 365 अनुप्रयोगों से घटनाओं और सूचनाओं का जवाब देते हैं। Notifications सपोर्ट का उपयोग करके, एजेंट अलर्ट प्राप्त कर सकते हैं और संसाधित कर सकते हैं जब उपयोगकर्ता ईमेल, दस्तावेज़ टिप्पणियों या अन्य सहयोगी परिदृश्यों के माध्यम से उनके साथ संवाद करते हैं।

सूचनाओं का वर्कफ़्लो

अपने AI एजेंट एप्लिकेशन के लिए सूचनाएं सक्षम करने के लिए इस कार्यप्रवाह का पालन करें:

  1. अधिसूचना पैकेज स्थापित करें.

  2. सूचना घटक आयात करें

    • सूचना कक्षाओं और हैंडलर आयात करें.
    • गतिविधि प्रकार और चैनल पहचानकर्ता आयात करें.

  3. अधिसूचना हैंडलर रजिस्टर करें

    • मार्गों को पंजीकृत करने के लिए अधिसूचना हैंडलर विधियों का उपयोग करें।
    • विशिष्ट सूचना प्रकारों, जैसे ईमेल, Word, Excel या PowerPoint के लिए हैंडलर कॉन्फ़िगर करें.

  4. एजेंट कोड में अधिसूचनाओं को प्रक्रिया करें

    • एजेंट Microsoft 365 अनुप्रयोगों से अधिसूचनाएँ प्राप्त करता है।
    • आने वाली सूचनाओं को संसाधित करें और उपयुक्त प्रतिक्रिया दें।

सूचना प्रकार

Agent 365 SDK निम्नलिखित सूचना प्रकारों का समर्थन करता है:

सूचना प्रकार विवरण उप-चैनल ID
ईमेल एजेंट को एक ईमेल प्राप्त होता है जिसमें उनका उल्लेख या उन्हें संबोधित किया गया है email
Word Word दस्तावेज़ में एक टिप्पणी में एजेंट का उल्लेख किया गया है word
Excel Excel दस्तावेज़ में एक टिप्पणी में एजेंट का उल्लेख किया गया है excel
PowerPoint PowerPoint दस्तावेज़ की एक टिप्पणी में एजेंट का उल्लेख किया गया है powerpoint
जीवनचक्र घटनाएँ एजेंट जीवनचक्र सूचनाएं (उपयोगकर्ता पहचान बनाई गई, कार्यभार ऑनबोर्डिंग, उपयोगकर्ता हटा दिया गया) N/A

एजेंट जीवनचक्र घटनाएं

एजेंट जीवनचक्र घटनाएँ आपके एजेंट को एजेंट उपयोगकर्ता पहचान प्रबंधन से संबंधित विशिष्ट सिस्टम घटनाओं का जवाब देने में सक्षम बनाती हैं। SDK टूल फ़िलहाल तीन जीवनचक्र इवेंट का समर्थन करता है:

इवेंट प्रकार इवेंट ID विवरण
उपयोगकर्ता पहचान बनाई गई 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: एजेंट्स 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 एंट्रा ऑब्जेक्ट आईडी

महत्त्वपूर्ण

डिस्प्ले नाम उपयोगकर्ता द्वारा नियंत्रित टेक्स्ट है। इसे एलएलएम सिस्टम प्रॉम्प्ट्स में सम्मिलित करने से पहले शुद्ध करें (नियंत्रण वर्ण हटाएँ, अधिकतम लंबाई निर्धारित करें) ताकि प्रॉम्प्ट इंजेक्शन हमलों को रोका जा सके।

टिप

Microsoft Graph API के साथ aadObjectId का उपयोग करें ताकि आपके एजेंट के पास उपयुक्त अनुमतियाँ होने पर विस्तारित प्रोफ़ाइल डेटा (जैसे नौकरी का शीर्षक, प्रबंधक, विभाग) प्राप्त किया जा सके।

विशिष्ट अधिसूचना हैंडलर्स

मूल अधिसूचना रूटिंग सेटअप करने के बाद, अधिक सूक्ष्म नियंत्रण के लिए विशेषीकृत हैंडलर विधियों का उपयोग करें। इन विधियों का उपयोग करके, आप यह कर सकते हैं:

  • एक ही अधिसूचना प्रकार के लिए एकाधिक हैंडलर पंजीकृत करें।
  • रैंकिंग का उपयोग करके हैंडलर प्राथमिकता सेट करें।
  • प्रत्येक हैंडलर के लिए स्वत: प्रमाणीकरण कॉन्फ़िगर करें।

नोट

अधिकांश उपयोग के मामलों के लिए, सामान्य हैंडलर पैटर्न पर्याप्त है। इन विशेष हैंडलर का उपयोग तब करें जब आपको एक ही अधिसूचना प्रकार के लिए उन्नत रूटिंग या एकाधिक हैंडलर की आवश्यकता हो।

सभी नोटिफ़िकेशन के लिए स्पेशल हैंडलर

ऐसे हैंडलर पंजीकृत करें जो सूचना के सभी प्रकार को प्रक्रिया करें:

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

नमूना कोड

सभी समर्थित फ्रेमवर्क के लिए अधिसूचना हैंडलिंग के पूर्ण कार्यशील उदाहरणों के लिए, Agent 365 Samples देखें।

सूचनाओं के साथ अपने एजेंट का परीक्षण करें

अधिसूचना हैंडलर लागू करने के बाद, यह सुनिश्चित करने के लिए अपने एजेंट का परीक्षण करें कि वह विभिन्न अधिसूचना प्रकारों को सही ढंग से प्राप्त करता है और संसाधित करता है। अपने वातावरण को सेटअप करने के लिए परीक्षण गाइड का पालन करें, और फिर मुख्य रूप से अधिसूचना गतिविधियों के साथ परीक्षण अनुभाग पर ध्यान केंद्रित करें ताकि एजेंटिक प्रमाणीकरण का उपयोग करके अपनी सूचनाओं को सत्यापित किया जा सके।

अधिसूचना हैंडलिंग की निगरानी करें

अपने एजेंट की अधिसूचना हैंडलिंग की निगरानी के लिए अवलोकन सुविधाएँ जोड़ें। एजेंट के प्रदर्शन को समझने के लिए अधिसूचना प्रसंस्करण, प्रतिक्रिया समय और त्रुटि दरों को ट्रैक करें। ट्रेसिंग और मॉनिटरिंग को लागू करने के बारे में अधिक जानें.

  • पिछली बार को अपडेट किया गया