Уведомить агентов

Используя модуль уведомлений, вы можете создавать агенты, которые реагируют на события и уведомления из приложений Microsoft 365. Используя поддержку уведомлений, агенты могут получать и обрабатывать оповещения при взаимодействии пользователей с ними через электронную почту, документирование комментариев или другие совместные сценарии.

Рабочий процесс уведомлений

Выполните этот рабочий процесс, чтобы включить уведомления для приложения агента ИИ:

  1. Установите пакеты уведомлений.

  2. Импорт компонентов уведомлений

    • Импортные классы уведомлений и обработчики.
    • Типы активности импорта и идентификаторы каналов.

  3. Регистрация обработчиков уведомлений

    • Используйте методы обработчика уведомлений для регистрации маршрутов.
    • Настройте обработчики для определённых типов уведомлений, таких как электронная почта, Word, Excel или PowerPoint.

  4. Обработка уведомлений в коде агента

    • Агент получает уведомления от приложений Microsoft 365.
    • Обрабатывайте входящие уведомления и реагируйте соответствующим образом.

Типы уведомлений

SDK Agent 365 поддерживает следующие типы уведомлений:

Тип уведомления Description Идентификатор Sub-Channel
Адрес эл. почты Агент получает электронное письмо, в котором он упоминается или адресован email
Слово Агент упоминается в комментарии в документе Word word
Excel Агент упоминается в комментарии в документе Excel excel
PowerPoint Агент упоминается в комментарии в документе PowerPoint powerpoint
События жизненного цикла Уведомления жизненного цикла агента (создание идентификации пользователя, подключение рабочей нагрузки, удаление пользователя) N/A

События жизненного цикла агента

События жизненного цикла агента позволяют вашему агенту реагировать на конкретные системные события, связанные с управлением идентификацией пользователей агента. В настоящее время пакет 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 содержащие специфические для уведомления метаданные, такие как идентификаторы, детали разговора и ссылки на документы.
  • Типы уведомлений: Перечисление поддерживаемых типов уведомлений, таких EMAIL_NOTIFICATIONкак , WPX_COMMENT.
  • ChannelId: Используйте для указания каналов уведомлений, например, ChannelId(channel="agents", sub_channel="*").
  • Авторизация: Контекст авторизации для обработки уведомлений.
  • TurnContext: Текущий контекст разговора из SDK агента.

Зарегистрируйте обработчики уведомлений в агенте

Добавьте обработчики уведомлений в инициализацию агента:

class YourAgent(AgentApplication):
    def __init__(self, app):
        # Create notification handler
        agent_notification = AgentNotification(app)
        
        # Register handler for all notifications
        @agent_notification.on_agent_notification(
            ChannelId(channel="agents", sub_channel="*")
        )
        async def handle_all_notifications(context, state, notification):
            # Route based on notification type
            if notification.notification_type == NotificationTypes.EMAIL_NOTIFICATION:
                await self.handle_email_notification(context, state, notification)
            elif notification.notification_type == NotificationTypes.WPX_COMMENT:
                await self.handle_comment_notification(context, state, notification)
            else:
                await context.send_activity('Notification type not yet implemented.')

Реализация конкретных обработчиков уведомлений

Добавьте методы обработчика для каждого типа уведомления:

class YourAgent(AgentApplication):
    # ... __init__ from above ...
    
    async def handle_email_notification(self, context, state, notification):
        """Handle email notifications"""
        email = notification.email_notification
        
        if not email:
            await context.send_activity('No email data found')
            return
        
        # Process the email
        await context.send_activity(
            f'Received email notification. Email ID: {email.id}'
        )
        
        # Your email processing logic here
    
    async def handle_comment_notification(self, context, state, notification):
        """Handle document comment notifications"""
        comment = notification.wpx_comment_notification
        
        if not comment:
            await context.send_activity('No comment data found')
            return
        
        # Process the comment
        await context.send_activity(
            f'Received comment notification. Document ID: {comment.document_id}'
        )
        
        # Your comment processing logic here

Определите отправителя

Каждая активность уведомления включает Activity.From. Платформа A365 заполняет это свойство базовой идентификацией отправителя, поэтому вам не нужны вызовы API или сбор токенов. Получите доступ к нему внутри любого обработчика уведомлений:

async def handle_email_notification(self, context, state, notification):
    from_prop = context.activity.from_property
    logger.info(
        "Notification from — DisplayName: '%s', UserId: '%s', AadObjectId: '%s'",
        getattr(from_prop, "name", None) or "(unknown)",
        getattr(from_prop, "id", None) or "(unknown)",
        getattr(from_prop, "aad_object_id", None) or "(none)",
    )
    display_name = getattr(from_prop, "name", None) or "unknown"
    # Use display_name in your response or LLM prompt

