Ειδοποιήστε παράγοντες

Χρησιμοποιώντας τη λειτουργική μονάδα Ειδοποιήσεις, μπορείτε να δημιουργήσετε παράγοντες που ανταποκρίνονται σε συμβάντα και ειδοποιήσεις από εφαρμογές του Microsoft 365. Χρησιμοποιώντας την υποστήριξη ειδοποιήσεων, οι παράγοντες μπορούν να λαμβάνουν και να επεξεργάζονται ειδοποιήσεις όταν οι χρήστες αλληλεπιδρούν μέσω email, σχολίων εγγράφων ή άλλων συνεργατικών σεναρίων.

Ροή εργασιών ειδοποιήσεων

Ακολουθήστε αυτήν τη ροή εργασίας για να ενεργοποιήσετε τις ειδοποιήσεις για την εφαρμογή παράγοντα AI:

  1. Εγκατάσταση πακέτων ειδοποιήσεων.

  2. Εισαγωγή στοιχείων ειδοποίησης

    • Εισαγάγετε κλάσεις ειδοποιήσεων και χειριστές.
    • Εισαγάγετε τύπους δραστηριότητας και αναγνωριστικά καναλιών.

  3. Καταχωρίστε χειριστές ειδοποιήσεων

    • Χρησιμοποιήστε μεθόδους χειρισμού ειδοποιήσεων για να καταχωρίσετε διαδρομές.
    • Ρυθμίστε τους χειριστές για συγκεκριμένους τύπους ειδοποιήσεων, όπως email, Word, Excel ή PowerPoint.

  4. Επεξεργασία ειδοποιήσεων στον κώδικα του παράγοντα

    • Ο παράγοντας λαμβάνει ειδοποιήσεις από εφαρμογές του Microsoft 365.
    • Χειριστείτε τις εισερχόμενες ειδοποιήσεις και απαντήστε κατάλληλα.

Τύποι ειδοποιήσεων

Το Agent 365 SDK υποστηρίζει τους ακόλουθους τύπους ειδοποιήσεων:

Τύπος ειδοποίησης Περιγραφή Αναγνωριστικό δευτερεύοντος καναλιού
Email Ο παράγοντας λαμβάνει ένα email στο οποίο αναφέρεται ή του απευθύνονται email
Word Ο παράγοντας αναφέρεται σε ένα σχόλιο σε ένα έγγραφο του Word word
Excel Ο παράγοντας αναφέρεται σε ένα σχόλιο σε ένα έγγραφο του Excel excel
PowerPoint Ο παράγοντας αναφέρεται σε ένα σχόλιο σε ένα έγγραφο του PowerPoint powerpoint
Συμβάντα κύκλου ζωής Ειδοποιήσεις κύκλου ζωής παράγοντα (δημιουργία ταυτότητας χρήστη, προσθήκη φόρτου εργασίας, διαγραφή χρήστη) ΔΙ

Συμβάντα κύκλου ζωής παράγοντα

Τα συμβάντα κύκλου ζωής παράγοντα επιτρέπουν στον παράγοντα σας να ανταποκρίνεται σε συγκεκριμένα συμβάντα συστήματος που σχετίζονται με τη διαχείριση ταυτότητας χρήστη παράγοντα. Το SDK επί του παρόντος υποστηρίζει τρία συμβάντα κύκλου ζωής:

Τύπος συμβάντος Αναγνωριστικό συμβάντος Περιγραφή
Δημιουργία ταυτότητας χρήστη agenticUserIdentityCreated Ενεργοποιείται όταν δημιουργείται η ταυτότητα χρήστη παράγοντα
Ενημερώθηκε το onboarding φόρτου εργασίας agenticUserWorkloadOnboardingUpdated Ενεργοποιείται όταν ενημερώνεται η κατάσταση onboarding του φόρτου εργασίας ενός χρήστη παράγοντα
Ο χρήστης διαγράφηκε agenticUserDeleted Ενεργοποιείται όταν διαγράφεται η ταυτότητα χρήστη παράγοντα

Χρησιμοποιώντας αυτά τα συμβάντα, οι παράγοντες μπορούν να εκτελούν εργασίες αρχικοποίησης, λειτουργίες καθαρισμού ή διαχείριση κατάστασης ως απόκριση σε αλλαγές στον κύκλο ζωής του χρήστη.

Αναφορά ωφέλιμου φορτίου της ειδοποίησης

