Skip to content

Commit 631185d

Browse files
ryukofcryukofc
committed
resync libraries
1 parent 1fffb3a commit 631185d

49 files changed

Lines changed: 2089 additions & 452 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎libraries/microsoft-agents-a365-notifications/README.md‎

Lines changed: 125 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,140 @@
11
# Microsoft Agent 365 Notifications
2+
[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-notifications.svg)](https://badge.fury.io/py/microsoft-agents-a365-notifications)
23

3-
This package provides notification and messaging extensions for AI agent applications.
4+
Notification and messaging extensions for AI agent applications built with the Microsoft Agent 365 SDK. Enable your agents to handle rich notifications from Microsoft 365 applications like Word, Excel, PowerPoint, and Email.
45

5-
## Features
6+
## What is this?
67

7-
- **Agent SDK Extensions**: Enhanced notification capabilities for AI agents
8-
- **Channel Management**: Support for different communication channels
9-
- **Activity Handling**: Interfaces for managing agent activities and recipients
10-
- **Role-based Messaging**: Support for role-based communication patterns
8+
This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The notifications package specifically handles incoming notifications from Microsoft 365 applications, allowing your agents to respond to events like document updates, email mentions, and collaborative activities.
119

12-
## Quick Start
13-
14-
### Import the notification extensions
15-
```python
16-
from microsoft_kairo.notification import agents_sdk_extensions
17-
```
10+
## Key Features
1811

19-
### Basic Usage
20-
21-
The package provides interfaces and utilities for:
22-
- Managing communication channels (`ChannelId`)
23-
- Defining recipients with roles (`IRecipient`)
24-
- Handling agent activities (`IActivity`)
25-
- Assertion helpers for validation
12+
✅ **Microsoft 365 Integration** - Handle notifications from Word, Excel, PowerPoint, and Outlook
13+
✅ **Channel Routing** - Intelligent routing based on source application and context
14+
✅ **Type Safety** - Built with Pydantic for automatic validation and type checking
15+
✅ **Flexible Handlers** - Support for wildcard and specific channel notification handlers
16+
✅ **Enterprise Ready** - Built for production Microsoft 365 environments
17+
✅ **Async Support** - Full async/await support for high-performance applications
2618

2719
## Installation
2820

2921
```bash
3022
pip install microsoft-agents-a365-notifications
3123
```
3224

25+
## Quick Start
26+
27+
### Basic Concepts
28+
29+
The Microsoft Agent 365 Notifications package enables your agents to receive and respond to notifications from Microsoft 365 applications. Key concepts include:
30+
31+
- **Notification Handlers**: Functions that process incoming notifications
32+
- **Channel Routing**: Route notifications based on the source application
33+
- **Sub-Channel Filtering**: Handle specific types of notifications (email, documents, etc.)
34+
- **Context Integration**: Access rich context about the notification source
35+
36+
### Getting Started
37+
38+
1. Install the package: `pip install microsoft-agents-a365-notifications`
39+
2. Configure your agent application with notification support
40+
3. Register handlers for specific Microsoft 365 applications
41+
4. Process incoming notifications with full context
42+
43+
## Supported Microsoft 365 Applications
44+
45+
| Application | Sub-Channel ID | Description |
46+
|-------------|----------------|-------------|
47+
| **Email** | `email` | Handle mentions and email-based interactions |
48+
| **Word** | `word` | Respond to document collaboration events |
49+
| **Excel** | `excel` | Process spreadsheet updates and analysis requests |
50+
| **PowerPoint** | `powerpoint` | Handle presentation collaboration notifications |
51+
| **Federated Knowledge** | `federatedknowledgeservice` | Enterprise knowledge base interactions |
52+
53+
## Advanced Usage
54+
55+
### Notification Processing Features
56+
57+
- **Custom Route Priorities**: Configure handler execution order for different notification types
58+
- **Authentication Integration**: Seamless integration with Microsoft 365 authentication flows
59+
- **Rich Context Access**: Access detailed metadata about notification sources and content
60+
- **Flexible Filtering**: Support for wildcard matching and specific application targeting
61+
62+
### Notification Types
63+
64+
The package supports various notification scenarios:
65+
- Document collaboration events (Word, Excel, PowerPoint)
66+
- Email mentions and interactions
67+
- Enterprise knowledge base updates
68+
- Custom application notifications
69+
70+
## Architecture
71+
72+
The notifications package follows a clean architecture pattern:
73+
74+
- **Route Selectors**: Determine which notifications match specific handlers
75+
- **Activity Wrappers**: Strongly-typed wrappers around raw notification data
76+
- **Handler Registry**: Manages registration and execution of notification handlers
77+
- **Channel Filtering**: Intelligent filtering based on Microsoft 365 application context
78+
79+
## Integration with Microsoft Agent 365 SDK
80+
81+
This package works seamlessly with other Microsoft Agent 365 SDK components:
82+
83+
| Package | Integration |
84+
|---------|-------------|
85+
| `microsoft-agents-activity` | Core activity types and protocols |
86+
| `microsoft-agents-hosting-core` | Agent lifecycle and middleware |
87+
| `microsoft-agents-authentication-msal` | Microsoft 365 authentication |
88+
| `microsoft-agents-hosting-teams` | Teams-specific hosting |
89+
90+
## Sample Applications
91+
92+
Check out these working examples:
93+
94+
| Sample | Description | Location |
95+
|--------|-------------|----------|
96+
| **Word Assistant** | Agent that helps with document writing | `samples/word-assistant/` |
97+
| **Excel Analyzer** | Data analysis agent for spreadsheets | `samples/excel-analyzer/` |
98+
| **Email Summarizer** | Automatic email summary agent | `samples/email-summarizer/` |
99+
| **Multi-App Agent** | Handles notifications from all M365 apps | `samples/multi-app-agent/` |
100+
33101
## Requirements
34102

35-
- Python 3.9+
36-
- Compatible with AI agent frameworks
103+
- **Python**: 3.11+
104+
- **Dependencies**:
105+
- `typing-extensions >= 4.0.0`
106+
- `microsoft-agents-activity >= 0.4.0`
107+
- `microsoft-agents-hosting-core >= 0.4.0`
108+
- `pydantic >= 2.0.0`
109+
110+
## Common Use Cases
111+
112+
### Document Collaboration
113+
- Respond to document updates and changes
114+
- Provide writing assistance and suggestions
115+
- Generate document summaries and reviews
116+
- Handle collaborative editing scenarios
117+
118+
### Data Analysis Assistant
119+
- Process spreadsheet updates and changes
120+
- Generate insights from data modifications
121+
- Create visualizations and reports
122+
- Assist with data analysis workflows
123+
124+
### Email Productivity
125+
- Handle email mentions and notifications
126+
- Draft responses and follow-ups
127+
- Extract action items from conversations
128+
- Manage email-based workflows
129+
130+
## Quick Links
131+
132+
📦 [All SDK Packages on PyPI](TODO: Update when packages are published)
133+
📖 [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python)
134+
💡 [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples)
135+
🐛 [Report Issues](https://github.com/microsoft/Agent365/issues)
136+
🔧 [Microsoft 365 Developer Center](https://developer.microsoft.com/microsoft-365/)
137+
138+
## License
139+
140+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/__init__.py‎

Lines changed: 26 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,30 +7,33 @@
77
This module provides utilities for handling agent notifications and routing.
88
"""
99

10-
from .agents_sdk_extensions import (
11-
AddRoute,
12-
AgentApplication,
13-
AgentNotificationExtensions,
14-
AgentsSdkExtension,
15-
ChannelId,
16-
IActivity,
17-
IRecipient,
18-
ITurnContext,
19-
OnAgentNotification,
20-
RouteHandler,
21-
RouteSelector,
10+
# Main notification handler class
11+
from .agent_notification import (
12+
AgentNotification,
13+
AgentHandler,
14+
)
15+
16+
# Import all models from the models subpackage
17+
from .models import (
18+
AgentNotificationActivity,
19+
EmailReference,
20+
WpxComment,
21+
EmailResponse,
22+
NotificationTypes,
23+
AgentSubChannel,
24+
AgentLifecycleEvent,
2225
)
2326

2427
__all__ = [
25-
"AddRoute",
26-
"AgentApplication",
27-
"AgentNotificationExtensions",
28-
"AgentsSdkExtension",
29-
"ChannelId",
30-
"IActivity",
31-
"IRecipient",
32-
"ITurnContext",
33-
"OnAgentNotification",
34-
"RouteHandler",
35-
"RouteSelector",
28+
# Main notification handler
29+
"AgentNotification",
30+
"AgentHandler",
31+
# Models and data classes
32+
"AgentNotificationActivity",
33+
"EmailReference",
34+
"WpxComment",
35+
"EmailResponse",
36+
"NotificationTypes",
37+
"AgentSubChannel",
38+
"AgentLifecycleEvent",
3639
]

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py‎

Lines changed: 80 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,27 @@
11
from __future__ import annotations
22

33
from collections.abc import Awaitable, Callable, Iterable
4-
from enum import Enum
54
from typing import Any, TypeVar
65

76
from microsoft_agents.activity import ChannelId
87
from microsoft_agents.hosting.core import TurnContext
98
from microsoft_agents.hosting.core.app.state import TurnState
10-
from .models.agent_notification_activity import AgentNotificationActivity
9+
from .models.agent_notification_activity import AgentNotificationActivity, NotificationTypes
10+
from .models.agent_subchannel import AgentSubChannel
11+
from .models.agent_lifecycle_event import AgentLifecycleEvent
1112

1213
TContext = TypeVar("TContext", bound=TurnContext)
1314
TState = TypeVar("TState", bound=TurnState)
1415

1516
AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]
1617

1718

18-
class AgentSubChannel(str, Enum):
19-
EMAIL = "email"
20-
EXCEL = "excel"
21-
WORD = "word"
22-
POWERPOINT = "powerpoint"
23-
FEDERATED_KNOWLEDGE_SERVICE = "federatedknowledgeservice"
24-
25-
2619
class AgentNotification:
2720
def __init__(
2821
self,
2922
app: Any,
3023
known_subchannels: Iterable[str | AgentSubChannel] | None = None,
24+
known_lifecycle_events: Iterable[str | AgentLifecycleEvent] | None = None,
3125
):
3226
self._app = app
3327
if known_subchannels is None:
@@ -43,6 +37,20 @@ def __init__(
4337
if normalized
4438
}
4539

40+
if known_lifecycle_events is None:
41+
source_lifecycle_events: Iterable[str | AgentLifecycleEvent] = AgentLifecycleEvent
42+
else:
43+
source_lifecycle_events = known_lifecycle_events
44+
45+
self._known_lifecycle_events = {
46+
normalized
47+
for normalized in (
48+
self._normalize_lifecycleevent(lifecycle_event)
49+
for lifecycle_event in source_lifecycle_events
50+
)
51+
if normalized
52+
}
53+
4654
def on_agent_notification(
4755
self,
4856
channel_id: ChannelId,
@@ -79,6 +87,39 @@ def decorator(handler: AgentHandler):
7987

8088
return decorator
8189

90+
def on_agent_lifecycle_notification(
91+
self,
92+
lifecycle_event: str,
93+
**kwargs: Any,
94+
):
95+
def route_selector(context: TurnContext) -> bool:
96+
ch = context.activity.channel_id
97+
received_channel = ch.channel if ch else ""
98+
received_channel = received_channel.lower()
99+
if received_channel != "agents":
100+
return False
101+
if context.activity.name != NotificationTypes.AGENT_LIFECYCLE:
102+
return False
103+
if lifecycle_event == "*":
104+
return True
105+
if context.activity.value_type not in self._known_lifecycle_events:
106+
return False
107+
return True
108+
109+
def create_handler(handler: AgentHandler):
110+
async def route_handler(context: TurnContext, state: TurnState):
111+
ana = AgentNotificationActivity(context.activity)
112+
await handler(context, state, ana)
113+
114+
return route_handler
115+
116+
def decorator(handler: AgentHandler):
117+
route_handler = create_handler(handler)
118+
self._app.add_route(route_selector, route_handler, **kwargs)
119+
return route_handler
120+
121+
return decorator
122+
82123
def on_email(
83124
self, **kwargs: Any
84125
) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
@@ -107,9 +148,38 @@ def on_powerpoint(
107148
ChannelId(channel="agents", sub_channel=AgentSubChannel.POWERPOINT), **kwargs
108149
)
109150

151+
def on_lifecycle(
152+
self, **kwargs: Any
153+
) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
154+
return self.on_lifecycle_notification("*", **kwargs)
155+
156+
def on_user_created(
157+
self, **kwargs: Any
158+
) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
159+
return self.on_lifecycle_notification(AgentLifecycleEvent.USERCREATED, **kwargs)
160+
161+
def on_user_workload_onboarding(
162+
self, **kwargs: Any
163+
) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
164+
return self.on_lifecycle_notification(
165+
AgentLifecycleEvent.USERWORKLOADONBOARDINGUPDATED, **kwargs
166+
)
167+
168+
def on_user_deleted(
169+
self, **kwargs: Any
170+
) -> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
171+
return self.on_lifecycle_notification(AgentLifecycleEvent.USERDELETED, **kwargs)
172+
110173
@staticmethod
111174
def _normalize_subchannel(value: str | AgentSubChannel | None) -> str:
112175
if value is None:
113176
return ""
114177
resolved = value.value if isinstance(value, AgentSubChannel) else str(value)
115178
return resolved.lower().strip()
179+
180+
@staticmethod
181+
def _normalize_lifecycleevent(value: str | AgentLifecycleEvent | None) -> str:
182+
if value is None:
183+
return ""
184+
resolved = value.value if isinstance(value, AgentLifecycleEvent) else str(value)
185+
return resolved.lower().strip()

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/__init__.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,16 @@
22
from .email_reference import EmailReference
33
from .wpx_comment import WpxComment
44
from .email_response import EmailResponse
5+
from .notification_types import NotificationTypes
6+
from .agent_subchannel import AgentSubChannel
7+
from .agent_lifecycle_event import AgentLifecycleEvent
58

69
__all__ = [
710
"AgentNotificationActivity",
811
"EmailReference",
912
"WpxComment",
1013
"EmailResponse",
14+
"NotificationTypes",
15+
"AgentSubChannel",
16+
"AgentLifecycleEvent",
1117
]

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_lifecycle_event.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
from enum import Enum
2+
3+
4+
class AgentLifecycleEvent(str, Enum):
5+
USERCREATED = "agenticuseridentitycreated"
6+
USERWORKLOADONBOARDINGUPDATED = "agenticuserworkloadonboardingupdated"
7+
USERDELETED = "agenticuseridentitydeleted"

0 commit comments

Comments
 (0)