Activity.from_property — это экземпляр класса ChannelAccount с следующими свойствами:

Свойство Description
name Показать имя
id Идентификатор пользователя канала
aad_object_id Идентификатор объекта Entra

Это важно

Отображаемое имя — это текст, управляемый пользователем. Прочистить его (удалить контрольные символы, обеспечить максимальную длину) перед вводом в системные запросы LLM, чтобы предотвратить атаки prompt injection.

Подсказка

Используйте aadObjectId с Microsoft API 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}")

Специализированный обработчик уведомлений по электронной почте

Зарегистрируйте дополнительные обработчики, специально предназначенные для уведомлений по электронной почте:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Use the convenience method for email notifications
@agent_notification.on_email()
async def handle_email(context, state, notification):
    email = notification.email_notification
    
    if not email:
        await context.send_activity('No email found')
        return
    
    # Process the email
    email_id = email.id
    conversation_id = email.conversation_id
    
    # Send response
    await context.send_activity('Thank you for your email!')

Специализированные обработчики для комментариев к документу

Зарегистрируйте дополнительные обработчики для уведомлений о комментариях Word, Excel и PowerPoint:

from microsoft_agents_a365.notifications import AgentNotification

# Create notification handler
agent_notification = AgentNotification(app)

# Use convenience methods for document notifications
@agent_notification.on_word()
async def handle_word(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        document_id = comment.document_id
        comment_id = comment.comment_id
        await context.send_activity(f'Processing Word comment: {comment_id}')

@agent_notification.on_excel()
async def handle_excel(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        await context.send_activity('Processing Excel comment')

@agent_notification.on_powerpoint()
async def handle_powerpoint(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        await context.send_activity('Processing PowerPoint comment')

Специализированные обработчики для событий жизненного цикла

Зарегистрируйте больше обработчиков для событий жизненного цикла агента, таких как создание идентификации пользователя, онбординг рабочей нагрузки и удаление пользователей:

from microsoft_agents_a365.notifications import AgentNotification

# Create notification handler
agent_notification = AgentNotification(app)

# Handle all lifecycle events
@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
    lifecycle_notification = notification.agent_lifecycle_notification
    if lifecycle_notification:
        event_type = lifecycle_notification.lifecycle_event_type
        
        if event_type == "agenticUserIdentityCreated":
            await context.send_activity('User identity created')
        elif event_type == "agenticUserWorkloadOnboardingUpdated":
            await context.send_activity('Workload onboarding completed')
        elif event_type == "agenticUserDeleted":
            await context.send_activity('User identity deleted')

Расширенная конфигурация

В этом разделе рассматриваются дополнительные параметры конфигурации для точной настройки обработчиков уведомлений. Используя эти конфигурации, вы можете контролировать порядок выполнения обработчика, управлять требованиями к аутентификации и оптимизировать обработку уведомлений для сложных сценариев.

Приоритет обработчика и ранжирование

Когда вы используете несколько специализированных обработчиков, указывайте порядок приоритета, используя значения ранга. Ниже значения ранга указывают на более высокий приоритет:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Higher priority handler (processed first)
@agent_notification.on_email(rank=100)
async def high_priority_email(context, state, notification):
    # Handle with high priority
    pass

# Lower priority handler (processed after higher priority)
@agent_notification.on_email(rank=200)
async def low_priority_email(context, state, notification):
    # Handle with lower priority
    pass

Обработчики проверки подлинности

Настройте обработчики автоматического входа для уведомлений, требующих проверки подлинности:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Handler with automatic authentication
@agent_notification.on_email(auto_sign_in_handlers=['agentic'])
async def authenticated_email(context, state, notification):
    # Authentication is handled automatically
    pass

Пример кода

Полные рабочие примеры обработки уведомлений во всех поддерживаемых фреймворках см. образцы агента 365.

Проверьте возможности вашего агента с помощью уведомлений

После реализации обработчиков уведомлений проверьте агент, чтобы убедиться, что он правильно получает и обрабатывает различные типы уведомлений. Следуйте руководству по тестированию для настройки среды, а затем сосредоточьтесь в основном на разделе «Тест с уведомлениями » для проверки уведомлений с помощью агентной аутентификации.

Мониторинг обработки уведомлений

Добавьте возможности наблюдаемости для мониторинга обработки уведомлений вашим агентом. Отслеживайте обработку уведомлений, время отклика и частоту ошибок, чтобы понять производительность агента. Узнайте больше о внедрении трассировки и мониторинга.

  • Last updated on