|
1 | | -# Microsoft Agent 365 Notifications |
2 | | -[](https://badge.fury.io/py/microsoft-agents-a365-notifications) |
| 1 | +# microsoft-agents-a365-notifications |
3 | 2 |
|
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. |
| 3 | +[](https://pypi.org/project/microsoft-agents-a365-notifications) |
| 4 | +[](https://pypi.org/project/microsoft-agents-a365-notifications) |
5 | 5 |
|
6 | | -## What is this? |
7 | | - |
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. |
9 | | - |
10 | | -## Key Features |
11 | | - |
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 |
| 6 | +Notification and messaging extensions for AI agent applications. This package provides utilities for handling agent notifications, lifecycle events, and routing across different channels and subchannels in Microsoft 365 applications. |
18 | 7 |
|
19 | 8 | ## Installation |
20 | 9 |
|
21 | 10 | ```bash |
22 | 11 | pip install microsoft-agents-a365-notifications |
23 | 12 | ``` |
24 | 13 |
|
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 | | - |
101 | | -## Requirements |
102 | | - |
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 |
| 14 | +## Usage |
| 15 | + |
| 16 | +### Basic Notification Handler |
| 17 | + |
| 18 | +```python |
| 19 | +from microsoft_agents_a365.notifications import AgentNotification, AgentNotificationActivity |
| 20 | +from microsoft_agents.activity import ChannelId |
| 21 | +from microsoft_agents.hosting.core import TurnContext, TurnState |
| 22 | + |
| 23 | +# Initialize notification handler |
| 24 | +agent_notification = AgentNotification( |
| 25 | + app=app, |
| 26 | + known_subchannels=["email", "word", "excel"], |
| 27 | +) |
| 28 | + |
| 29 | +# Register notification handler for specific channel |
| 30 | +@agent_notification.on_agent_notification( |
| 31 | + channel_id=ChannelId(channel="msteams", sub_channel="email") |
| 32 | +) |
| 33 | +async def handle_email_notification( |
| 34 | + context: TurnContext, |
| 35 | + state: TurnState, |
| 36 | + notification: AgentNotificationActivity |
| 37 | +): |
| 38 | + # Process email notification |
| 39 | + print(f"Received notification: {notification.notification_type}") |
| 40 | + await context.send_activity("Processing your email notification") |
| 41 | +``` |
117 | 42 |
|
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 |
| 43 | +### Handle Multiple Subchannels |
| 44 | + |
| 45 | +```python |
| 46 | +# Handle all notifications for a channel (wildcard) |
| 47 | +@agent_notification.on_agent_notification( |
| 48 | + channel_id=ChannelId(channel="msteams", sub_channel="*") |
| 49 | +) |
| 50 | +async def handle_all_notifications( |
| 51 | + context: TurnContext, |
| 52 | + state: TurnState, |
| 53 | + notification: AgentNotificationActivity |
| 54 | +): |
| 55 | + # Route based on notification type |
| 56 | + if notification.notification_type == "email": |
| 57 | + await handle_email(context, notification) |
| 58 | + elif notification.notification_type == "document": |
| 59 | + await handle_document(context, notification) |
| 60 | +``` |
123 | 61 |
|
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 |
| 62 | +## Support |
129 | 63 |
|
130 | | -## Quick Links |
| 64 | +For issues, questions, or feedback: |
131 | 65 |
|
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/) |
| 66 | +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section |
| 67 | +- See the [main documentation](../../../README.md) for more information |
137 | 68 |
|
138 | 69 | ## License |
139 | 70 |
|
140 | | -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |
| 71 | +Copyright (c) Microsoft Corporation. All rights reserved. |
| 72 | + |
| 73 | +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. |
0 commit comments