microsoft-agents-a365-observability-hosting 0.2.1.dev0__py3-none-any.whl

microsoft_agents_a365/observability/hosting/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Microsoft Agent 365 Observability Hosting Library.
+"""

microsoft_agents_a365/observability/hosting/scope_helpers/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.

microsoft_agents_a365/observability/hosting/scope_helpers/populate_baggage.py

@@ -0,0 +1,45 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from microsoft_agents.hosting.core.turn_context import TurnContext
+from microsoft_agents_a365.observability.core.middleware.baggage_builder import BaggageBuilder
+
+from .utils import (
+    get_caller_pairs,
+    get_conversation_pairs,
+    get_execution_type_pair,
+    get_source_metadata_pairs,
+    get_target_agent_pairs,
+    get_tenant_id_pair,
+)
+
+
+def _iter_all_pairs(turn_context: TurnContext) -> Iterator[tuple[str, Any]]:
+    activity = turn_context.activity
+    if not activity:
+        return
+    yield from get_caller_pairs(activity)
+    yield from get_execution_type_pair(activity)
+    yield from get_target_agent_pairs(activity)
+    yield from get_tenant_id_pair(activity)
+    yield from get_source_metadata_pairs(activity)
+    yield from get_conversation_pairs(activity)
+
+
+def populate(builder: BaggageBuilder, turn_context: TurnContext) -> BaggageBuilder:
+    """Populate BaggageBuilder with baggage values extracted from a turn context.
+
+    Args:
+        builder: The BaggageBuilder instance to populate
+        turn_context: The TurnContext containing activity information
+
+    Returns:
+        The updated BaggageBuilder instance (for method chaining)
+    """
+    builder.set_pairs(_iter_all_pairs(turn_context))
+    return builder

microsoft_agents_a365/observability/hosting/scope_helpers/populate_invoke_agent_scope.py

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from microsoft_agents_a365.observability.core.invoke_agent_scope import InvokeAgentScope
+
+from .utils import (
+    get_caller_pairs,
+    get_conversation_pairs,
+    get_execution_type_pair,
+    get_source_metadata_pairs,
+    get_target_agent_pairs,
+    get_tenant_id_pair,
+)
+
+if TYPE_CHECKING:
+    from microsoft_agents.hosting.core.turn_context import TurnContext
+
+
+def populate(scope: InvokeAgentScope, turn_context: TurnContext) -> InvokeAgentScope:
+    """
+    Populate all supported InvokeAgentScope tags from the provided TurnContext.
+    :param scope: The InvokeAgentScope instance to populate.
+    :param turn_context: The TurnContext containing activity information.
+    :return: The updated InvokeAgentScope instance.
+    """
+    if not turn_context:
+        raise ValueError("turn_context is required")
+
+    if not turn_context.activity:
+        return scope
+
+    activity = turn_context.activity
+
+    scope.record_attributes(get_caller_pairs(activity))
+    scope.record_attributes(get_execution_type_pair(activity))
+    scope.record_attributes(get_target_agent_pairs(activity))
+    scope.record_attributes(get_tenant_id_pair(activity))
+    scope.record_attributes(get_source_metadata_pairs(activity))
+    scope.record_attributes(get_conversation_pairs(activity))
+
+    if activity.text:
+        scope.record_input_messages([activity.text])
+
+    return scope

microsoft_agents_a365/observability/hosting/scope_helpers/utils.py

@@ -0,0 +1,114 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+from collections.abc import Iterator
+from typing import Any
+
+from microsoft_agents.activity import Activity
+from microsoft_agents_a365.observability.core.constants import (
+    GEN_AI_AGENT_AUID_KEY,
+    GEN_AI_AGENT_DESCRIPTION_KEY,
+    GEN_AI_AGENT_ID_KEY,
+    GEN_AI_AGENT_NAME_KEY,
+    GEN_AI_AGENT_UPN_KEY,
+    GEN_AI_CALLER_ID_KEY,
+    GEN_AI_CALLER_NAME_KEY,
+    GEN_AI_CALLER_TENANT_ID_KEY,
+    GEN_AI_CALLER_UPN_KEY,
+    GEN_AI_CONVERSATION_ID_KEY,
+    GEN_AI_CONVERSATION_ITEM_LINK_KEY,
+    GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY,
+    GEN_AI_EXECUTION_SOURCE_NAME_KEY,
+    GEN_AI_EXECUTION_TYPE_KEY,
+    TENANT_ID_KEY,
+)
+from microsoft_agents_a365.observability.core.execution_type import ExecutionType
+
+AGENT_ROLE = "agenticUser"
+
+
+def _is_agentic(entity: Any) -> bool:
+    if not entity:
+        return False
+    return bool(
+        entity.agentic_user_id
+        or ((role := entity.role) and isinstance(role, str) and role.lower() == AGENT_ROLE.lower())
+    )
+
+
+def get_caller_pairs(activity: Activity) -> Iterator[tuple[str, Any]]:
+    frm = activity.from_property
+    if not frm:
+        return
+    yield GEN_AI_CALLER_ID_KEY, frm.aad_object_id
+    yield GEN_AI_CALLER_NAME_KEY, frm.name
+    yield GEN_AI_CALLER_UPN_KEY, frm.agentic_user_id
+    yield GEN_AI_CALLER_TENANT_ID_KEY, frm.tenant_id
+
+
+def get_execution_type_pair(activity: Activity) -> Iterator[tuple[str, Any]]:
+    frm = activity.from_property
+    rec = activity.recipient
+    is_agentic_caller = _is_agentic(frm)
+    is_agentic_recipient = _is_agentic(rec)
+    exec_type = (
+        ExecutionType.AGENT_TO_AGENT.value
+        if (is_agentic_caller and is_agentic_recipient)
+        else ExecutionType.HUMAN_TO_AGENT.value
+    )
+    yield GEN_AI_EXECUTION_TYPE_KEY, exec_type
+
+
+def get_target_agent_pairs(activity: Activity) -> Iterator[tuple[str, Any]]:
+    rec = activity.recipient
+    if not rec:
+        return
+    yield GEN_AI_AGENT_ID_KEY, rec.agentic_app_id
+    yield GEN_AI_AGENT_NAME_KEY, rec.name
+    yield GEN_AI_AGENT_AUID_KEY, rec.aad_object_id
+    yield GEN_AI_AGENT_UPN_KEY, rec.agentic_user_id
+    yield (
+        GEN_AI_AGENT_DESCRIPTION_KEY,
+        rec.role,
+    )
+
+
+def get_tenant_id_pair(activity: Activity) -> Iterator[tuple[str, Any]]:
+    yield TENANT_ID_KEY, activity.recipient.tenant_id
+
+
+def get_source_metadata_pairs(activity: Activity) -> Iterator[tuple[str, Any]]:
+    """
+    Generate source metadata pairs from activity, handling both string and ChannelId object cases.
+
+    :param activity: The activity object (Activity instance or dict)
+    :return: Iterator of (key, value) tuples for source metadata
+    """
+    # Handle channel_id (can be string or ChannelId object)
+    channel_id = activity.channel_id
+
+    # Extract channel name from either string or ChannelId object
+    channel_name = None
+    sub_channel = None
+
+    if channel_id is not None:
+        if isinstance(channel_id, str):
+            # Direct string value
+            channel_name = channel_id
+        elif hasattr(channel_id, "channel"):
+            # ChannelId object
+            channel_name = channel_id.channel
+            sub_channel = channel_id.sub_channel
+
+    # Yield channel name as source name
+    yield GEN_AI_EXECUTION_SOURCE_NAME_KEY, channel_name
+    yield GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY, sub_channel
+
+
+def get_conversation_pairs(activity: Activity) -> Iterator[tuple[str, Any]]:
+    conv = activity.conversation
+    conversation_id = conv.id if conv else None
+
+    item_link = activity.service_url
+
+    yield GEN_AI_CONVERSATION_ID_KEY, conversation_id
+    yield GEN_AI_CONVERSATION_ITEM_LINK_KEY, item_link

microsoft_agents_a365/observability/hosting/token_cache_helpers/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Token cache helpers for observability."""
+
+from .agent_token_cache import AgenticTokenCache, AgenticTokenStruct
+
+__all__ = ["AgenticTokenCache", "AgenticTokenStruct"]

