Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Wichtig
Sie müssen Teil des Frontier-Vorschauversionsprogramms sein, um Vorabzugriff auf Microsoft Agent 365 zu erhalten. Frontier verbindet Sie direkt mit den neuesten KI-Innovationen von Microsoft. Frontier-Vorschauversionen unterliegen den bestehenden Vorschauversionsbedingungen Ihrer Kundenvereinbarungen. Da sich diese Funktionen noch in der Entwicklung befinden, können sich ihre Verfügbarkeit und Merkmale im Laufe der Zeit ändern.
Mithilfe des Benachrichtigungsmoduls können Sie Agents erstellen, die auf Ereignisse und Benachrichtigungen von Microsoft 365 Anwendungen reagieren. Durch die Nutzung von Benachrichtigungsunterstützung können Agenten Benachrichtigungen erhalten und bearbeiten, wenn Nutzer mit ihnen per E-Mail, Dokumentenkommentaren oder anderen kollaborativen Szenarien interagieren.
Benachrichtigungs-Workflow
Folgen Sie diesem Workflow, um Benachrichtigungen für Ihre KI-Agent-Anwendung zu aktivieren:
Importieren von Benachrichtigungskomponenten
- Importieren sie Benachrichtigungsklassen und -handler.
- Importieren sie Aktivitätstypen und Kanalbezeichner.
Registrieren von Benachrichtigungshandlern
- Verwenden Sie Benachrichtigungshandlermethoden zum Registrieren von Routen.
- Konfigurieren Sie Handler für bestimmte Benachrichtigungstypen, z. B. E-Mail, Word, Excel oder PowerPoint.
Verarbeiten von Benachrichtigungen im Agentcode
- Der Agent empfängt Benachrichtigungen von Microsoft 365 Anwendungen.
- Behandeln Sie eingehende Benachrichtigungen, und reagieren Sie entsprechend.
Benachrichtigungstypen
Das Agent 365 SDK unterstützt folgende Benachrichtigungstypen:
| Benachrichtigungstyp | Beschreibung | Unterkanal-ID |
|---|---|---|
| E‑Mail | Der Agent erhält eine E-Mail, in der er erwähnt oder adressiert wird | email |
| Word | Agent wird in einem Kommentar in einem Word Dokument erwähnt. | word |
| Excel | Agent wird in einem Kommentar in einem Excel-Dokument erwähnt | excel |
| PowerPoint | Agent wird in einem Kommentar in einem PowerPoint Dokument erwähnt. | powerpoint |
| Lebenszyklusereignisse | Agent-Lebenszyklusbenachrichtigungen (Benutzeridentität erstellt, Workload-Onboarding, Benutzer gelöscht) | NICHT ZUTREFFEND |
Agent-Lebenszyklusereignisse
Agent-Lebenszyklusereignisse ermöglichen es Ihrem Agent, auf bestimmte Systemereignisse im Zusammenhang mit der agentischen Benutzeridentitätsverwaltung zu reagieren. Das SDK unterstützt derzeit drei Lebenszyklusereignisse:
| Ereignistyp | Ereignis-ID | Beschreibung |
|---|---|---|
| Benutzeridentität erstellt | agenticUserIdentityCreated |
Wird ausgelöst, wenn eine Agent-Benutzeridentität erstellt wird |
| Workload Onboarding aktualisiert | agenticUserWorkloadOnboardingUpdated |
Wird ausgelöst, wenn der Workload-Onboarding-Status eines proaktiven Benutzers aktualisiert wird. |
| Benutzer gelöscht | agenticUserDeleted |
Wird ausgelöst, wenn eine Agent-Benutzeridentität gelöscht wird |
Mithilfe dieser Ereignisse können Agents Initialisierungsaufgaben, Bereinigungsvorgänge oder Zustandsverwaltung als Reaktion auf Änderungen des Benutzerlebenszyklus ausführen.
Bearbeiten von Agentinstallations- und Deinstallationsereignissen
Wenn ein Benutzer Ihren Agent in Teams oder anderen vom Agent 365 gehosteten Kanälen installiert oder deinstalliert, sendet die Plattform eine InstallationUpdate Aktivität (auch als agentInstanceCreated Ereignis bezeichnet). Ihr Agent kann diese Ereignisse verarbeiten, um eine Willkommensnachricht zu senden, wenn sie installiert ist, und eine Abschiedsnachricht, wenn sie deinstalliert wird.
| Action | Beschreibung |
|---|---|
add |
Der Benutzer installiert den Agent |
remove |
Der Benutzer deinstalliert den Agent. |
Im Gegensatz zu Benachrichtigungshandlern erfordert der InstallationUpdate Handler keine Authentifizierung, da das Installations- oder Deinstallationsereignis vor oder nach einer aktiven Sitzung des Benutzers ausgelöst wird.
Registrieren des Installations- und Deinstallationshandlers
Registrieren Sie einen Aktivitätshandler für den InstallationUpdate Aktivitätstyp in der Initialisierung Ihres Agents.
@agent_app.activity("installationUpdate")
async def on_installation_update(context: TurnContext, state: TurnState):
action = context.activity.action
from_prop = context.activity.from_property
logger.info(
"InstallationUpdate received — Action: '%s', DisplayName: '%s', UserId: '%s'",
action or "(none)",
getattr(from_prop, "name", "(unknown)") if from_prop else "(unknown)",
getattr(from_prop, "id", "(unknown)") if from_prop else "(unknown)",
)
if action == "add":
await context.send_activity("Thank you for hiring me! Looking forward to assisting you in your professional journey!")
elif action == "remove":
await context.send_activity("Thank you for your time, I enjoyed working with you.")
Activity.action ist eine Zeichenfolge, die auf "add" festgelegt wird, wenn der Agent installiert oder auf "remove" festgelegt wird, wenn er deinstalliert wird.
Activity.from_property ist eine ChannelAccount-Instanz , die die Identität des Benutzers enthält.
Referenz der Benachrichtigungsnutzlast
Wenn Ihr Agent eine Benachrichtigung erhält, enthält die Nutzlast strukturierte Daten, die spezifisch für den Benachrichtigungstyp sind. Das Verständnis dieser Nutzlasten hilft Ihnen, die Informationen zu extrahieren, die Sie benötigen, um Benachrichtigungen effektiv zu verarbeiten.
E-Mail-Benachrichtigungsnutzlast
Wenn ein Nutzer eine E-Mail an seinen Agenten schickt oder ihn in einer E-Mail erwähnt, erhält er eine E-Mail-Benachrichtigung mit folgender 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>"
}
]
}
Nutzlast der Dokumentkommentarbenachrichtigung (Word, Excel, PowerPoint)
Wenn ein Benutzer Ihren Agent in einem Kommentar in einem Word-, Excel- oder PowerPoint-Dokument erwähnt, empfängt Ihr Agent eine WPX-Kommentarbenachrichtigung (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"
}
]
}
Benachrichtigungen zu Ihrem Agenten hinzufügen
Führen Sie die folgenden Schritte aus, um die Benachrichtigungsverarbeitung in Ihrem vorhandenen Agent zu aktivieren:
Importieren von Benachrichtigungskomponenten
Fügen Sie diese Importe zu Ihrer Agentdatei hinzu:
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 zum Erstellen von Agent365-Anwendungen. Es bietet Kernfunktionen für Routingaktivitäten, das Verwalten des Zustands und die Verarbeitung von Anforderungen.
-
AgentNotification: Klasse zum Registrieren von Benachrichtigungshandlern mit Dekoratormethoden. Es bietet
on_agent_notification(),on_email(),on_word()und andere Komfort-Dekoratoren. -
AgentNotificationActivity: Wrapper mit analysierten Benachrichtigungsdaten und typisierten Eigenschaften wie
email_notificationundwpx_comment_notification, die benachrichtigungsspezifische Metadaten wie IDs, Unterhaltungsdetails und Dokumentverweise enthalten. -
NotificationTypes: Enumeration der unterstützten Benachrichtigungstypen wie
EMAIL_NOTIFICATION,WPX_COMMENT. - de-DE: ChannelId: Dient zum Angeben von Benachrichtigungskanälen, z. B.
ChannelId(channel="agents", sub_channel="*"). - Autorisierung: Autorisierungskontext für die Verarbeitung von Benachrichtigungen.
- TurnContext: Der Kontext der aktuellen Unterhaltung wird aus dem Agents SDK abgeleitet.
Registrieren von Benachrichtigungshandlern in Ihrem Agent
Fügen Sie Benachrichtigungshandler zur Initialisierung Ihres Agenten hinzu:
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.')
Implementieren bestimmter Benachrichtigungshandler
Fügen Sie Handlermethoden für jeden Benachrichtigungstyp hinzu:
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
Identifizieren des Absenders
Jede Benachrichtigungsaktivität enthält Activity.From. Die A365-Plattform füllt diese Eigenschaft mit der grundlegenden Identität des Absenders auf, sodass Sie keine API-Aufrufe oder Tokenakquise benötigen. Greifen Sie innerhalb eines beliebigen Benachrichtigungshandlers darauf zu:
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 ist eine ChannelAccount-Klasseninstanz mit den folgenden Eigenschaften:
| Eigentum | Beschreibung |
|---|---|
name |
Anzeigename |
id |
Kanalbenutzer-ID |
aad_object_id |
Entra-Objekt-ID |
Wichtig
Der Anzeigename ist vom Benutzer gesteuerter Text. Stellen Sie sicher, dass Sie es bereinigen (Steuerzeichen entfernen, eine maximale Länge erzwingen), bevor Sie es in LLM-Systemaufforderungen einfügen, um Aufforderungseinspritzungsangriffe zu verhindern.
Tipp
Verwenden Sie aadObjectId mit dem Microsoft Graph API, um erweiterte Profildaten (Position, Manager, Abteilung) abzurufen, wenn Ihr Agent über entsprechende Berechtigungen verfügt.
Spezielle Benachrichtigungshandler
Verwenden Sie nach dem Einrichten des grundlegenden Benachrichtigungsroutings spezielle Handlermethoden für eine genauere Steuerung. Mithilfe dieser Methoden können Sie folgende Aktionen ausführen:
- Registrieren Sie mehrere Handler für denselben Benachrichtigungstyp.
- Legen Sie die Handlerpriorität mithilfe der Rangfolge fest.
- Konfigurieren sie die automatische Authentifizierung für jeden Handler.
Anmerkung
Für die meisten Anwendungsfälle reicht das generische Handlermuster aus. Verwenden Sie diese speziellen Handler, wenn Sie erweitertes Routing oder mehrere Handler für denselben Benachrichtigungstyp benötigen.
Spezieller Handler für alle Benachrichtigungen
Registrieren Sie weitere Handler, die alle Benachrichtigungstypen verarbeiten:
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}")
Spezieller Handler für E-Mail-Benachrichtigungen
Registrieren Sie weitere Handler speziell für E-Mail-Benachrichtigungen:
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!')
Spezielle Handler für Dokumentkommentare
Registrieren Sie weitere Handler für Word-, Excel- und PowerPoint Kommentarbenachrichtigungen:
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')
Spezielle Handler für Lebenszyklusereignisse
Registrieren Sie weitere Handler für Agent-Lebenszyklusereignisse, z. B. Benutzeridentitätserstellung, Workload-Onboarding und Benutzerlöschung:
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')
Erweiterte Konfiguration
In diesem Abschnitt werden die erweiterten Konfigurationsoptionen für die Feinabstimmung der Benachrichtigungshandler behandelt. Mithilfe dieser Konfigurationen können Sie die Ausführungsreihenfolge des Handlers steuern, Authentifizierungsanforderungen verwalten und die Benachrichtigungsverarbeitung für komplexe Szenarien optimieren.
Priorität und Rangfolge des Handlers
Wenn Sie mehrere spezialisierte Handler verwenden, geben Sie die Prioritätsreihenfolge mithilfe von Rangwerten an. Niedrigere Rangwerte weisen auf eine höhere Priorität hin:
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
Authentifizierungshandler
Konfigurieren Sie automatische Anmeldehandler für Benachrichtigungen, für die eine Authentifizierung erforderlich ist:
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
Beispielcode
Vollständige Arbeitsbeispiele für die Benachrichtigungsverarbeitung in allen unterstützten Frameworks finden Sie in den Agent 365-Beispielen.
Testen Ihres Agents mit Benachrichtigungen
Testen Sie den Agent nach der Implementierung von Benachrichtigungshandlern, um sicherzustellen, dass er ordnungsgemäß empfängt und verschiedene Benachrichtigungstypen verarbeitet. Folgen Sie dem Testhandbuch , um Ihre Umgebung einzurichten, und konzentrieren Sie sich dann hauptsächlich auf den Abschnitt " Testen mit Benachrichtigungsaktivitäten ", um Ihre Benachrichtigungen mithilfe der agentischen Authentifizierung zu überprüfen.
Überwachen der Benachrichtigungsverarbeitung
Um die Benachrichtigungsbehandlung Ihres Agents zu überwachen, fügen Sie Überwachungsfunktionen hinzu. Verfolgen Sie die Benachrichtigungsverarbeitung, Antwortzeiten und Fehlerraten, um die Leistung des Agents zu verstehen. Erfahren Sie mehr über die Implementierung von Nachverfolgung und Überwachung.