Microsoft Agent 365 Notifications SDK

The Microsoft Agent 365 Notifications SDK extends the AgentApplication class from @microsoft/agents-hosting with a family of typed convenience methods for handling notification-shaped activities: email references, Word/Excel/PowerPoint collaboration comments, and agent identity lifecycle events (created, deleted, undeleted, updated, enabled, disabled, manager updated, workload onboarding). Rather than hand-parsing raw activity payloads and channel IDs, developers register a handler like onAgenticEmailNotification or onAgenticUserCreatedNotification and receive a strongly-typed AgentNotificationActivity wrapper with the relevant fields already extracted.

It is one of several focused packages published from the microsoft/Agent365-nodejs monorepo (alongside runtime, observability, and tooling SDKs) that together form the enterprise layer on top of the Microsoft 365 Agents SDK, targeting agents running on M365, Teams, Copilot Studio, and Webchat. The package is intentionally narrow in scope — notification and lifecycle routing only — and depends on sibling workspace packages for the underlying agent runtime and activity types.

What You Get

• A set of AgentApplication extension methods (onAgentNotification, onAgenticEmailNotification, onAgenticWordNotification, onAgenticExcelNotification, onAgenticPowerPointNotification) added via TypeScript declaration merging
• Dedicated lifecycle handlers (onAgenticUserCreatedNotification, onAgenticUserDeletedNotification, onAgenticUserEnabledNotification, onAgenticUserDisabledNotification, and more) covering the full M365 agent identity lifecycle
• A createAgentNotificationActivity() helper that parses raw activity entities into a typed AgentNotificationActivity with emailNotification, wpxCommentNotification, and a NotificationType enum
• Built-in agentic request filtering that verifies the sender role (agenticAppInstance/agenticUser) before invoking any handler
• Shared channel/lifecycle constants (AGENTS_EMAIL_SUBCHANNEL, USER_CREATED_LIFECYCLE_EVENT, etc.) so consumers never need to hardcode string literals

Common Use Cases

• Reacting to an email a user forwards or shares with an agent, using the parsed emailReference (from, subject, body preview) to decide how to respond
• Following up on Word, Excel, or PowerPoint comments that @mention an agent inside Microsoft 365 collaboration surfaces
• Initializing per-user agent state the moment a new agentic identity is created or onboarded
• Cleaning up cached state or revoking tokens when a user identity is deleted, disabled, or its manager changes

Under The Hood

Architecture The package is a small, single-purpose extension module inside a pnpm workspace monorepo; its index.ts re-exports models, extensions, and constants before the main agent-notification.ts module, which performs TypeScript declaration merging against AgentApplication from the sibling @microsoft/agents-hosting package and attaches roughly a dozen convenience methods directly onto its prototype at import time. Each public method delegates to one of two internal factories — onAgentNotificationInternal for channel-based notifications and onLifecycleNotificationInternal for lifecycle events — both of which build a Selector closure that filters on channelId or activity.name, wrap the raw TurnContext.activity via createAgentNotificationActivity(), and register the resulting route through a shared addAgenticRoute helper that layers an isAgenticRequest role check on top of the caller’s selector. It is a flat, side-effect-based extension architecture with no classes or DI container; its only real coupling risk is to the shape of AgentApplication.addRoute in the package it patches.

Tech Stack Written in strict TypeScript (ES2020 target), dual-built to CommonJS and ESM via separate tsconfig.cjs.json/tsconfig.esm.json projects and plain tsc, and tested with ts-jest/Jest (--passWithNoTests, since no tests exist yet for this package specifically). It depends on the workspace-linked @microsoft/agents-a365-runtime and catalog-pinned @microsoft/agents-activity/@microsoft/agents-hosting — the core Microsoft 365 Agents SDK — all orchestrated by pnpm workspaces with catalog: version pinning, and built/tested in GitHub Actions across a Node 18/20 matrix.

Code Quality No .test.ts or .spec.ts files exist under this package’s src/ directory, so despite Jest/ts-jest being wired up at both the package and monorepo level, it currently ships with zero package-specific unit tests. Style discipline elsewhere is solid: every exported function carries JSDoc, strict TypeScript is enforced with almost no any usage, small pure helpers (isAgenticChannel, isValidChannel, isValidLifecycleEvent) keep validation logic isolated, and ESLint plus typescript-eslint run as part of CI.

API Design The headline ergonomic choice is using declaration merging to bolt roughly a dozen semantically named onAgentic*Notification methods onto AgentApplication, so consumers get IDE autocomplete and typed handlers (AgentNotificationHandler<TState>) without extending or wrapping a base class — just import '@microsoft/agents-a365-notifications' for its side effect, then call app.onAgenticEmailNotification(...). Naming is consistent and self-documenting throughout. The rough edge is that this is a global, import-order-sensitive prototype patch rather than an explicit dependency, and this specific package’s own README is a short stub that defers all usage detail to the monorepo’s docs/design.md and external Microsoft Learn documentation.