microsoft_agents_a365/observability/hosting/token_cache_helpers/agent_token_cache.py

@@ -0,0 +1,137 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Token cache for observability tokens per (agentId, tenantId).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from threading import Lock
+
+from microsoft_agents.hosting.core.app.oauth.authorization import Authorization
+from microsoft_agents.hosting.core.turn_context import TurnContext
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgenticTokenStruct:
+    """Structure containing the token generation components."""
+
+    authorization: Authorization
+    """The user authorization object for token exchange."""
+
+    turn_context: TurnContext
+    """The turn context for the current conversation."""
+
+    auth_handler_name: str | None = "AGENTIC"
+    """The name of the authentication handler."""
+
+
+class AgenticTokenCache:
+    """
+    Caches observability tokens per (agentId, tenantId) using the provided
+    UserAuthorization and TurnContext.
+    """
+
+    @dataclass
+    class _Entry:
+        """Internal entry structure for cache storage."""
+
+        agentic_token_struct: AgenticTokenStruct
+        """The token generation structure."""
+
+        scopes: list[str]
+        """The observability scopes for token requests."""
+
+    def __init__(self) -> None:
+        """Initialize the token cache."""
+        self._map: dict[str, AgenticTokenCache._Entry] = {}
+        self._lock = Lock()
+
+    def register_observability(
+        self,
+        agent_id: str,
+        tenant_id: str,
+        token_generator: AgenticTokenStruct,
+        observability_scopes: list[str],
+    ) -> None:
+        """
+        Register observability for the specified agent and tenant.
+
+        Args:
+            agent_id: The agent identifier.
+            tenant_id: The tenant identifier.
+            token_generator: The token generator structure.
+            observability_scopes: The observability scopes.
+
+        Raises:
+            ValueError: If agent_id or tenant_id is empty or None.
+            TypeError: If token_generator is None.
+        """
+        if not agent_id or not agent_id.strip():
+            raise ValueError("agent_id cannot be None or whitespace")
+
+        if not tenant_id or not tenant_id.strip():
+            raise ValueError("tenant_id cannot be None or whitespace")
+
+        if token_generator is None:
+            raise TypeError("token_generator cannot be None")
+
+        key = f"{agent_id}:{tenant_id}"
+
+        # First registration wins; subsequent calls ignored (idempotent)
+        with self._lock:
+            if key not in self._map:
+                self._map[key] = AgenticTokenCache._Entry(
+                    agentic_token_struct=token_generator, scopes=observability_scopes
+                )
+                logger.debug(f"Registered observability for {key}")
+            else:
+                logger.debug(f"Observability already registered for {key}, ignoring")
+
+    async def get_observability_token(self, agent_id: str, tenant_id: str) -> str | None:
+        """
+        Get the observability token for the specified agent and tenant.
+
+        Args:
+            agent_id: The agent identifier.
+            tenant_id: The tenant identifier.
+
+        Returns:
+            The observability token if available; otherwise, None.
+        """
+        key = f"{agent_id}:{tenant_id}"
+
+        logger.debug(f"Cache lookup for {key}")
+
+        with self._lock:
+            entry = self._map.get(key)
+
+        if entry is None:
+            logger.debug(f"Cache miss for {key}")
+            return None
+
+        logger.debug(f"Cache hit for {key}, exchanging token")
+
+        try:
+            authorization = entry.agentic_token_struct.authorization
+            turn_context = entry.agentic_token_struct.turn_context
+            auth_handler_id = entry.agentic_token_struct.auth_handler_name
+
+            # Exchange the turn token for an observability token
+            token = await authorization.exchange_token(
+                context=turn_context,
+                scopes=entry.scopes,
+                auth_handler_id=auth_handler_id,
+            )
+
+            logger.info(f"Successfully exchanged token for {key}")
+            return token
+        except Exception as e:
+            # Return None if token generation fails
+            logger.error(f"Token exchange failed for {key}: {type(e).__name__}")
+            return None

microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-a365-observability-hosting
+Version: 0.2.1.dev0
+Summary: Hosting components for Agent 365 observability
+Author-email: Microsoft <support@microsoft.com>
+License: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agent365-python
+Project-URL: Repository, https://github.com/microsoft/Agent365-python
+Project-URL: Issues, https://github.com/microsoft/Agent365-python/issues
+Project-URL: Documentation, https://github.com/microsoft/Agent365-python/tree/main/libraries/microsoft-agents-a365-observability-hosting
+Keywords: observability,telemetry,tracing,opentelemetry,monitoring,ai,agents,hosting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: microsoft-agents-hosting-core<0.6.0,>=0.4.0
+Requires-Dist: microsoft-agents-a365-observability-core>=0.0.0
+Requires-Dist: opentelemetry-api>=1.36.0
+
+# Microsoft Agent 365 Observability Hosting Library
+
+This library provides hosting components for Agent 365 observability.
+
+## Installation
+
+```bash
+pip install microsoft-agents-a365-observability-hosting
+```

microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/RECORD

@@ -0,0 +1,11 @@
+microsoft_agents_a365/observability/hosting/__init__.py,sha256=94JvLF3ymPp0EfJMRPEhWWsBljFlAM1O5aXFImFgpqw,133
+microsoft_agents_a365/observability/hosting/scope_helpers/__init__.py,sha256=HIog-luBqQnLkza1Q8b34Rr1QVu6tuiAy5sOry0vIPg,73
+microsoft_agents_a365/observability/hosting/scope_helpers/populate_baggage.py,sha256=y39TwqC0RDQkuDf1nyRSn9Z6yX3e8h_rjjCzOLKOuNI,1419
+microsoft_agents_a365/observability/hosting/scope_helpers/populate_invoke_agent_scope.py,sha256=h2d9kJy-fprnilmWXOC7m9OX-66dOupcrHJNay0QSQI,1513
+microsoft_agents_a365/observability/hosting/scope_helpers/utils.py,sha256=Ic1rOxCIT08K-UCwkwjcVCbF_hxysMoCg7a_AgpCJfM,3694
+microsoft_agents_a365/observability/hosting/token_cache_helpers/__init__.py,sha256=cLrxkhOtq7WXyhdAfn_vCdJpbf6K0y283MGcfQIqZq0,243
+microsoft_agents_a365/observability/hosting/token_cache_helpers/agent_token_cache.py,sha256=iVbhYpnLLMx-PSM_jlcMTkVDAz4J8KgWWUQwYkZoxRQ,4380
+microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/METADATA,sha256=g7tF4cVcL2yjyG1lDf5LfxvKk_9mlhos_A-2rC6pQZo,1550
+microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/RECORD,,

microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_a365_observability_hosting-0.2.1.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents_a365