Όταν ο παράγοντας σας λαμβάνει μια ειδοποίηση, το φορτίο περιέχει δομημένα δεδομένα ειδικά για τον τύπο της ειδοποίησης. Η κατανόηση αυτών των φορτίων σας βοηθά να εξαγάγετε τις πληροφορίες που χρειάζεστε για να επεξεργαστείτε τις ειδοποιήσεις αποτελεσματικά.

Φορτίο ειδοποίησης ηλεκτρονικού ταχυδρομείου

Όταν ένας χρήστης στέλνει ένα email στον παράγοντα σας ή αναφέρει τον παράγοντα σας σε ένα email, ο παράγοντας σας λαμβάνει μια ειδοποίηση email με την εξής δομή:

{
  "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 που έχει τις ακόλουθες ιδιότητες:

Ιδιότητα Description
name Εμφανιζόμενο όνομα
id Αναγνωριστικό χρήστη καναλιού
aad_object_id Αναγνωριστικό αντικειμένου Entra

Σημαντικό

Το εμφανιζόμενο όνομα είναι κείμενο που ελέγχεται από το χρήστη. Καθαρίστε το (αφαιρέστε χαρακτήρες ελέγχου, επιβάλλετε ένα μέγιστο μήκος) πριν το εισάγετε στις προτροπές συστήματος του LLM για να αποτρέψετε επιθέσεις εισαγωγής προτροπών.

Φιλοδώρημα

Χρησιμοποιήστε το aadObjectId με το Microsoft Graph API για να ανακτήσετε εκτεταμένα δεδομένα προφίλ (τίτλος εργασίας, διευθυντής, τμήμα) όταν ο παράγοντας σας έχει τα κατάλληλα δικαιώματα.

Εξειδικευμένοι χειριστές ειδοποιήσεων

Αφού ρυθμίσετε τη βασική δρομολόγηση ειδοποιήσεων, χρησιμοποιήστε εξειδικευμένες μεθόδους χειρισμού για λεπτομερέστερο έλεγχο. Χρησιμοποιώντας αυτές τις μεθόδους, μπορείτε να κάνετε τα εξής:

  • Εγγράψτε πολλούς χειριστές για τον ίδιο τύπο ειδοποίησης.
  • Ορίστε την προτεραιότητα των χειριστών χρησιμοποιώντας την κατάταξη.
  • Ρυθμίστε τον αυτόματο έλεγχο ταυτότητας για κάθε χειριστή.

Σημείωμα

Στις περισσότερες περιπτώσεις χρήσης, το γενικό πρότυπο χειριστή είναι επαρκές. Χρησιμοποιήστε αυτούς τους εξειδικευμένους χειριστές όταν απαιτείται προηγμένη δρομολόγηση ή πολλαπλοί χειριστές για τον ίδιο τύπο ειδοποίησης.

Εξειδικευμένος χειριστής για όλες τις ειδοποιήσεις

Καταχωρίστε περισσότερους χειριστές που επεξεργάζονται όλους τους τύπους ειδοποιήσεων:

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}")

Εξειδικευμένος χειριστής για ειδοποιήσεις email

Καταχωρίστε περισσότερους χειριστές ειδικά για ειδοποιήσεις email:

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.

Δοκιμάστε τον παράγοντας σας με ειδοποιήσεις

Αφού υλοποιήσετε τους χειριστές ειδοποιήσεων, δοκιμάστε τον παράγοντα σας για να βεβαιωθείτε ότι λαμβάνει και επεξεργάζεται σωστά διαφορετικούς τύπους ειδοποιήσεων. Ακολουθήστε τον οδηγό δοκιμών για να ρυθμίσετε το περιβάλλον σας, και στη συνέχεια εστιάστε κυρίως στην ενότητα Δοκιμή με δραστηριότητες ειδοποιήσεων για να επικυρώσετε τις ειδοποιήσεις σας χρησιμοποιώντας αυθεντικοποίηση παράγοντα.

Παρακολουθήστε τον χειρισμό ειδοποιήσεων

Προσθέστε δυνατότητες παρατηρησιμότητας για να παρακολουθείτε τον χειρισμό ειδοποιήσεων του παράγοντα σας. Παρακολουθήστε την επεξεργασία ειδοποιήσεων, τους χρόνους απόκρισης και τα ποσοστά σφαλμάτων για να κατανοήσετε την απόδοση του παράγοντα. Μάθετε περισσότερα για την υλοποίηση ιχνηλάτησης και παρακολούθησης.

  • Last updated on