Powiadom agentów

Za pomocą modułu Notifications możesz tworzyć agentów, którzy reagują na zdarzenia i powiadomienia z aplikacji Microsoft 365. Dzięki obsłudze powiadomień agenci mogą otrzymywać i przetwarzać alerty, gdy użytkownicy wchodzą z nimi w interakcję przez e-mail, komentarze w dokumentach lub inne scenariusze współpracy.

Schemat przepływu powiadomień

Postępuj zgodnie z tym schematem, aby włączyć powiadomienia w aplikacji agenta AI:

  1. Zainstaluj pakiety aplikacji.

  2. Importuj komponenty powiadomień

    • Importuj klasy powiadomień i obsługi.
    • Importuj typy aktywności i identyfikatory kanałów.

  3. Obsługiwacze powiadomień rejestrów

    • Użyj metod obsługi powiadomień do rejestrowania ścieżek.
    • Konfiguruj obsługiwacze dla konkretnych typów powiadomień, takich jak e-mail, Word, Excel czy PowerPoint.

  4. Przetwarzaj powiadomienia w kodzie agenta

    • Agent otrzymuje powiadomienia od aplikacji Microsoft 365.
    • Obsługuj powiadomienia przychodzące i reaguj odpowiednio.

Typy powiadomień

Aplikacja SDK Agent 365 obsługuje następujące typy powiadomień:

Typ powiadomienia Podpis identyfikator kanału podrzędnego
E-mail Agent otrzymuje e-mail, w którym został wspomniany lub skierowany do niego email
Word Agent został wspomniany w komentarzu w dokumencie Worda word
Excel Agent został wspomniany w komentarzu w dokumencie Excel excel
PowerPoint Agent został wspomniany w komentarzu w dokumencie PowerPoint powerpoint
Wydarzenia cyklu życia Powiadomienia o cyklu życia agenta (utworzenie tożsamości użytkownika, uruchomienie obciążenia, usunięcie użytkownika) Brak

Zdarzenia cyklu życia agenta

Zdarzenia cyklu życia agenta pozwalają agentowi reagować na konkretne zdarzenia systemowe związane z zarządzaniem tożsamością użytkownika agenta. SDK obecnie wspiera trzy zdarzenia cyklu życia:

Typ zdarzenia Identyfikator zdarzenia Podpis
Tożsamość użytkownika utworzona agenticUserIdentityCreated Wyzwalane po utworzeniu tożsamości użytkownika agenta
Aktualizacja wdrożenia obciążenia pracą agenticUserWorkloadOnboardingUpdated Wyzwalane po aktualizacji statusu onboardingu użytkownika agenta
Usunięto użytkownika agenticUserDeleted Wyzwalane po usunięciu tożsamości użytkownika agenta

Te zdarzenia umożliwiają agentom wykonywanie zadań inicjalizacyjnych, operacji czyszczenia lub zarządzania stanem w odpowiedzi na zmiany cyklu życia użytkownika.

Preferencja dotycząca ładunku

Gdy Twój agent otrzymuje powiadomienie, ładunek zawiera dane strukturalne specyficzne dla typu powiadomienia. Zrozumienie struktury powiadomień pomaga uzyskać potrzebne informacje do ich efektywnego przetwarzania.

Ładunek powiadomień e-mail

Gdy użytkownik wysyła wiadomość e-mail do agenta lub wspomina o nim w wiadomości e-mail, agent otrzymuje powiadomienie e-mail o następującej strukturze:

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

Ładunek powiadomień o komentarzach dokumentów (Word, Excel, PowerPoint)

Gdy użytkownik wspomina Twojego agenta w komentarzu w dokumencie Word, Excel lub PowerPoint, Twój agent otrzymuje powiadomienie WPX (Word, PowerPoint, Excel) o komentarzu:

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

Dodaj powiadomienia do swojego agenta

Wykonaj poniższe kroki, aby włączyć obsługę powiadomień w swoim istniejącym agencie:

Importuj komponenty powiadomień

Dodaj poniższe importy do pliku agenta:

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: Klasa bazowa do tworzenia aplikacji Agent365. Zapewnia podstawową funkcjonalność do trasowania aktywności, zarządzania stanem i przetwarzania żądań.
  • AgentNotification: Klasa do rejestrowania handlerów powiadomień za pomocą metod dekoratorskich. Udostępnia on_agent_notification(), on_email(), on_word() oraz inne dekoratory ułatwiające pracę.
  • AgentNotificationActivity: Obiekt opakowujący przetworzone dane powiadomień z typowanymi właściwościami, takimi jak email_notification i wpx_comment_notification, które zawierają metadane specyficzne dla powiadomień, takie jak identyfikatory, szczegóły konwersacji i odwołania do dokumentów.
  • NotificationTypes: wyliczenie obsługiwanych typów powiadomień, takich jak EMAIL_NOTIFICATION, WPX_COMMENT.
  • ChannelId: Służy do określania kanałów powiadomień, na przykład, ChannelId(channel="agents", sub_channel="*").
  • Autoryzacja: Kontekst autoryzacji do przetwarzania powiadomień.
  • TurnContext: Aktualny kontekst tury konwersacji w Agents SDK.

