แจ้งเอเจนต์

คุณสามารถสร้างเอเจนต์ที่ตอบสนองต่อเหตุการณ์และการแจ้งเตือนจากแอปพลิเคชัน Microsoft 365 ได้โดยการใช้โมดูลการแจ้งเตือน เอเจนต์สามารถรับและประมวลผลการแจ้งเตือนเมื่อผู้ใช้โต้ตอบกับพวกเขาผ่านอีเมล ความคิดเห็นในเอกสาร หรือสถานการณ์การทํางานร่วมกันอื่นๆ ด้วยการใช้การสนับสนุนการแจ้งเตือน

เวิร์กโฟลว์การแจ้งเตือน

ทําตามเวิร์กโฟลว์นี้เพื่อเปิดใช้งานการแจ้งเตือนสําหรับแอปพลิเคชันเอเจนต์ AI ของคุณ:

ติดตั้งแพคเกจการแจ้งเตือน
นําเข้าส่วนประกอบการแจ้งเตือน
- นำเข้าประเภทการแจ้งเตือนและตัวจัดการ
- นําเข้าประเภทกิจกรรมและตัวระบุช่องทาง
ลงทะเบียนตัวจัดการการแจ้งเตือน
- ใช้วิธีการของตัวจัดการการแจ้งเตือนเพื่อลงทะเบียนเส้นทาง
- กำหนดค่าตัวจัดการสำหรับประเภทการแจ้งเตือนเฉพาะ เช่น อีเมล, Word, Excel หรือ PowerPoint
ประมวลผลการแจ้งเตือนในโค้ดของเอเจนต์
- เอเจนต์ได้รับการแจ้งเตือนจากแอปพลิเคชัน 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: Wrapper ที่มีข้อมูลการแจ้งเตือนที่แยกวิเคราะห์ด้วยคุณสมบัติที่พิมพ์ เช่น email_notification และ wpx_comment_notification ที่มีเมตาดาต้าเฉพาะการแจ้งเตือน เช่น รหัสรายละเอียดการสนทนา และการอ้างอิงเอกสาร
NotificationTypes: การแจงนับประเภทการแจ้งเตือนที่รองรับ เช่น EMAIL_NOTIFICATION, WPX_COMMENT
ChannelId: ใช้เพื่อระบุช่องทางการแจ้งเตือน เช่น ChannelId(channel="agents", sub_channel="*")
Authorization: บริบทการอนุญาตสำหรับการประมวลผลการแจ้งเตือน
TurnContext: บริบทของรอบสนทนาปัจจุบันจาก SDK เอเจนต์

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() ในการลงทะเบียนตัวจัดการ
AgentNotificationActivity: กิจกรรมการแจ้งเตือนที่แยกวิเคราะห์โดยใช้ข้อมูลการแจ้งเตือนที่มีประเภทชัดเจน คุณสมบัติต่างๆ เช่น emailNotification และ wpxCommentNotification มีเมตาดาต้าเฉพาะสำหรับการแจ้งเตือน เช่น รหัส รายละเอียดการสนทนา และการอ้างอิงเอกสาร
NotificationType: การแจงนับประเภทการแจ้งเตือน ได้แก่ 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: ครอบกิจกรรมด้วยข้อมูลการแจ้งเตือนที่มีชนิดข้อมูลที่ระบุอย่างชัดเจน คุณสมบัติต่างๆ เช่น EmailNotification และ 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 เป็นอินสแตนซ์ของ ส่วนติดต่อ 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 เป็นอินสแตนซ์ของ ประเภท ChannelAccount ที่มีคุณสมบัติต่อไปนี้:

คุณสมบัติ	คำอธิบาย
From.Name	ชื่อที่แสดง
From.Id	รหัสช่องทางของผู้ใช้
From.AadObjectId	รหัสออบเจ็กต์ 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}")

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-07-30