エージェントへの通知

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 などの型指定されたプロパティを持ち、通知固有のメタデータ (ID、会話詳細、ドキュメント参照) を含みます。
• NotificationTypes: サポートされている通知の種類 (EMAIL_NOTIFICATION、WPX_COMMENT) の列挙型。
• ChannelId: 通知チャネルを指定するために使用されます (ChannelId(channel="agents", sub_channel="*") など)。
• 承認: 通知を処理する承認コンテキスト。
• 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 などのプロパティには、ID、会話の詳細、ドキュメント参照など、通知固有のメタデータが含まれています。
• 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 などのプロパティには、ID、会話の詳細、ドキュメント参照など通知固有のメタデータが含まれています。
• NotificationTypeEnum: NotificationTypeEnum: サポートされている通知の種類の列挙 (Unknown、WpxComment、EmailNotification、AgentLifecycleNotification)。
• ITurnContext: ITurnContext: 現在の会話ターン コンテキストを表すインターフェイス。
• ITurnState: 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
}

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 クラスのインスタンスです:

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 インターフェースのインスタンスで、以下のプロパティを持っています。

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

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