Add BaggageMiddleware, OutputLoggingMiddleware, and ObservabilityHostingManager

Implement Python equivalents of the Node.js PR #210 middleware:
- BaggageMiddleware: propagates OpenTelemetry baggage from TurnContext
- OutputLoggingMiddleware: creates OutputScope spans for outgoing messages
- ObservabilityHostingManager: singleton to configure hosting middleware
- 19 unit tests covering all three middleware components

Co-authored-by: nikhilNava <211831449+nikhilNava@users.noreply.github.com>

Author: Copilot

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/__init__.py

@@ -4,3 +4,18 @@
 """
 Microsoft Agent 365 Observability Hosting Library.
 """
+
+from .middleware.baggage_middleware import BaggageMiddleware
+from .middleware.observability_hosting_manager import (
+    ObservabilityHostingManager,
+    ObservabilityHostingOptions,
+)
+from .middleware.output_logging_middleware import A365_PARENT_SPAN_KEY, OutputLoggingMiddleware
+
+__all__ = [
+    "BaggageMiddleware",
+    "OutputLoggingMiddleware",
+    "A365_PARENT_SPAN_KEY",
+    "ObservabilityHostingManager",
+    "ObservabilityHostingOptions",
+]

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from .baggage_middleware import BaggageMiddleware
+from .observability_hosting_manager import ObservabilityHostingManager, ObservabilityHostingOptions
+from .output_logging_middleware import A365_PARENT_SPAN_KEY, OutputLoggingMiddleware
+
+__all__ = [
+    "BaggageMiddleware",
+    "OutputLoggingMiddleware",
+    "A365_PARENT_SPAN_KEY",
+    "ObservabilityHostingManager",
+    "ObservabilityHostingOptions",
+]

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/baggage_middleware.py

@@ -0,0 +1,47 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Middleware that propagates OpenTelemetry baggage context derived from TurnContext."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+
+from microsoft_agents.activity import ActivityEventNames, ActivityTypes
+from microsoft_agents.hosting.core.turn_context import TurnContext
+from microsoft_agents_a365.observability.core.middleware.baggage_builder import BaggageBuilder
+
+from ..scope_helpers.populate_baggage import populate
+
+logger = logging.getLogger(__name__)
+
+
+class BaggageMiddleware:
+    """Middleware that propagates OpenTelemetry baggage context derived from TurnContext.
+
+    Async replies (ContinueConversation) are passed through without baggage setup.
+    """
+
+    async def on_turn(
+        self,
+        context: TurnContext,
+        logic: Callable[[TurnContext], Awaitable],
+    ) -> None:
+        activity = context.activity
+        is_async_reply = (
+            activity is not None
+            and activity.type == ActivityTypes.event
+            and activity.name == ActivityEventNames.continue_conversation
+        )
+
+        if is_async_reply:
+            await logic()
+            return
+
+        builder = BaggageBuilder()
+        populate(builder, context)
+        baggage_scope = builder.build()
+
+        with baggage_scope:
+            await logic()

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/observability_hosting_manager.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Singleton manager for configuring hosting-layer observability middleware."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Protocol
+
+from microsoft_agents.hosting.core import Middleware
+
+from .baggage_middleware import BaggageMiddleware
+from .output_logging_middleware import OutputLoggingMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class _AdapterLike(Protocol):
+    """Protocol for adapter objects that support middleware registration."""
+
+    def use(self, middleware: Middleware) -> object: ...
+
+
+@dataclass
+class ObservabilityHostingOptions:
+    """Configuration options for the hosting observability layer."""
+
+    enable_baggage: bool = True
+    """Enable baggage propagation middleware. Defaults to ``True``."""
+
+    enable_output_logging: bool = False
+    """Enable output logging middleware for tracing outgoing messages. Defaults to ``False``."""
+
+
+class ObservabilityHostingManager:
+    """Singleton manager for configuring hosting-layer observability middleware.
+
+    Example:
+        .. code-block:: python
+
+            ObservabilityHostingManager.configure(adapter, ObservabilityHostingOptions(
+                enable_output_logging=True,
+            ))
+    """
+
+    _instance: ObservabilityHostingManager | None = None
+
+    def __init__(self) -> None:
+        """Private constructor — use :meth:`configure` instead."""
+
+    @classmethod
+    def configure(
+        cls,
+        adapter: _AdapterLike | None = None,
+        options: ObservabilityHostingOptions | None = None,
+    ) -> ObservabilityHostingManager:
+        """Configure the singleton instance and register middleware on the adapter.
+
+        Subsequent calls after the first are no-ops and return the existing instance.
+
+        Args:
+            adapter: An adapter that supports ``.use()`` for middleware registration.
+            options: Configuration options. Defaults are used when ``None``.
+
+        Returns:
+            The singleton :class:`ObservabilityHostingManager` instance.
+        """
+        if cls._instance is not None:
+            logger.warning(
+                "[ObservabilityHostingManager] Already configured. "
+                "Subsequent configure() calls are ignored."
+            )
+            return cls._instance
+
+        instance = cls()
+
+        if adapter is not None:
+            opts = options or ObservabilityHostingOptions()
+
+            if opts.enable_baggage:
+                adapter.use(BaggageMiddleware())
+                logger.info("[ObservabilityHostingManager] BaggageMiddleware registered.")
+
+            if opts.enable_output_logging:
+                adapter.use(OutputLoggingMiddleware())
+                logger.info("[ObservabilityHostingManager] OutputLoggingMiddleware registered.")
+
+            logger.info(
+                "[ObservabilityHostingManager] Configured. Baggage: %s, OutputLogging: %s.",
+                opts.enable_baggage,
+                opts.enable_output_logging,
+            )
+        else:
+            logger.warning(
+                "[ObservabilityHostingManager] No adapter provided. No middleware registered."
+            )
+
+        cls._instance = instance
+        return instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance. Intended for testing only."""
+        cls._instance = None