Aracılara bildirim gönderme

Bildirimler modülünü kullanarak, Microsoft 365 uygulamalarından gelen olaylara ve bildirimlere yanıt veren derleme aracıları oluşturabilirsiniz. Bildirim desteği sayesinde, aracılar, kullanıcılar e-posta, belge yorumları veya diğer işbirliği senaryoları yoluyla kendileriyle etkileşime girdiğinde uyarıları alabilir ve işleyebilir.

Bildirim iş akışı

AI destekli aracı uygulamanız için bildirimleri etkinleştirmek üzere aşağıdaki iş akışını takip edin:

Bildirim paketlerini yükleyin.
Bildirim bileşenlerini içeri aktarma
- Bildirim sınıflarını ve işleyicileri içeri aktarın.
- Etkinlik türlerini ve kanal tanımlayıcılarını içeri aktarın.
Bildirim işleyicilerini kaydetme
- Rotaları kaydolmak için bildirim işleyici yöntemlerini kullanın.
- E-posta, Word, Excel veya PowerPoint gibi belirli bildirim türleri için işleyicileri yapılandırın.
Aracı kodunda bildirimleri işleme
- Aracı, Microsoft 365 uygulamalarından bildirimler alır.
- Gelen bildirimleri işleyin ve uygun şekilde yanıtlayın.

Bildirim türleri

Agent 365 SDK'sı aşağıdaki bildirim türlerini desteklemektedir:

Bildirim türü	Açıklama	Alt Kanal Kimliği
E-posta	Aracı, kendisinden bahsedilen veya kendisine hitap edilen bir e-posta alır	`email`
Word	Word belgesindeki yorumda aracıdan bahsedilmiştir	`word`
Excel	Excel belgesindeki bir yorumda aracıdan bahsedilmiştir	`excel`
PowerPoint	PowerPoint belgesindeki bir yorumda aracıdan bahsedilmiştir	`powerpoint`
Yaşam Döngüsü Olayları	Aracı yaşam döngüsü bildirimleri (kullanıcı kimliği oluşturuldu, iş yükü ekleme, kullanıcı silindi)	Yok

Aracı yaşam döngüsü olayları

Aracı yaşam döngüsü olayları, aracınızın aracı kullanıcı kimliği yönetimiyle ilgili belirli sistem olaylarına yanıt vermesini sağlar. SDK şu anda üç yaşam döngüsü olayını desteklemektedir:

Olay türü	Olay Kimliği	Açıklama
Kullanıcı Kimliği Oluşturuldu	`agenticUserIdentityCreated`	Bir aracı kullanıcı kimliği oluşturulduğunda tetiklenir
İş Yükü Ekleme İşlemi Güncelleştirildi	`agenticUserWorkloadOnboardingUpdated`	Bir aracı kullanıcısının iş yükü ekleme durumu güncelleştirildiğinde tetiklenir
Kullanıcı Silindi	`agenticUserDeleted`	Bir aracı kullanıcı kimliği silindiğinde tetiklenir

Aracılar, bu etkinlikleri kullanarak kullanıcı yaşam döngüsündeki değişikliklere yanıt olarak başlatma görevlerini, temizleme işlemlerini veya durum yönetimini gerçekleştirebilirler.

Bildirim yükü referansı

Aracınız bir bildirim aldığında, yük, bildirim türüne özgü yapılandırılmış veriler içerir. Bu yükleri anlamak, bildirimleri etkili bir şekilde işlemek için ihtiyacınız olan bilgileri elde etmenize yardımcı olur.

E-posta bildirimi yükü

Bir kullanıcı aracınızla e-posta gönderdiğinde veya bir e-postada aracınızdan bahsettiğinde, aracınız aşağıdaki yapıya sahip bir e-posta bildirimi alır:

{
  "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>"
    }
  ]
}

Belge yorumu bildirim yükü (Word, Excel, PowerPoint)

Bir kullanıcı, Word, Excel veya PowerPoint belgesindeki bir yorumda aracınızdan bahsettiğinde, temsilciniz bir WPX (Word, PowerPoint, Excel) yorum bildirimini alır:

{
  "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"
    }
  ]
}

Aracınıza bildirimler ekleme