Zarejestruj handlery powiadomień w agencie

Dodaj handlery powiadomień do inicjalizacji agenta:

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.')

Implementuj specyficzne handlery powiadomień

Dodaj metody obsługi dla każdego typu powiadomienia:

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

Zidentyfikuj nadawcę

Każda aktywność powiadomienia zawiera Activity.From. Platforma A365 uzupełnia tę właściwość podstawowymi danymi tożsamości nadawcy, więc nie potrzebujesz wywołań API ani pozyskiwania tokenów. Uzyskaj do niego dostęp w dowolnej metodzie obsługi powiadomień:

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 jest instancją klasy ChannelAccount, która posiada następujące właściwości:

Właściwość Description
name Nazwa wyświetlana
id Identyfikator użytkownika kanału
aad_object_id Identyfikator obiektu usługi Entra

Ważne

Nazwa wyświetlana to tekst definiowany przez użytkownika. Oczyść go (usuń znaki sterujące, ogranicz długość), zanim umieścisz go w poleceniach systemu LLM, aby zapobiec atakom typu polecenie injection.

Wskazówka

Użyj aadObjectId z interfejsem Microsoft interfejs Graph API, aby pobrać rozszerzone dane profilowe (stanowisko, przełożony, dział), gdy agent posiada odpowiednie uprawnienia.

Specjalistyczne obsługiwacze powiadomień

Po skonfigurowaniu podstawowego routingu powiadomień należy stosować specjalistyczne metody obsługi dla bardziej szczegółowej kontroli. Stosując te metody, możesz:

  • Zarejestruj wielu handlerów dla tego samego typu powiadomień.
  • Ustaw priorytet handlera za pomocą rankingu.
  • Skonfiguruj automatyczne uwierzytelnianie dla każdego handlera.

Notatka

W większości przypadków ogólny wzorzec handlera wystarczy. Używaj tych specjalistycznych obsług, gdy potrzebujesz zaawansowanego routingu lub kilku obsługiwaczy dla tego samego typu powiadomień.

Specjalistyczny obsługiwacz dla wszystkich powiadomień

Zarejestruj dodatkowe obsługiwacze, które przetwarzają wszystkie typy powiadomień:

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

Dedykowany obsługiwacz powiadomień e-mail

Zarejestruj dodatkowe obsługiwacze do obsługi powiadomień e-mail:

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!')

Specjalistyczne obsługiwacze komentarzy dokumentów

Zarejestruj więcej osób obsługujących komentarze w Wordzie, Excelu i 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')

Specjalizowane handlery dla zdarzeń cyklu życia

Zarejestruj więcej handlerów dla zdarzeń cyklu życia agenta, takich jak tworzenie tożsamości użytkownika, wdrażanie zadań oraz usuwanie użytkownika:

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

Konfiguracja zaawansowana

Ta sekcja obejmuje zaawansowane opcje konfiguracyjne umożliwiające precyzyjne dostrojenie handlerów powiadomień. Korzystając z tych konfiguracji, można kontrolować kolejność wykonywania handlerów, zarządzać wymaganiami uwierzytelniania oraz optymalizować przetwarzanie powiadomień w złożonych scenariuszach.

Priorytety i ranking handlerów

Gdy używasz wielu wyspecjalizowanych handlerów, określ kolejność ich wykonywania według wartości rangi. Im niższa wartość rangi, tym wyższy priorytet:

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

Obsługiwanie uwierzytelniania

Skonfiguruj handlery automatycznego logowania dla powiadomień wymagających uwierzytelnienia:

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

Przykładowy kod

Pełne, działające przykłady obsługi powiadomień dla wszystkich obsługiwanych struktur znajdziesz w Agent 365 Samples.

Testowanie agenta z powiadomieniami

Po zaimplementowaniu obsługi powiadomień przetestuj agenta, aby upewnić się, że poprawnie odbiera i przetwarza różne typy powiadomień. Postępuj zgodnie z przewodnikiem testów, aby skonfigurować swoje środowisko, a następnie skup się przede wszystkim na sekcji „Testowanie aktywności powiadomień”, aby zweryfikować swoje powiadomienia przy użyciu uwierzytelniania agentycznego.

Monitorowanie obsługi powiadomień

Dodaj funkcje obserwowalności, aby monitorować obsługę powiadomień przez agenta. Monitoruj przetwarzanie powiadomień, czasy odpowiedzi i wskaźniki błędów, aby zrozumieć wydajność agenta. Dowiedz się więcej o wdrażaniu śledzenia i monitoringu.

  • Last updated on