Sdílet prostřednictvím


Upozornění agentů

Důležité

Abyste získali přednostní přístup k Microsoft Agentu 365, musíte být součástí programu Frontier Preview. Hranice vás spojuje přímo s nejnovějšími inovacemi umělé inteligence Microsoftu. Verze Preview hranice podléhají stávajícím podmínkám verze Preview vašich smluv se zákazníkem. Vzhledem k tomu, že tyto funkce jsou stále ve vývoji, jejich dostupnost a možnosti se můžou v průběhu času měnit.

Modul Oznámení umožňuje vývojářům vytvářet agenty, kteří můžou reagovat na události a oznámení z aplikací Microsoftu 365. Díky podpoře oznámení můžou agenti přijímat a zpracovávat výstrahy, když s nimi uživatelé komunikují prostřednictvím e-mailu, komentářů k dokumentům nebo jiných scénářů pro spolupráci.

Pracovní postup oznámení

Pokud chcete povolit oznámení pro aplikaci agenta AI, postupujte podle tohoto pracovního postupu:

  1. Nainstalujte balíčky oznámení.

  2. Import komponent oznámení

    • Import tříd oznámení a obslužných rutin
    • Import typů aktivit a identifikátorů kanálů
  3. Registrace obslužných rutin oznámení

    • Použití metod obslužné rutiny oznámení k registraci tras
    • Konfigurace obslužných rutin pro konkrétní typy oznámení (například e-mail, Word, Excel, PowerPoint)
  4. Zpracování oznámení v kódu agenta

    • Agent přijímá oznámení z aplikací Microsoftu 365
    • Zpracování příchozíchoznámeních

Typy oznámení

podporuje následující typy oznámení.

Typ upozornění Popis ID dílčího kanálu
E-mail Agent obdrží e-mail se zmínkou nebo adresou. email
Slovo Agent je zmíněn v komentáři ve wordovém dokumentu. word
Vynikat Agent je zmíněn v komentáři v excelovém dokumentu. excel
PowerPoint 2021 Agent je zmíněn v komentáři v dokumentu PowerPointu. powerpoint
Události životního cyklu Oznámení o životním cyklu agenta (vytvořená identita uživatele, onboarding úloh, odstranění uživatele)

Události životního cyklu agenta

Události životního cyklu agenta umožňují agentu reagovat na konkrétní systémové události související se správou identit uživatelů agentů. Sada SDK aktuálně podporuje tři události životního cyklu:

Typ akce ID události Popis
Vytvořená identita uživatele agenticUserIdentityCreated Aktivuje se při vytvoření identity uživatele agenta.
Aktualizace onboardingu úloh agenticUserWorkloadOnboardingUpdated Aktivuje se, když se aktualizuje stav onboardingu úloh agenta uživatele.
Uživatel byl odstraněn. agenticUserDeleted Aktivuje se při odstranění identity uživatele agenta.

Tyto události umožňují agentům provádět úlohy inicializace, operace čištění nebo správu stavu v reakci na změny životního cyklu uživatele.

Přidání oznámení do agenta

Pokud chcete povolit zpracování oznámení ve stávajícím agentu, postupujte takto:

Import komponent oznámení

Přidejte do souboru agenta tyto importy:

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 aktivity směrování, správu stavu a zpracování požadavků.
  • AgentNotification: Třída pro registraci obslužných rutin oznámení pomocí metod dekorátoru. Poskytuje on_agent_notification(), on_email(), on_word()a další dekorátory pohodlí
  • AgentNotificationActivity: Obálka obsahující analyzovaná data oznámení s typem vlastností, jako email_notification jsou metadata wpx_comment_notification specifická pro oznámení (ID, podrobnosti konverzace, odkazy na dokumenty)
  • NotificationTypes: Výčet podporovaných typů oznámení (EMAIL_NOTIFICATION, WPX_COMMENT, AGENT_LIFECYCLE)
  • ChannelId: Slouží k určení kanálů oznámení (např. ChannelId(channel="agents", sub_channel="*"))
  • Autorizace: Kontext autorizace pro zpracování oznámení
  • TurnContext: Kontext aktuální konverzace ze sady Agents SDK

Registrace obslužných rutin oznámení v agentu

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

Implementace konkrétních obslužných rutin oznámení

Přidejte metody obslužné rutiny 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

Specializované obslužné rutiny oznámení

Po nastavení základního směrování oznámení použijte specializované metody obslužné rutiny pro podrobnější řízení. Tyto metody umožňují:

  • Registrace více obslužných rutin pro stejný typ oznámení
  • Nastavení priority obslužné rutiny s řazením
  • Konfigurace automatického ověřování na obslužnou rutinu

Poznámka:

Ve většině případů použití stačí obecný vzor obslužné rutiny. Tyto specializované obslužné rutiny použijte, pokud potřebujete rozšířené 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 další obslužné rutiny, 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 další obslužné rutiny speciálně 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

Registrace dalších obslužných rutin pro oznámení komentářů k 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, jako je vytvoření identity uživatele, onboarding ú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 část popisuje pokročilé možnosti konfigurace pro vyladění obslužných rutin oznámení. Tyto konfigurace umožňují řídit pořadí provádění obslužné rutiny, spravovat požadavky na ověřování a optimalizovat zpracování oznámení pro složité scénáře.

Priorita a řazení obslužné rutiny

Při použití více specializovaných obslužných rutin můžete určit pořadí priority pomocí hodnot pořadí. Nižší hodnoty označují 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í

Nakonfigurujte obslužné rutiny automatického přihlašování pro oznámení, která vyžadují ověřování:

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

Testování a monitorování

Testování agenta s oznámeními

Po implementaci obslužných rutin oznámení otestujte agenta, abyste zajistili, že správně přijímá a zpracovává různé typy oznámení. Postupujte podle průvodce testováním a nastavte své prostředí a pak se zaměřte hlavně na část Testování s aktivitami oznámení a ověřte oznámení pomocí ověřování agentů.

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

Monitorování zpracování oznámení agenta přidáním možností pozorovatelnosti Sledujte zpracování oznámení, dobu odezvy a míry chyb, abyste porozuměli výkonu agenta. Další informace o implementaci trasování a monitorování