AgentNotification Class
Handler for agent notifications from Microsoft 365 applications.
This class provides decorators for registering handlers that respond to notifications from various Microsoft 365 channels and subchannels. It supports routing based on channel ID, subchannel, and lifecycle events.
Constructor
AgentNotification()Parameters
| Name | Description |
|---|---|
|
app
Required
|
The application instance that will handle the routed notifications. |
|
known_subchannels
|
Optional iterable of recognized subchannels. If None, defaults to all values in the AgentSubChannel enum. Default value: None
|
|
known_lifecycle_events
|
Optional iterable of recognized lifecycle events. If None, defaults to all values in the AgentLifecycleEvent enum. Default value: None
|
Examples
``<<>>`<<python from microsoft_agents.hosting import Application from microsoft_agents_a365.notifications import AgentNotificationapp = Application() notifications = AgentNotification(app)@notifications.on_email() async def handle_email(context, state, notification):
email = notification.email if email:
await context.send_activity(f"Received email: {email.id}")
``<<>>`<<
Methods
| __init__ | |
| __new__ | |
| on_agent_lifecycle_notification |
Register a handler for agent lifecycle event notifications. This decorator registers a handler function to be called when lifecycle events occur, such as user creation, deletion, or workload onboarding updates. |
| on_agent_notification |
Register a handler for notifications from a specific channel and subchannel. This decorator registers a handler function to be called when a notification is received from the specified channel and optional subchannel. The handler will receive a typed AgentNotificationActivity wrapper. |
| on_email |
Register a handler for Outlook email notifications. This is a convenience decorator that registers a handler for notifications from the email subchannel. |
| on_excel |
Register a handler for Microsoft Excel comment notifications. This is a convenience decorator that registers a handler for notifications from the Excel subchannel. |
| on_lifecycle |
Register a handler for all agent lifecycle event notifications. This is a convenience decorator that registers a handler for all lifecycle events using the wildcard "*" matcher. |
| on_powerpoint |
Register a handler for Microsoft PowerPoint comment notifications. This is a convenience decorator that registers a handler for notifications from the PowerPoint subchannel. |
| on_user_created |
Register a handler for user creation lifecycle events. This is a convenience decorator that registers a handler specifically for agentic user identity creation events. |
| on_user_deleted |
Register a handler for user deletion lifecycle events. This is a convenience decorator that registers a handler specifically for agentic user identity deletion events. |
| on_user_workload_onboarding |
Register a handler for user workload onboarding update events. This is a convenience decorator that registers a handler for events that occur when a user's workload onboarding status is updated. |
| on_word |
Register a handler for Microsoft Word comment notifications. This is a convenience decorator that registers a handler for notifications from the Word subchannel. |
__init__
__init__(app: Any, known_subchannels: Iterable[str | AgentSubChannel] | None = None, known_lifecycle_events: Iterable[str | AgentLifecycleEvent] | None = None)Parameters
| Name | Description |
|---|---|
|
app
Required
|
|
|
known_subchannels
|
Default value: None
|
|
known_lifecycle_events
|
Default value: None
|
__new__
__new__(**kwargs)on_agent_lifecycle_notification
Register a handler for agent lifecycle event notifications.
This decorator registers a handler function to be called when lifecycle events occur, such as user creation, deletion, or workload onboarding updates.
on_agent_lifecycle_notification(lifecycle_event: str, **kwargs: Any)Parameters
| Name | Description |
|---|---|
|
lifecycle_event
Required
|
The lifecycle event to listen for. Use "*" to match all lifecycle events, or specify a specific event from AgentLifecycleEvent. |
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_agent_lifecycle_notification("agenticuseridentitycreated") async def handle_user_created(context, state, notification):
print("New user created")
``<<>>`<<
on_agent_notification
Register a handler for notifications from a specific channel and subchannel.
This decorator registers a handler function to be called when a notification is received from the specified channel and optional subchannel. The handler will receive a typed AgentNotificationActivity wrapper.
on_agent_notification(channel_id: ChannelId, **kwargs: Any)Parameters
| Name | Description |
|---|---|
|
channel_id
Required
|
The channel ID specifying the channel and optional subchannel to listen for. Use "*" as the subchannel to match all subchannels. |
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python from microsoft_agents.activity import ChannelId
@notifications.on_agent_notification( ChannelId(channel="agents", sub_channel="email")
) async def handle_custom_channel(context, state, notification):
print(f"Received notification on {notification.channel}/{notification.sub_channel}")
``<<>>`<<
on_email
Register a handler for Outlook email notifications.
This is a convenience decorator that registers a handler for notifications from the email subchannel.
on_email(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_email() async def handle_email(context, state, notification):
email = notification.email if email:
print(f"Received email: {email.id}")
# Send a response
response = EmailResponse.create_email_response_activity(
"<p>Thank you for your email.</p>"
)
await context.send_activity(response)
``<<>>`<<
on_excel
Register a handler for Microsoft Excel comment notifications.
This is a convenience decorator that registers a handler for notifications from the Excel subchannel.
on_excel(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_excel() async def handle_excel_comment(context, state, notification):
comment = notification.wpx_comment if comment:
print(f"Received Excel comment: {comment.comment_id}")
``<<>>`<<
on_lifecycle
Register a handler for all agent lifecycle event notifications.
This is a convenience decorator that registers a handler for all lifecycle events using the wildcard "*" matcher.
on_lifecycle(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_lifecycle() async def handle_any_lifecycle_event(context, state, notification):
print(f"Lifecycle event type: {notification.notification_type}")
``<<>>`<<
on_powerpoint
Register a handler for Microsoft PowerPoint comment notifications.
This is a convenience decorator that registers a handler for notifications from the PowerPoint subchannel.
on_powerpoint(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_powerpoint() async def handle_powerpoint_comment(context, state, notification):
comment = notification.wpx_comment if comment:
print(f"Received PowerPoint comment: {comment.comment_id}")
``<<>>`<<
on_user_created
Register a handler for user creation lifecycle events.
This is a convenience decorator that registers a handler specifically for agentic user identity creation events.
on_user_created(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_user_created() async def handle_user_created(context, state, notification):
print("New agentic user identity created")
``<<>>`<<
on_user_deleted
Register a handler for user deletion lifecycle events.
This is a convenience decorator that registers a handler specifically for agentic user identity deletion events.
on_user_deleted(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_user_deleted() async def handle_user_deleted(context, state, notification):
print("Agentic user identity deleted")
``<<>>`<<
on_user_workload_onboarding
Register a handler for user workload onboarding update events.
This is a convenience decorator that registers a handler for events that occur when a user's workload onboarding status is updated.
on_user_workload_onboarding(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_user_workload_onboarding() async def handle_onboarding_update(context, state, notification):
print("User workload onboarding status updated")
``<<>>`<<
on_word
Register a handler for Microsoft Word comment notifications.
This is a convenience decorator that registers a handler for notifications from the Word subchannel.
on_word(**kwargs: Any) -> Callable[[Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]Parameters
| Name | Description |
|---|---|
|
**kwargs
Required
|
Additional keyword arguments passed to the app's add_route method. |
Returns
| Type | Description |
|---|---|
|
Callable[[Callable[[<xref:microsoft_agents_a365.notifications.agent_notification.TContext>, <xref:microsoft_agents_a365.notifications.agent_notification.TState>, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
|
A decorator function that registers the handler with the application. |
Examples
``<<>>`<<python @notifications.on_word() async def handle_word_comment(context, state, notification):
comment = notification.wpx_comment if comment:
print(f"Received Word comment: {comment.comment_id}")
``<<>>`<<