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

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

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

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

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

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

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

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

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

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

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

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

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

Тип уведомления Описание ИД субканала
Электронная почта Агент получает электронное письмо, в котором его упоминают или которое ему адресовано 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: оболочка, включающая разобранные данные уведомления с типизированными свойствами, например email_notification и wpx_comment_notification, содержащими специфические для уведомления метаданные, такие как идентификаторы, сведения о разговоре и ссылки на документы.
  • NotificationTypes: перечисление поддерживаемых типов уведомлений, таких как EMAIL_NOTIFICATION, WPX_COMMENT.
  • ChannelId: используется для указания каналов уведомлений, например ChannelId(channel="agents", sub_channel="*").
  • Authorization: контекст авторизации для обработки уведомлений.
  • 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 со следующими свойствами:

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

Важно

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

Совет

Используйте aadObjectId вместе с API Microsoft Graph для получения расширенных данных профиля (должность, менеджер, отдел), если у вашего агента есть соответствующие разрешения.

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

После настройки базовой маршрутизации уведомлений используйте специализированные методы обработки для более тонкого контроля. С помощью этих методов вы можете:

  • Регистрировать несколько обработчиков для одного типа уведомлений.
  • Установить приоритет обработчика путем ранжирования.
  • Настроить автоматическую аутентификацию для каждого обработчика.

Примечание

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

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

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

from microsoft_agents_a365.notifications import (
    AgentNotification,
    NotificationTypes
)
from microsoft_agents.activity import ChannelId

# Create notification handler
agent_notification = AgentNotification(app)

# Register handler for all notifications
@agent_notification.on_agent_notification(
    ChannelId(channel="agents", sub_channel="*")
)
async def handle_all_notifications(context, state, notification):
    if notification.notification_type == NotificationTypes.EMAIL_NOTIFICATION:
        if notification.email_notification:
            await context.send_activity(f"Received email: {notification.email_notification.id}")
    elif notification.notification_type == NotificationTypes.WPX_COMMENT:
        if notification.wpx_comment_notification:
            await context.send_activity(f"Received comment: {notification.wpx_comment_notification.comment_id}")

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

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

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

Пример кода

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

Тестирование агента с уведомлениями

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

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

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

  • Last updated on