Upozornit agenty

Pomocí modulu oznámení můžete vytvářet agenty, kteří reagují na události a oznámení z aplikací Microsoft 365. Díky podpoře oznámení mohou agenti přijímat a zpracovávat upozornění, když s nimi uživatelé komunikují prostřednictvím e-mailu, komentářů k dokumentům nebo dalších scénářů spolupráce.

Pracovní postup oznámení

Chcete-li ve své aplikaci agenta AI povolit oznámení, postupujte podle následujícího postupu:

  1. Instalovat balíčky aplikací.

  2. Komponenty oznámení o importu

    • Importovat třídy oznámení a obslužné rutiny.
    • Importovat typy aktivit a identifikátory kanálů.

  3. Registrujte obslužné rutiny oznámení

    • Používejte metody obslužné rutiny oznámení k registraci tras.
    • Konfigurujte obslužné rutiny pro konkrétní typy oznámení, například e-mail, Word, Excel nebo PowerPoint.

  4. Zpracování oznámení v kódu agenta

    • Agent přijímá oznámení z aplikací Microsoft 365.
    • Zpracovávejte příchozí oznámení a reagujte na ně vhodným způsobem.

Typy oznámení

Sada Agent 365 SDK podporuje následující typy oznámení.

Typ oznámení Popis ID podkanálu
E-mail Agent obdrží e-mail, ve kterém je zmíněn nebo osloven. email
Word Agent je zmíněn v komentáři v dokumentu Word. word
Excel Agent je zmíněn v komentáři v dokumentu Excel excel
PowerPoint Agent je zmíněn v komentáři v dokumentu PowerPoint powerpoint
Události životního cyklu Oznámení o životním cyklu agenta (vytvoření identity uživatele, onboarding pracovního prostředí, odstranění uživatele) Není k dispozici

Události životního cyklu agenta

Události životního cyklu agenta umožňují vašemu agentovi reagovat na konkrétní systémové události související se správou uživatelské identity agenta. SDK aktuálně podporuje tři události životního cyklu:

Typ události ID události Popis
Vytvořena identita uživatele agenticUserIdentityCreated Spouští se, když je vytvořena identita uživatele agenta.
Aktualizován onboarding pracovních úloh agenticUserWorkloadOnboardingUpdated Spouští se, když je aktualizován stav onboardingu pracovních úloh uživatele agenta.
Uživatel odstraněn agenticUserDeleted Spouští se, když je identita uživatele agenta smazána

Pomocí těchto událostí mohou agenti provádět inicializační úkoly, úklidové operace nebo správu stavu v reakci na změny životního cyklu uživatele.

Odkaz na datovou část oznámení

Když váš agent obdrží oznámení, jeho payload obsahuje strukturovaná data specifická pro daný typ oznámení. Porozumění těmto datovým částem oznámení vám pomůže získat informace potřebné k efektivnímu zpracování oznámení.

Datová část e-mailového oznámení

Když uživatel odešle e-mail vašemu agentovi nebo ho v e-mailu zmíní, obdrží váš agent e-mailové oznámení v následující struktuře:

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

Datová část oznámení komentářů k dokumentu (Word, Excel, PowerPoint)

Když uživatel zmíní vašeho agenta v komentáři v dokumentu Word, Excel nebo PowerPoint, váš agent obdrží oznámení o komentáři 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"
    }
  ]
}

Přidání oznámení k agentovi

Postupujte podle těchto kroků, abyste u svého stávajícího agenta povolili zpracování oznámení:

Komponenty oznámení o importu

Přidejte tyto importy do souboru 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: Základní třída pro vytváření aplikací Agent365 Poskytuje základní funkce pro směrování aktivit, správu stavu a zpracování požadavků.
  • AgentNotification: Třída pro registraci zpracovatelů oznámení pomocí dekoračních metod. Poskytuje on_agent_notification(), on_email(), on_word() a další užitečné dekorátorové metody.
  • AgentNotificationActivity: Obálka obsahující parsovaná data oznámení s typovanými vlastnostmi, jako například email_notification a wpx_comment_notification, které obsahují oznámení-specifická metadata, například ID, detaily konverzace a odkazy na dokumenty.
  • Enum podporovaných typů oznámení: Výčet podporovaných typů oznámení, jako například EMAIL_NOTIFICATION, WPX_COMMENT.
  • ChannelId: Použijte k určení kanálů oznámení, například ChannelId(channel="agents", sub_channel="*").
  • Autorizace: Kontext autorizace pro zpracování oznámení.
  • TurnContext: Aktuální konverzační kontext ze SDK agentů.