Mevcut aracınızda bildirim işleme özelliğini etkinleştirmek için aşağıdaki adımları izleyin:

Bildirim bileşenlerini içeri aktarma

Bu ithalatları aracı dosyanıza ekleyin:

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 uygulamaları geliştirmek için temel sınıf. Yönlendirme işlemleri, durum yönetimi ve isteklerin işlenmesi için temel işlevsellik sağlar.
AgentNotification: Dekoratör yöntemleri kullanarak bildirim işleyicilerini kaydolmaya yarayan sınıf. on_agent_notification(), on_email(), on_word() ve diğer kolaylık dekoratörlerini sağlar.
AgentNotificationActivity: Kimlikler, konuşma ayrıntıları ve belge başvuruları gibi bildirime özel meta verileri içeren email_notification ve wpx_comment_notification gibi türü belirtilmiş özelliklere sahip, ayrıştırılmış bildirim verilerini içeren sarmalayıcı.
NotificationTypes: EMAIL_NOTIFICATION ve WPX_COMMENT gibi desteklenen bildirim türlerinin sabit listesi.
ChannelId: Bildirim kanallarını belirtmek için kullanın; örneğin: ChannelId(channel="agents", sub_channel="*").
Yetkilendirme: Bildirimlerin işlenmesi için yetkilendirme bağlamı.
TurnContext: Aracılar SDK'sından alınan geçerli konuşma bağlamı.

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

AgentApplication: Agent365 uygulamaları geliştirmek için temel sınıf. Yönlendirme işlemleri, durum yönetimi ve isteklerin işlenmesi için temel işlevsellik sağlar. İşleyicileri kaydetmek için onAgentNotification() kullanın.
AgentNotificationActivity: Kesin tür belirtilmiş bildirim verileriyle ayrıştırılmış bildirim etkinliği. emailNotification ve wpxCommentNotification gibi özellikler; kimlikler, konuşma ayrıntıları ve belge başvuruları gibi bildirime özel meta verileri içerir.
NotificationType: Unknown, WpxComment, EmailNotification ve AgentLifecycleNotification dahil olmak üzere bildirim türlerini içeren sabit listesi.
TurnContext: Geçerli konuşma turu bağlamı.
TurnState: Konuşma için durum yönetimi.

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

AgentApplication: Agent365 uygulamaları geliştirmek için temel sınıf. Yönlendirme işlemleri, durum yönetimi ve isteklerin işlenmesi için temel işlevsellik sağlar. İşleyicileri kaydetmek için OnAgentNotification yöntemini kullanın.
AgentNotificationActivity: Bir etkinliği, kesin tür belirtilmiş bildirim verileriyle sarar. EmailNotification ve WpxCommentNotification gibi özellikler, kimlikler, konuşma ayrıntıları ve belge başvuruları gibi bildirime özel meta verileri içerir.
NotificationTypeEnum: Unknown, WpxComment, EmailNotification, AgentLifecycleNotification dahil olmak üzere desteklenen bildirim türlerinin numaralandırılması.
ITurnContext: Geçerli konuşma bağlamını temsil eden arabirim.
ITurnState: Konuşma durumu yönetimi için arabirim.

Aracınıza bildirim işleyicilerini kaydetme

Aracınızın başlatma işlemine bildirim işleyicileri ekleyin:

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;
        }
    }
}

Belirli bildirim işleyicilerini uygulama

Her bildirim türü için işleyici yöntemleri ekleyin:

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
}

Göndereni tanımlama

Her bildirim etkinliği Activity.From içerir. A365 platformu, bu özelliğe gönderenin temel kimlik bilgilerini otomatik olarak doldurur; bu sayede herhangi bir API çağrısı yapmanıza veya belirteç almanıza gerek kalmaz. Herhangi bir bildirim işleyicisi içinde buna erişin:

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 aşağıdaki özelliklere sahip bir ChannelAccount sınıfı örneğidir:

Özellik	Description
`name`	Görünen ad
`id`	Kanal kullanıcısı kimliği
`aad_object_id`	Entra Nesne Kimliği

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 özelliği, aşağıdaki özelliklere sahip bir ChannelAccount arabirimi örneğidir:

