Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Importante
Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.
Il modulo Notifiche consente agli sviluppatori di compilare agenti in grado di rispondere a eventi e notifiche dalle applicazioni di Microsoft 365. Con il supporto delle notifiche, gli agenti possono ricevere ed elaborare avvisi quando gli utenti interagiscono con loro tramite e-mail, commenti ai documenti o altri scenari collaborativi.
Flusso di lavoro delle notifiche
Segui questo flusso di lavoro per abilitare le notifiche per l'applicazione dell'agente IA:
Importare i componenti delle notifiche
- Importare classi di notifica e gestori
- Importare tipi di attività e identificatori di canale
Registrare i gestori di notifica
- Usare i metodi del gestore delle notifiche per registrare gli itinerari
- Configurare i gestori per tipi di notifica specifici (ad esempio: e-mail, Word, Excel, PowerPoint)
Elaborare le notifiche nel codice dell'agente
- L'agente riceve notifiche dalle applicazioni Microsoft 365
- Gestire le notifiche in ingresso e rispondere in modo appropriato
Tipi di notifica
Agents 365 SDK supporta i seguenti tipi di notifica:
| Tipo di notifica | Descrizione | ID canale secondario |
|---|---|---|
| L'agente riceve un messaggio e-mail in cui sono menzionati o indirizzati | email |
|
| Word | L'agente è menzionato in un commento in un documento di Word | word |
| Excel | L'agente è menzionato in un commento in un documento Excel | excel |
| PowerPoint | L'agente è menzionato in un commento in un documento PowerPoint | powerpoint |
| Eventi reali | Notifiche del ciclo di vita dell'agente (identità utente creata, onboarding del carico di lavoro, utente eliminato) | N/A |
Eventi del ciclo di vita dell'agente
Gli eventi del ciclo di vita dell'agente consentono all'agente di rispondere a eventi di sistema specifici correlati alla gestione delle identità utente dell'agente. L'SDK supporta attualmente tre eventi del ciclo di vita:
| Tipo di evento | ID evento | Descrizione |
|---|---|---|
| Identità utente creata | agenticUserIdentityCreated |
Attivato quando viene creata un'identità utente agente |
| Onboarding del carico di lavoro aggiornato | agenticUserWorkloadOnboardingUpdated |
Attivato quando viene aggiornato lo stato di onboarding del carico di lavoro di un utente agente |
| Utente eliminato | agenticUserDeleted |
Attivato quando viene eliminata un'identità utente agente |
Questi eventi consentono agli agenti di eseguire attività di inizializzazione, operazioni di pulizia o gestione dello stato in risposta alle modifiche del ciclo di vita dell'utente.
Aggiungere notifiche all'agente
Segui questa procedura per abilitare la gestione delle notifiche nell'agente esistente:
Importare i componenti delle notifiche
Aggiungi queste importazioni al file dell'agente:
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: classe base per la compilazione di applicazioni Agent365; fornisce funzionalità di base per le attività di routing, la gestione dello stato e l'elaborazione delle richieste
-
AgentNotification: classe per la registrazione di gestori di notifica con metodi decorator. Fornisce
on_agent_notification(),on_email(),on_word()e altri elementi decorator per comodità -
AgentNotificationActivity: wrapper contenente dati di notifica analizzati con proprietà tipizzate come
email_notificationewpx_comment_notificationche contengono metadati specifici della notifica (ID, dettagli della conversazione, riferimenti ai documenti) -
NotificationTypes: enumerazione dei tipi di notifica supportati (
EMAIL_NOTIFICATION,WPX_COMMENT,AGENT_LIFECYCLE) -
ChannelId: usato per specificare i canali di notifica (ad esempio,
ChannelId(channel="agents", sub_channel="*")) - Autorizzazione: contesto di autorizzazione per l'elaborazione delle notifiche
- TurnContext: contesto del turno di conversazione corrente dall'SDK degli agenti
Registrare i gestori di notifica nell'agente
Aggiungere gestori di notifica all'inizializzazione dell'agente:
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.')
Implementare gestori di notifica specifici
Aggiungere metodi del gestore per ogni tipo di notifica:
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
Gestori di notifica specializzati
Dopo aver configurato il routing delle notifiche di base, usa metodi del gestore specializzati per un controllo più granulare. Tali metodi consentono di:
- Registrare più gestori per lo stesso tipo di notifica
- Impostare la priorità del gestore con la classificazione
- Configurare l'autenticazione automatica per gestore
Nota
Per la maggior parte dei casi d'uso, il modello di gestore generico è sufficiente. Usa questi gestori specializzati quando sono necessari routing avanzato o più gestori per lo stesso tipo di notifica.
Gestore specializzato per tutte le notifiche
Registra più gestori che elaborano tutti i tipi di notifica:
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}")
Gestore specializzato per le notifiche e-mail
Registra più gestori in particolare per le notifiche tramite e-mail:
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!')
Gestori specializzati per i commenti dei documenti
Registra altri gestori per le notifiche di commento di Word, Excel e PowerPoint:
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')
Gestori specializzati per gli eventi del ciclo di vita
Registra più gestori per gli eventi del ciclo di vita dell'agente, ad esempio la creazione di identità utente, l'onboarding del carico di lavoro e l'eliminazione dell'utente:
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')
Configurazione avanzata
Questa sezione illustra le opzioni di configurazione avanzate per ottimizzare i gestori di notifica. Queste configurazioni consentono di controllare l'ordine di esecuzione del gestore, gestire i requisiti di autenticazione e ottimizzare l'elaborazione delle notifiche per scenari complessi.
Priorità e classificazione del gestore
Quando si usano più gestori specializzati, puoi specificare l'ordine di priorità usando i valori di classificazione. Valori di classificazione più bassi indicano una priorità più alta:
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
Gestori dell'autenticazione
Configura i gestori di accesso automatico per le notifiche che richiedono l'autenticazione:
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
Testare e monitorare
Testa l'agente con le notifiche
Dopo l'implementazione dei gestori di notifica, testa l'agente per assicurarsi che riceva correttamente ed elabori tipi di notifica diversi. Segui la guida ai test per configurare l'ambiente, quindi concentrati principalmente sulla sezione Test con attività di notifica per convalidare le notifiche usando l'autenticazione agente.
Monitorare la gestione delle notifiche
Monitora la gestione delle notifiche dell'agente aggiungendo funzionalità di osservabilità. Tieni traccia dell'elaborazione delle notifiche, dei tempi di risposta e delle percentuali di errore per comprendere le prestazioni dell'agente. Altre informazioni sull'implementazione della traccia e del monitoraggio