nat.plugins.a365.front_end.worker

Worker for Microsoft Agent 365 front-end plugin.

This worker encapsulates the Microsoft Agents SDK integration logic, allowing for extensibility and better separation of concerns.

Attributes

logger

Classes

A365FrontEndPluginWorker

Worker that handles Microsoft Agents SDK setup and configuration.

Module Contents

logger

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.