nat.plugins.a365.front_end#

Microsoft Agent 365 front-end plugin.

Submodules#

Exceptions#

`A365AuthenticationError`	Authentication-related errors.
`A365ConfigurationError`	Configuration-related errors.
`A365Error`	Base exception for A365 plugin errors.
`A365SDKError`	Errors related to Microsoft Agents SDK components.
`A365WorkflowExecutionError`	Errors during workflow execution.

Classes#

`A365FrontEndConfig`	Microsoft Agent 365 front-end configuration.
`A365FrontEndPlugin`	Microsoft Agent 365 front-end plugin.
`A365FrontEndPluginWorker`	Worker that handles Microsoft Agents SDK setup and configuration.

Package Contents#

exception A365AuthenticationError( message: str, original_error: Exception | None = None, )#

Bases: A365Error

Authentication-related errors.

Used for authentication failures across A365 modules: - Front-end: Bot Framework authentication failures - Tooling: A365 Gateway and MCP server authentication failures - Telemetry: Token resolver authentication failures

Initialize self. See help(type(self)) for accurate signature.

original_error = None#

exception A365ConfigurationError( message: str, original_error: Exception | None = None, )#

Bases: A365Error

Configuration-related errors.

Used for configuration validation failures across A365 modules: - Front-end: Invalid front-end configuration (missing fields, wrong types) - Tooling: Invalid tooling configuration (reconnect settings, auth config) - Telemetry: Invalid telemetry configuration (token resolver path)

Initialize self. See help(type(self)) for accurate signature.

original_error = None#

exception A365Error#

Bases: Exception

Base exception for A365 plugin errors.

Initialize self. See help(type(self)) for accurate signature.

exception A365SDKError( message: str, sdk_component: str | None = None, original_error: Exception | None = None, )#

Bases: A365Error

Errors related to Microsoft Agents SDK components.

Used for SDK-related errors across A365 modules: - Front-end: Microsoft Agents SDK (AgentApplication, CloudAdapter, etc.) - Telemetry: Agent365Exporter SDK errors - Tooling: McpToolServerConfigurationService SDK errors

Initialize self. See help(type(self)) for accurate signature.

sdk_component = None#

original_error = None#

exception A365WorkflowExecutionError( message: str, workflow_type: str = 'workflow', original_error: Exception | None = None, )#

Bases: A365Error

Errors during workflow execution.

Used when NAT workflows fail during execution in A365 handlers.

Initialize self. See help(type(self)) for accurate signature.

workflow_type = 'workflow'#

original_error = None#

class A365FrontEndConfig#

Bases: nat.data_models.front_end.FrontEndBaseConfig

Microsoft Agent 365 front-end configuration.

This front-end integrates NAT workflows with Microsoft Agent 365 hosting framework, enabling workflows to receive notifications from Teams, Email, and Office 365 apps.

Authentication uses Entra ID (Azure AD) App Registration credentials (app_id and app_password) created when registering your bot in Azure Portal. The Microsoft Agents SDK authenticates with Entra ID via MsalConnectionManager to enable bot communication with Teams and Office 365.

host: str = None#

port: int = None#

app_id: str = None#

app_password: nat.data_models.common.OptionalSecretStr = None#

tenant_id: str | None = None#

allowed_audiences: list[str] = None#

log_level: str = None#

enable_notifications: bool = None#

notification_workflow: str | None = None#

runner_class: str | None = None#

validate_security_configuration()#: Validate security configuration to prevent accidental misconfigurations.

classmethod normalize_allowed_audiences(value)#: Accept YAML lists or comma-delimited strings for audience aliases.

classmethod warn_on_suspicious_allowed_audiences(value: list[str]) → list[str]#

Warn (don’t reject) on entries that don’t look like real audiences.

Real Microsoft audiences are either a GUID (the bot’s app_id or another registered app’s), a fully-qualified URL such as https://api.botframework.com, or a Microsoft resource ID. Anything much shorter or containing internal whitespace is almost certainly a typo.

We emit a warning instead of raising because Microsoft may introduce new canonical audiences in the future and we shouldn’t gate config load on a heuristic. The warning surfaces the typo early; the deployment still loads.

class A365FrontEndPlugin#

Bases: nat.builder.front_end.FrontEndBase[nat.plugins.a365.front_end.front_end_config.A365FrontEndConfig]

Microsoft Agent 365 front-end plugin.

This plugin integrates NAT workflows with Microsoft Agent 365 hosting framework, allowing workflows to receive and respond to notifications from Teams, Email, and Office 365.

async run() → None#

Run the Microsoft Agent 365 server.

This method orchestrates the workflow lifecycle: 1. Imports and validates Microsoft Agents SDK dependencies 2. Configures logging 3. Builds NAT workflows and creates session managers 4. Delegates SDK setup to worker 5. Starts the Microsoft Agents SDK server 6. Handles cleanup on shutdown

