הודע לסוכנים

באמצעות מודול ההתראות, ניתן לבנות סוכנים שמגיבים לאירועים והתראות מיישומי Microsoft 365. באמצעות תמיכה בהתראות, הסוכנים יכולים לקבל ולעבד התראות כאשר משתמשים יוצרים אינטראקציה איתם דרך דואר אלקטרוני, הערות במסמכים או תרחישים שיתופיים אחרים.

זרימת עבודה של התראות

עקבו אחר זרימת העבודה הזו כדי לאפשר התראות לאפליקציית סוכן AI שלכם:

התקן חבילות של התראות.
ייבא רכיבי התראות
- ייבא מחלקות התראות ומטפלים.
- ייבא סוגי פעילות ומזהי ערוצים.
רשום מטפלי התראות
- השתמש בשיטות של מטפל התראות כדי לרשום מסלולים.
- הגדר מטפלים לסוגי התראות מסוימים, כמו דואר אלקטרוני, Word, Excel או PowerPoint.
עיבוד התראות בקוד סוכן
- הסוכן מקבל התראות מיישומי Microsoft 365.
- טפל בהתראות נכנסות והגב בהתאם.

סוגי הודעה

ערכת הפיתוח של Agent 365 תומכת בסוגי ההתראות הבאים:

סוג הודעה	Description	מזהה ערוץ משני
דוא"ל	הסוכן מקבל הודעה שבה הוא מוזכר או שנשלחה אליו	`email`
Word	הסוכן מוזכר בתגובה במסמך Word	`word`
Excel	הסוכן מוזכר בתגובה במסמך Excel	`excel`
PowerPoint	הסוכן מוזכר בתגובה במסמך PowerPoint	`powerpoint`
אירועי מחזור חיים	התראות מחזור חיי סוכן (נוצר זהות משתמש, הטמעת עומס עבודה, מחיקה משתמש)	לא ישים

אירועי מחזור חיים של סוכן

אירועי מחזור חיים של סוכן מאפשרים לסוכן שלך להגיב לאירועי מערכת הקשורים לניהול זהות המשתמש של הסוכן. ה-SDK תומך כיום בשלושה אירועי מחזור חיים:

