Give agenter besked

Ved at bruge modulet Meddelelser kan du bygge agenter, der reagerer på hændelser og meddelelser fra Microsoft 365-programmer. Ved at bruge 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

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

Beskedtyper

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

Meddelelsestype 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:

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

Ved at bruge disse hændelser kan agenter udføre initialiseringsopgaver, cleanup-handlinger eller tilstandsstyring som svar på ændringer i brugerlivscyklus.

Henvisning til nyttedata for meddelelse

Når din agent modtager en notifikation, indeholder nyttedataene strukturerede data, der er specifikke for notifikationstypen. At forstå disse nyttedata hjælper dig med at udtrække de oplysninger, du har brug for til effektivt at behandle notifikationer.

E-mailnotifikationsnyttedata

Når en bruger sender en mail til din agent eller nævner din agent i en mail, modtager din agent en mailnotifikation med følgende struktur:

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

Notifikationsnyttedata med dokumentkommentar (Word, Excel, PowerPoint)

Når en bruger nævner din agent i en kommentar i et Word-, Excel- eller PowerPoint-dokument, modtager din agent en WPX (Word, PowerPoint, Excel) kommentarnotifikation:

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

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 til opbygning af Agent365-programmer. Den leverer kernefunktionalitet til routing af aktiviteter, tilstandshåndtering og behandling af forespørgsler.
  • AgentNotification: Klasse til registrering af meddelelseshandlere med dekoratørmetoder. Den leverer on_agent_notification(), on_email(), on_word() og andre hjælpedekoratorer.
  • AgentNotificationActivity: Ombryder, der indeholder parsede meddelelsesdata med indtastede egenskaber som f.eks. email_notification og wpx_comment_notification, som indeholder meddelelsesspecifikke metadata, f.eks. id'er, samtaleoplysninger og dokumentreferencer.
  • NotificationTypes: En optælling af understøttede meddelelsestyper som EMAIL_NOTIFICATION, WPX_COMMENT.
  • ChannelId: Bruges til at angive meddelelseskanaler, f.eks. ChannelId(channel="agents", sub_channel="*").
  • Authorization: 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

Identificer afsenderen

Hver notifikationsaktivitet indeholder Activity.From. A365-platformen udfylder denne egenskab med afsenderens grundlæggende identitet, så du ikke behøver at foretage API-kald eller hente tokens. Få adgang til den i enhver notifikationshandler:

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 er en forekomst af ChannelAccount-klassen med følgende egenskaber:

Egenskab Beskrivelse
name Visningsnavn
id Kanalbruger-id
aad_object_id Entra-objekt-id

Vigtigt!

Vist navn er brugerstyret tekst. Rens den (fjern kontroltegn, og begræns længden), før du injicerer den i LLM-systemprompter, for at forhindre promptinjektionsangreb.

Tip

Brug aadObjectId med Microsoft Graph API til at hente udvidede profildata (jobtitel, leder, afdeling), når din agent har de nødvendige tilladelser.

Specialiserede meddelelseshandlere

Når du har konfigureret den grundlæggende meddelelsesrouting, skal du bruge specialiserede handlermetoder til mere detaljeret kontrol. Ved at bruge disse metoder kan du:

  • Registrere flere handlere for den samme meddelelsestype.
  • Angive handlerprioritet med rangering.
  • Konfigurere automatisk godkendelse for hver 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. Ved hjælp af disse konfigurationer kan du 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, skal 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

Eksempelkode

For komplette arbejdseksempler på notifikationshåndtering på tværs af alle understøttede strukturer kan du se Agent 365-eksempler.

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

Tilføj funktioner til observerbarhed for at overvåge din agents håndtering af meddelelser. Spor behandling af meddelelser, svartider og fejlprocenter for at forstå agentens ydeevne. Få mere at vide om implementering af sporing og overvågning.

  • Last updated on