Del via


Give agenter besked

Vigtigt

Du skal være en del af Frontier-forhåndsversionsprogrammet for at få tidlig adgang til Microsoft Agent 365. Frontier forbinder dig direkte med Microsofts seneste AI-innovationer. Frontier-forhåndsversioner er underlagt de eksisterende forhåndsversionsbetingelser i dine kundeaftaler. Da disse funktioner stadig er under udvikling, kan deres tilgængelighed og egenskaber ændre sig over tid.

Modulet Meddelelser gør det muligt for udviklere at bygge agenter, der kan reagere på hændelser og meddelelser fra Microsoft 365-programmer. Med understøttelse af meddelelser kan agenter modtage og behandle beskeder, når brugerne interagerer med dem via mail, dokumentkommentarer eller andre samarbejdsscenarier.

Meddelelsesarbejdsproces

Følg denne arbejdsproces for at aktivere meddelelser for dit AI-agentprogram:

  1. Installér meddelelsespakker.

  2. Importér meddelelseskomponenter

    • Importér meddelelsesklasser og -handlere
    • Importér aktivitetstyper og kanal-id'er
  3. Registrer meddelelseshandlere

    • Brug metoder til meddelelseshandler til at registrere ruter
    • Konfigurer handlere for bestemte meddelelsestyper (f.eks. mail, Word, Excel, PowerPoint)
  4. Behandl meddelelser i agentkode

    • Agent modtager meddelelser fra Microsoft 365-programmer
    • Håndterer indgående meddelelser, og besvarer korrekt

Beskedtyper

Agent 365 SDK'er understøtter følgende meddelelsestyper:

Notifikationstype Beskrivelse Underkanal-id
Mail Agenten modtager en mail, hvor vedkommende er nævnt eller adresseret email
Word Agent er nævnt i en kommentar i et Word-dokument word
Excel Agent er nævnt i en kommentar i et Excel-dokument excel
PowerPoint Agent er nævnt i en kommentar i et PowerPoint-dokument powerpoint
Livscyklushændelser Meddelelser om agentlivscyklus (brugeridentitet er oprettet, onboarding af arbejdsbelastning, bruger slettet) I/T

Agentlivscyklushændelser

Agentlivscyklushændelser gør det muligt for din agent at reagere på specifikke systemhændelser, der er relateret til administration af agentbaseret brugeridentitet. SDK'et understøtter i øjeblikket tre livscyklushændelser:

Arrangementstype Hændelses-id Beskrivelse
Brugeridentitet er oprettet agenticUserIdentityCreated Udløses, når der oprettes en agentbaseret brugeridentitet
Onboarding af arbejdsbelastning opdateret agenticUserWorkloadOnboardingUpdated Udløses, når onboardingstatus for en agentbaseret brugers arbejdsbelastning opdateres
Bruger slettet agenticUserDeleted Udløses, når en agentbaseret brugeridentitet slettes

Disse hændelser gør det muligt for agenter at udføre initialiseringsopgaver, cleanup-handlinger eller tilstandsstyring som svar på ændringer i brugerlivscyklus.

Føj meddelelser til din agent

Følg disse trin for at aktivere håndtering af meddelelser i din eksisterende agent:

Importér meddelelseskomponenter

Føj disse importer til din agentfil:

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: Basisklasse for bygning af Agent365-programmer. Leverer kernefunktionalitet til routingaktiviteter, administration af tilstand og behandling af anmodninger
  • AgentNotification: Klasse til registrering af meddelelseshandlere med dekoratørmetoder. Leverer on_agent_notification(), on_email(), on_word()og andre hjælpedekoratorer
  • AgentNotificationActivity: Wrapper, der indeholder parsede meddelelsesdata med indtastede egenskaber som f.eks. email_notification , og wpx_comment_notification, som indeholder meddelelsesspecifikke metadata (id'er, samtaleoplysninger, dokumentreferencer)
  • NotificationTypes: En optælling af understøttede meddelelsestyper (EMAIL_NOTIFICATION, WPX_COMMENT, AGENT_LIFECYCLE)
  • ChannelId: Bruges til at angive meddelelseskanaler (f.eks. ChannelId(channel="agents", sub_channel="*"))
  • Godkendelse: Godkendelseskontekst til behandling af meddelelser
  • TurnContext: Kontekst for det aktuelle samtaleskift fra SDK til agenter

Registrer meddelelseshandlere i din agent

Føj meddelelseshandlere til din agents initialisering:

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

Implementer specifikke meddelelseshandlere

Tilføj handlermetoder for hver meddelelsestype:

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

Specialiserede meddelelseshandlere

Når du har konfigureret den grundlæggende meddelelsesrouting, skal du bruge specialiserede handlermetoder til mere detaljeret kontrol. Disse metoder giver dig mulighed for at:

  • Registrer flere handlere for den samme meddelelsestype
  • Angiv handlerprioritet med rangering
  • Konfigurer automatisk godkendelse pr. handler

Bemærk

I de fleste use cases er det generiske handlermønster tilstrækkeligt. Brug disse specialiserede handlere, når du har brug for avanceret routing eller flere handlere til den samme meddelelsestype.

Specialiseret handler til alle meddelelser

Registrer flere handlere, der behandler alle meddelelsestyper:

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

Specialiseret handler til mailmeddelelser

Registrer flere handlere specifikt til mailmeddelelser:

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

Specialiserede handlere til dokumentkommentarer

Registrer flere handlere til Word-, Excel- og PowerPoint-kommentarmeddelelser:

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

Specialiserede handlere til livscyklushændelser

Registrer flere handlere til agentlivscyklushændelser, f.eks. oprettelse af brugeridentitet, onboarding af arbejdsbelastninger og sletning af brugere:

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

Avanceret konfiguration

I dette afsnit beskrives avancerede konfigurationsindstillinger til finjustering af dine meddelelseshandlere. Disse konfigurationer giver dig mulighed for at styre udførelsesrækkefølgen for handleren, administrere godkendelseskrav og optimere meddelelsesbehandling af komplekse scenarier.

Handlerprioritet og rangering

Når du bruger flere specialiserede handlere, kan du angive prioritetsrækkefølgen ved hjælp af rangeringsværdier. Lavere rangeringsværdier angiver højere prioritet:

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

Godkendelseshandlere

Konfigurer handlere til automatisk logon til meddelelser, der kræver godkendelse:

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

Test og overvåg

Test din agent med meddelelser

Når du har implementeret meddelelseshandlere, skal du teste din agent for at sikre, at den modtager og behandler forskellige meddelelsestyper korrekt. Følg testvejledningen for at konfigurere dit miljø, og fokuser derefter primært på afsnittet Test med meddelelsesaktiviteter for at validere dine meddelelser ved hjælp af agentbaseret godkendelse.

Overvåg håndtering af meddelelser

Overvåg din agents håndtering af meddelelser ved at tilføje funktioner til observationsmulighed. Spor behandling af meddelelser, svartider og fejlprocenter for at forstå agentens ydeevne. Få mere at vide om implementering af sporing og overvågning