‏‏סוג אירוע‬	מזהה אירוע	Description
יצירת זהות משתמש	`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: ‏Enum של סוגי התראות נתמכים כמו EMAIL_NOTIFICATION, WPX_COMMENT.
ChannelId: השתמש כדי להגדיר ערוצי התראה, לדוגמה, ChannelId(channel="agents", sub_channel="*").
הרשאה: הקשר לאישור לעיבוד התראות.
TurnContext: הקשר של שיחות נוכחיות מתוך ערכת הפיתוח של הסוכנים.

import { AgentApplication, TurnContext, TurnState } from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { 
  AgentNotificationActivity,
  NotificationType
} from '@microsoft/agents-a365-notifications';

AgentApplication: מחלקת בסיס ליצירת אפליקציות Agent365. הוא מספק יכולות מרכזיות לניתוב פעילויות, ניהול מצב ועיבוד בקשות. השתמש ב-onAgentNotification() כדי לרשום מטפלים.
AgentNotification Activity: פעילות התראה מפורשת עם נתוני התראה מוכתבים בצורה חזקה. מאפיינים כמו emailNotification ו-wpxCommentNotification מכילים מטה-נתונים ספציפיים להתראות כגון מזהים, פרטי שיחה והפניות למסמכים.
סוג ההתראה: ‏Enum של סוגי התראות הכולל את Unknown, WpxComment, EmailNotification, AgentLifecycleNotification.
TurnContext: השיחה הנוכחית הופכת הקשר.
TurnState: ניהול מצבים עבור שיחה.

using Microsoft.Agents.Hosting;
using Microsoft.Agents.A365.Notifications;
using Microsoft.Agents.A365.Notifications.Extensions;
using Microsoft.Agents.A365.Notifications.Models;

AgentApplication: מחלקת בסיס ליצירת אפליקציות Agent365. הוא מספק יכולות מרכזיות לניתוב פעילויות, ניהול מצב ועיבוד בקשות. השתמש בשיטת OnAgentNotification כדי לרשום מטפלי אירועים.
AgentNotificationActivity: עוטף פעילות בנתוני התראה מוכתבים בצורה חזקה. Properties like EmailNotification and WpxCommentNotification מכילים מטה-נתונים ספציפיים להתראות כגון מזהים, פרטי שיחה והפניות למסמכים.
NotificationTypeEnum: ספירה של סוגי ההתראות הנתמכים, כולל Unknown, WpxComment, EmailNotification, AgentLifecycleNotification.
ITurnContext: ממשק המייצג את הקשר הפנייה הנוכחית בשיחה.
ITurnState: ממשק לניהול מצב שיחה.

רשום מטפלי התראות בסוכן שלך

הוסף מטפלי התראות בעת אתחול הסוכן:

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

export class YourAgent extends AgentApplication {
  constructor() {
    super();
    
    // Register notification handler
    this.onAgentNotification("*", async (context, state, notification) => {
      await this.handleAgentNotificationActivity(context, state, notification);
    });
  }
  
  async handleAgentNotificationActivity(context, state, notification) {
    // Route based on notification type
    switch (notification.notificationType) {
      case NotificationType.EmailNotification:
        await this.handleEmailNotification(context, state, notification);
        break;
      case NotificationType.WpxComment:
        await this.handleCommentNotification(context, state, notification);
        break;
      default:
        await context.sendActivity('Notification type not yet implemented.');
    }
  }
}

public class YourAgent : AgentApplication
{
    public YourAgent()
    {
        // Register notification handler
        this.OnAgentNotification(
            "*",
            HandleNotificationAsync
        );
    }
    
    private async Task HandleNotificationAsync(
        ITurnContext turnContext,
        ITurnState turnState,
        AgentNotificationActivity activity,
        CancellationToken cancellationToken)
    {
        // Route based on notification type
        switch (activity.NotificationType)
        {
            case NotificationTypeEnum.EmailNotification:
                await HandleEmailNotificationAsync(turnContext, turnState, activity, 
                    cancellationToken);
                break;
            case NotificationTypeEnum.WpxComment:
                await HandleCommentNotificationAsync(turnContext, turnState, activity, 
                    cancellationToken);
                break;
            default:
                await turnContext.SendActivityAsync("Notification type not yet implemented.", 
                    cancellationToken: cancellationToken);
                break;
        }
    }
}

יישום מטפלי התראות ספציפיים

הוסף שיטות מטפל לכל סוג התראה:

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

async handleEmailNotification(context, state, notification) {
  const email = notification.emailNotification;
  
  if (!email) {
    await context.sendActivity('No email data found');
    return;
  }
  
  // Process the email
  await context.sendActivity(`Received email notification. Email ID: ${email.id}`);
  
  // Your email processing logic here
}

async handleCommentNotification(context, state, notification) {
  const comment = notification.wpxCommentNotification;
  
  if (!comment) {
    await context.sendActivity('No comment data found');
    return;
  }
  
  // Process the comment
  await context.sendActivity(`Received comment. Document ID: ${comment.documentId}`);
  
  // Your comment processing logic here
}

private async Task HandleEmailNotificationAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    var email = activity.EmailNotification;
    
    if (email == null)
    {
        await turnContext.SendActivityAsync("No email data found", 
            cancellationToken: cancellationToken);
        return;
    }
    
    // Process the email
    await turnContext.SendActivityAsync(
        $"Received email notification. Email ID: {email.Id}",
        cancellationToken: cancellationToken
    );
    
    // Your email processing logic here
}

private async Task HandleCommentNotificationAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    var comment = activity.WpxCommentNotification;
    
    if (comment == null)
    {
        await turnContext.SendActivityAsync("No comment data found", 
            cancellationToken: cancellationToken);
        return;
    }
    
    // Process the comment
    await turnContext.SendActivityAsync(
        $"Received comment. Document ID: {comment.DocumentId}",
        cancellationToken: cancellationToken
    );
    
    // 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

async handleEmailNotification(context, state, notification) {
  const from = context.activity?.from;
  console.log(`Notification from — DisplayName: '${from?.name ?? "(unknown)"}', UserId: '${from?.id ?? "(unknown)"}', AadObjectId: '${from?.aadObjectId ?? "(none)"}'`);
  const displayName = from?.name ?? 'unknown';
  // Use displayName in your response or LLM prompt
}

Activity.from property הוא מופע של ממשק ChannelAccount עם המאפיינים הבאים:

מאפיין‬	Description
`name`	שם תצוגה
`id`	מזהה משתמש בערוץ
`aadObjectId`	מזהה אובייקט Entra

private async Task HandleEmailNotificationAsync(
    ITurnContext turnContext, ITurnState turnState,
    AgentNotificationActivity activity, CancellationToken cancellationToken)
{
    var from = turnContext.Activity.From;
    _logger.LogInformation(
        "Notification from — DisplayName: '{Name}', UserId: '{Id}', AadObjectId: '{AadObjectId}'",
        from?.Name ?? "(unknown)", from?.Id ?? "(unknown)", from?.AadObjectId ?? "(none)");

    var displayName = from?.Name ?? "unknown";
    // Use displayName in your response or LLM prompt
}

Activity.From_property הוא מופע של מחלקת ChannelAccount עם המאפיינים הבאים:

מאפיין‬	Description
From.Name	שם תצוגה
From.Id	מזהה משתמש בערוץ
From.AadObjectId	מזהה אובייקט Entra

חשוב

שם התצוגה הוא טקסט הנשלט על ידי המשתמש. נקה אותו (הסר תווי בקרה, אכוף אורך מקסימלי) לפני הזרקתו להנחיות מערכת LLM כדי למנוע התקפות הזרקת הנחיות.

עצה

השתמש ב-aadObjectId ב-API של Microsoft Graph כדי לאסוף נתוני פרופיל מורחבים (תפקיד, מנהל, מחלקה) כאשר לסוכן שלך יש הרשאות מתאימות.

מטפלי התראות ייעודיים

לאחר הגדרת ניתוב ההתראות הבסיסי, השתמש בשיטות טיפול ייעודיות לשליטה מדויקת יותר. באמצעות שיטות אלו, אתה יכול:

לרשום מספר מטפלים לאותו סוג התראה.
לקבוע עדיפות למטפלים באמצעות דירוג.
להגדיר אימות אוטומטי לכל מטפל.

הערה

ברוב מקרי השימוש, תבנית המטפל הגנרית מספיקה. השתמש במטפלים המיוחדים האלה כאשר דרוש ניתוב מתקדם או מספר מטפלים לאותו סוג ההתראה.

מטפל ייעודי לכל ההתראות

רשום עוד מטפלים שמעבדים את כל סוגי ההתראות:

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

import '@microsoft/agents-a365-notifications';

// Register handler for all notifications
app.onAgentNotification('*', async (context, state, notification) => {
  const { notificationType, emailNotification, wpxCommentNotification } = notification;

  switch (notificationType) {
    case NotificationType.EmailNotification:
      if (emailNotification) {
        console.log('Email ID:', emailNotification.id);
        await context.sendActivity('Processing your email...');
      }
      break;
    
    case NotificationType.WpxComment:
      if (wpxCommentNotification) {
        console.log('Comment ID:', wpxCommentNotification.commentId);
        await context.sendActivity('Responding to your comment...');
      }
      break;
  }
});

using Microsoft.Agents.A365.Notifications;
using Microsoft.Agents.A365.Notifications.Extensions;
using Microsoft.Agents.A365.Notifications.Models;

// Register handler for all notifications (wildcard)
this.OnAgentNotification(
    "*",
    AgentNotificationActivityAsync
);

private async Task AgentNotificationActivityAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    switch (activity.NotificationType)
    {
        case NotificationTypeEnum.EmailNotification:
            var email = activity.EmailNotification;
            if (email != null)
            {
                await turnContext.SendActivityAsync(
                    $"Received email: {email.Id}",
                    cancellationToken: cancellationToken
                );
            }
            break;
            
        case NotificationTypeEnum.WpxComment:
            var comment = activity.WpxCommentNotification;
            if (comment != null)
            {
                await turnContext.SendActivityAsync(
                    $"Received comment: {comment.CommentId}",
                    cancellationToken: cancellationToken
                );
            }
            break;
    }
}

מטפל ייעודי להתראות דוא"ל

רשום עוד מטפלים במיוחד עבור התראות בדוא"ל:

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!')

app.onAgenticEmailNotification(async (context, state, notification) => {
  const email = notification.emailNotification;

  if (!email) {
    await context.sendActivity('No email found');
    return;
  }

  // Process the email
  console.log('Email ID:', email.id);
  console.log('Conversation ID:', email.conversationId);

  // Send a response
  await context.sendActivity('Thank you for your email!');
});

// Register handler for email notifications
this.OnAgenticEmailNotification(HandleEmailNotificationAsync);

private async Task HandleEmailNotificationAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    var email = activity.EmailNotification;
    
    if (email == null)
    {
        await turnContext.SendActivityAsync("No email found", 
            cancellationToken: cancellationToken);
        return;
    }
    
    // Process email
    var emailId = email.Id;
    var conversationId = email.ConversationId;
    
    // Send response
    await turnContext.SendActivityAsync(
        "Thank you for your email!",
        cancellationToken: cancellationToken
    );
}

מטפלים ייעודיים להערות במסמכים

רשום עוד מטפלים לקבלת התראות על תגובות ב-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')

// Handle Word notifications
app.onAgenticWordNotification(async (context, state, notification) => {
  const comment = notification.wpxCommentNotification;
  
  if (comment) {
    console.log('Word comment:', comment.commentText);
    await context.sendActivity('Processing your Word comment...');
  }
});

// Handle Excel notifications
app.onAgenticExcelNotification(async (context, state, notification) => {
  const comment = notification.wpxCommentNotification;
  
  if (comment) {
    await context.sendActivity('Processing your Excel comment...');
  }
});

// Handle PowerPoint notifications
app.onAgenticPowerPointNotification(async (context, state, notification) => {
  const comment = notification.wpxCommentNotification;
  
  if (comment) {
    await context.sendActivity('Processing your PowerPoint comment...');
  }
});

// Register handlers for document notifications
this.OnAgenticWordNotification(HandleWordNotificationAsync);
this.OnAgenticExcelNotification(HandleExcelNotificationAsync);
this.OnAgenticPowerPointNotification(HandlePowerPointNotificationAsync);

private async Task HandleWordNotificationAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    var comment = activity.WpxCommentNotification;
    
    if (comment != null)
    {
        await turnContext.SendActivityAsync(
            $"Processing Word comment: {comment.CommentText}",
            cancellationToken: cancellationToken
        );
    }
}

private async Task HandleExcelNotificationAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    var comment = activity.WpxCommentNotification;
    
    if (comment != null)
    {
        await turnContext.SendActivityAsync(
            "Processing Excel comment",
            cancellationToken: cancellationToken
        );
    }
}

private async Task HandlePowerPointNotificationAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    var comment = activity.WpxCommentNotification;
    
    if (comment != null)
    {
        await turnContext.SendActivityAsync(
            "Processing PowerPoint comment",
            cancellationToken: cancellationToken
        );
    }
}

מטפלים ייעודיים לאירועי מחזור חיים

רשום עוד מטפלים לאירועי מחזור חיי סוכנים, כגון יצירת זהות משתמש, קליטת עומס עבודה ומחיקת משתמשים:

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')

// Handle all lifecycle notifications
app.onLifecycleNotification(async (context, state, notification) => {
  await context.sendActivity('Lifecycle event received');
});

// Handle specific lifecycle events
app.onAgenticUserCreatedNotification(async (context, state, notification) => {
  await context.sendActivity('User identity created');
});

app.onAgenticUserWorkloadOnboardingNotification(
  async (context, state, notification) => {
    await context.sendActivity('Workload onboarding completed');
  }
);

app.onAgenticUserIdentityDeletedNotification(
  async (context, state, notification) => {
    await context.sendActivity('User identity deleted');
  }
);

// Register lifecycle notification handlers
this.OnLifecycleNotification(HandleAllLifecycleEventsAsync);
this.OnAgenticUserIdentityCreatedNotification(HandleUserCreatedAsync);
this.OnAgenticUserWorkloadOnboardingNotification(HandleWorkloadOnboardingAsync);
this.OnAgenticUserDeletedNotification(HandleUserDeletedAsync);

private async Task HandleAllLifecycleEventsAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(
        "Lifecycle event received",
        cancellationToken: cancellationToken
    );
}

private async Task HandleUserCreatedAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(
        "User identity created",
        cancellationToken: cancellationToken
    );
}

private async Task HandleWorkloadOnboardingAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(
        "Workload onboarding completed",
        cancellationToken: cancellationToken
    );
}

private async Task HandleUserDeletedAsync(
    ITurnContext turnContext,
    ITurnState turnState,
    AgentNotificationActivity activity,
    CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(
        "User identity deleted",
        cancellationToken: cancellationToken
    );
}

תצורה מתקדמת

חלק זה עוסק באפשרויות קונפיגורציה מתקדמות לכיוונון מדויק של מטפלי ההתראות. באמצעות תצורות אלו, ניתן לשלוט בסדר הביצוע של המטפלים, לנהל דרישות אימות ולייעל את עיבוד ההתראות לתרחישים מורכבים.

עדיפות ודירוג המטפל

כאשר משתמשים במספר מטפלים מתמחים, יש לציין את סדר העדיפויות באמצעות ערכי דירוג. ככל שדרגת הדירוג נמוכה יותר, כך העדיפות גבוהה יותר:

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

// Higher priority handler (lower rank number)
app.onAgenticEmailNotification(
  async (context, state, notification) => {
    // Handle email with high priority
  },
  100 // rank
);

// Lower priority handler
app.onAgenticEmailNotification(
  async (context, state, notification) => {
    // Handle email with lower priority
  },
  200 // rank
);

// Higher priority handler (lower rank number)
this.OnAgenticEmailNotification(
    HighPriorityEmailHandlerAsync,
    rank: 100
);

// Lower priority handler
this.OnAgenticEmailNotification(
    LowerPriorityEmailHandlerAsync,
    rank: 200
);

מטפלי אימות

הגדר מטפלי כניסה אוטומטית להתראות שדורשות אימות:

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

app.onAgenticEmailNotification(
  async (context, state, notification) => {
    // Handler with automatic authentication
  },
  32767, // rank (default)
  ['agentic'] // autoSignInHandlers
);

this.OnAgenticEmailNotification(
    HandleAuthenticatedEmailAsync,
    rank: 32767,
    autoSignInHandlers: new[] { "agentic" }
);

דוגמת קוד

לעיון בדוגמאות מלאות של טיפול בהודעות בכל הפלטפורמות הנתמכות, ראה דוגמאות של Agent 365.

בדוק את הסוכן שלך עם התראות

לאחר יישום מטפלי התראות, בדוק את הסוכן שלך כדי לוודא שהוא מקבל ומעבד נכון סוגי התראות שונים. עקוב אחר מדריך הבדיקות כדי להגדיר את הסביבה והתמקד בעיקר בחלק בדיקות עם פעילויות התראות כדי לאמת את ההתראות באמצעות אימות אג'נטי.

ניטור הטיפול בהתראות

הוסף יכולות ניטור כדי לנטר את הטיפול בהתראות של הסוכן. עקוב אחרי עיבוד התראות, זמני תגובה ושיעורי שגיאה כדי להבין את ביצועי הסוכן. למד עוד על ישום מעקב וניטור.

משוב

האם עמוד זה היה מועיל?

Last updated on 2026-08-05