Zaregistrujte obslužné rutiny oznámení ve svém agentu

Přidejte obslužné rutiny oznámení do inicializace vašeho 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.')

Implementujte specifické obslužné rutiny pro oznámení

Přidejte obslužné metody pro každý typ oznámení:

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

Identifikovat odesílatele

Každá aktivita oznámení obsahuje Activity.From. Platforma A365 tuto vlastnost naplní základní identitou odesílatele, takže nepotřebujete žádné API volání ani získávání tokenů. Přistupujte k němu v jakékoli obslužné metodě oznámení:

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 je instance třídy ChannelAccount, která má následující vlastnosti:

Vlastnost Description
name Zobrazovaný název
id ID uživatele kanálu
aad_object_id ID objektu Entra

Důležité

Zobrazované jméno je text zadaný uživatelem. Před vložením do systémových výzev LLM odstraňte řídicí znaky a vynuťte maximální délku, abyste předešli útokům typu injection do výzvy.

Zpropitné

Použijte aadObjectId s Microsoft Graph API k získání rozšířených profilových dat (pracovní pozice, manažer, oddělení), pokud má váš agent příslušná oprávnění.

Specializované obslužné rutiny oznámení

Po nastavení základního směrování oznámení použijte specializované obslužné metody pro podrobnější řízení. Používáním těchto metod můžete:

  • Zaregistrujte více obslužných rutin pro stejný typ oznámení.
  • Nastavte prioritu obslužné rutiny pomocí pořadí.
  • Konfigurujte automatické ověřování pro každou obslužnou rutinu.

Poznámka:

Pro většinu případů použití je obecný vzor obslužných rutin dostačující. Použijte tyto specializované obslužné rutiny, když potřebujete pokročilé směrování nebo více obslužných rutin pro stejný typ oznámení.

Specializovaná obslužná rutina pro všechna oznámení

Zaregistrujte více obslužných rutin, které zpracovávají všechny typy oznámení:

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

Specializovaná obslužná rutina pro e-mailová oznámení

Zaregistrujte více obslužných rutin určených pro e-mailová oznámení:

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

Specializované obslužné rutiny pro komentáře k dokumentům

Zaregistrujte další obslužné rutiny pro oznámení komentářů ve Wordu, Excelu a PowerPointu:

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

Specializované obslužné rutiny pro události životního cyklu

Zaregistrujte další obslužné rutiny pro události životního cyklu agenta, například vytvoření identity uživatele, nasazení úloh a odstranění uživatele:

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

Pokročilá konfigurace

Tato sekce se věnuje pokročilým konfiguračním možnostem pro doladění vašich obslužných rutin oznámení. Použitím těchto konfigurací můžete kontrolovat pořadí provádění obslužných rutin, spravovat požadavky na ověřování a optimalizovat zpracování oznámení pro komplexní scénáře.

Priorita a pořadí obslužných rutin

Pokud používáte více specializovaných obslužných rutin, určete pořadí priority pomocí hodnot pořadí. Nižší hodnoty pořadí znamenají vyšší prioritu:

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

Obslužné rutiny ověřování

Nastavte automatické obslužné rutiny přihlášení pro oznámení, které vyžadují ověření:

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

Ukázkový kód

Pro úplné pracovní příklady zpracování oznámení napříč všemi podporovanými rámci se podívejte na Ukázky Agent 365.

Otestujte agenta s oznámeními

Po implementaci obslužných rutin pro oznámení otestujte svého agenta, abyste se ujistili, že správně přijímá a zpracovává různé typy oznámení. Postupujte podle průvodce testováním pro nastavení prostředí a poté se zaměřte především na sekci Testování s aktivitami oznámení, abyste ověřili oznámení pomocí agentického ověření.

Monitorování zpracování oznámení

Implementujte funkce pozorovatelnosti pro sledování zpracování oznámení vašeho agenta. Sledujte zpracování oznámení, doby odezvy a míru chybovosti, abyste lépe pochopili výkon agenta. Zjistěte více o implementaci trasování a monitoringu.

  • Last updated on