Özellik	Description
`name`	Görünen ad
`id`	Kanal kullanıcısı kimliği
`aadObjectId`	Entra Nesne Kimliği

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 özelliği,ChannelAccount sınıfı örneği olup aşağıdaki özelliklere sahiptir:

Özellik	Açıklama
From.Name	Görünen ad
From.Id	Kanal kullanıcısı kimliği
From.AadObjectId	Entra Nesne Kimliği

Önemli

Görünen ad, kullanıcı kontrolüyle belirlenmiş bir metindir. İstem enjeksiyonu saldırılarını önlemek için LLM sisteminin komut istemlerine eklemeden önce içeriği temizleyin (denetim karakterlerini kaldırın, maksimum uzunluk sınırını uygulayın).

İpucu

Aracınızın uygun izinlere sahip olduğu durumlarda, genişletilmiş profil verilerini (iş unvanı, yönetici, departman) almak için Microsoft Graph API ile birlikte aadObjectId kullanın.

Özel bildirim işleyiciler

Temel bildirim yönlendirmesini ayarladıktan sonra, daha ayrıntılı denetim için özelleştirilmiş işleyici yöntemlerini kullanın. Bu yöntemleri kullanarak şunları yapabilirsiniz:

Aynı bildirim türü için birden fazla işleyici kaydolun.
Sıralama yöntemini kullanarak işleyici önceliğini belirleyin.
Her bir işleyici için otomatik kimlik doğrulamayı yapılandırın.

Not

Çoğu kullanım örneği için genel işleyici deseni yeterlidir. Gelişmiş yönlendirme gerekiyorsa veya aynı bildirim türü için birden fazla işleyici kullanmanız gerektiğinde bu özel işleyicileri kullanın.

Tüm bildirimler için özel işleyici

Tüm bildirim türlerini işleyen daha fazla işleyici kaydolun:

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;
    }
}

E-posta bildirimleri için özel işleyici

E-posta bildirimleri için özel olarak daha fazla işleyici kaydolun:

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

Belge yorumları için özel işleyiciler

Word, Excel ve PowerPoint yorum bildirimleri için daha fazla işleyici kaydolun:

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

Yaşam döngüsü olayları için özel işleyiciler

Kullanıcı kimliği oluşturma, iş yükü ekleme ve kullanıcı silme gibi aracı yaşam döngüsü olayları için daha fazla işleyici kaydolun:

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

Gelişmiş yapılandırma

Bu bölüm, bildirim işleyicilerinizi daha hassas bir şekilde ayarlamak için kullanılan gelişmiş yapılandırma seçeneklerini ele almaktadır. Bu yapılandırmaları kullanarak, işleyici yürütme sırasını kontrol edebilir, kimlik doğrulama gereksinimlerini yönetebilir ve karmaşık senaryolar için bildirim işleme sürecini optimize edebilirsiniz.

İşleyici önceliği ve sıralaması

Birden fazla özel işleyici kullandığınızda, öncelik sırasını sıralama değerlerini kullanarak belirleyin. Daha düşük sıra değerleri, yüksek öncelik gösterir:

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

Kimlik doğrulama işleyicileri

Kimlik doğrulaması gerektiren bildirimler için otomatik oturum açma işleyicilerini yapılandırın:

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

Örnek kod

Desteklenen tüm çerçevelerde bildirim işleme süreçlerine ilişkin eksiksiz ve çalışan örnekler için Agent 365 Örnekleri bölümüne bakın.

Aracınızı bildirimlerle test etme

Bildirim işleyicilerini uyguladıktan sonra, aracının farklı bildirim türlerini doğru bir şekilde alıp işlediğinden emin olmak için aracıyı test edin. Ortamınızı ayarlamak için test kılavuzunu izleyin, ardından bildirimlerinizi aracı kimlik doğrulaması kullanarak doğrulamak için öncelikli olarak Bildirim etkinlikleriyle test etme bölümüne odaklanın.

Bildirim işleme sürecini izleme

Aracınızın bildirim işleme sürecini izlemek için gözlemlenebilirlik işlevini ekleyin. Aracıların performansını değerlendirmek için bildirim işleme sürecini, yanıt sürelerini ve hata oranlarını takip edin. Takip ve izlemenin nasıl uygulanacağı hakkında daha fazla bilgi edinin.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-30