_get_worker_instance() → nat.plugins.a365.front_end.worker.A365FrontEndPluginWorker#

Instantiate the worker (default or runner_class override).

runner_class must be a dotted path pkg.module.ClassName (same pattern as MCP / A2A front-ends): last segment is the class, everything before is the module.

class A365FrontEndPluginWorker(config: nat.data_models.config.Config)#

Worker that handles Microsoft Agents SDK setup and configuration.

This class encapsulates the implementation details of integrating NAT workflows with the Microsoft Agents SDK, allowing for extensibility through subclassing and better separation of concerns from the plugin orchestration logic.

Initialize the A365 worker with configuration.

Args:: config: The full NAT configuration

full_config#

front_end_config: nat.plugins.a365.front_end.front_end_config.A365FrontEndConfig#

_get_storage() → microsoft_agents.hosting.core.storage.Storage#

Get the storage instance for the AgentApplication.

Uses dependency injection pattern - returns Storage Protocol implementation. Defaults to MemoryStorage, but can be overridden for custom storage (e.g., BlobStorage, CosmosDbStorage).

Returns:: Storage: A Storage Protocol implementation (default: MemoryStorage)

_build_connection_configurations( service_connection: microsoft_agents.hosting.core.AgentAuthConfiguration, ) → dict[str, microsoft_agents.hosting.core.AgentAuthConfiguration]#

Build SDK connection configs, including optional JWT audience aliases.

The Microsoft Agents SDK validates inbound JWT audiences via AgentAuthConfiguration._jwt_patch_is_valid_aud (a private SDK method, as indicated by the _jwt_patch_ prefix). MsalConnectionManager.__init__ cross-populates AgentAuthConfiguration._connections on every config in connections_configurations (the “# JWT-patch” loop in 0.8.0 wheels), so adding alias entries here is enough to make Bot Framework / Teams tokens with non-app_id audiences pass JWT validation.

SECURITY NOTE: alias entries are constructed as fully-functional AgentAuthConfiguration objects carrying the bot’s real client_secret. Today the SDK only consults aliases on the inbound audience-validation path, but each alias is also registered as an outbound MsalAuth provider keyed by the alias client_id. If a future SDK feature (e.g. connections_map) routes outbound token acquisition through an alias, MSAL will attempt to mint a token for client_id=<alias_audience> using the bot’s secret – which Azure AD will reject. This is not a credential-leak vector but it does mean the secret is now copied into N+1 in-memory MsalAuth instances. Worth revisiting if/when the SDK exposes an audience-only validation API.

STABILITY NOTE: the underlying mechanism depends on SDK private members (_connections, _jwt_patch_is_valid_aud). A test in tests/front_end/test_integration.py exercises the SDK end-to-end so regressions surface before shipping.

_get_connection_manager( service_connection: microsoft_agents.hosting.core.AgentAuthConfiguration, ) → microsoft_agents.hosting.core.authorization.Connections#

Get the connection manager instance for the AgentApplication.

Defaults to MsalConnectionManager with a single SERVICE_CONNECTION entry (required by the Microsoft Agents SDK 0.8+ MSAL integration).

Args:: service_connection: Auth configuration for the bot’s service connection.
Returns:: Connections: A Connections implementation (default: MsalConnectionManager)

async create_agent_application() → tuple[microsoft_agents.hosting.core.AgentApplication[microsoft_agents.hosting.core.TurnState], microsoft_agents.hosting.core.authorization.Connections, microsoft_agents.hosting.aiohttp.CloudAdapter]#

Create and initialize Microsoft Agents SDK application.

Returns:: Initialized AgentApplication, Connections (MSAL manager), and aiohttp CloudAdapter (used by the HTTP server and AgentApplication options).
Raises:: A365ConfigurationError: If configuration is invalid (missing fields, wrong types) A365SDKError: If SDK component initialization fails

async setup_notification_handlers( agent_app: microsoft_agents.hosting.core.AgentApplication, session_manager: nat.runtime.session.SessionManager, ) → None#

Set up A365 notification handlers.

Args:: agent_app: The Microsoft Agents SDK AgentApplication instance session_manager: SessionManager for executing NAT workflows

async setup_message_handlers( agent_app: microsoft_agents.hosting.core.AgentApplication, session_manager: nat.runtime.session.SessionManager, ) → None#

Set up message handlers for regular chat messages.

Args:: agent_app: The Microsoft Agents SDK AgentApplication instance session_manager: SessionManager for executing NAT workflows

setup_error_handlers( agent_app: microsoft_agents.hosting.core.AgentApplication, ) → None#

Set up error handlers for the AgentApplication.

Args:: agent_app: The Microsoft Agents SDK AgentApplication instance

async cleanup() → None#

Clean up any resources managed by the worker.

Currently, the worker doesn’t manage any resources that need explicit cleanup, but this method is provided for consistency with other workers and future extensibility.