microsoft-agents-a365-observability-core 0.2.1.dev42__tar.gz → 0.2.1.dev44__tar.gz

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-a365-observability-core
-Version: 0.2.1.dev42
+Version: 0.2.1.dev44
 Summary: Telemetry, tracing, and monitoring components for AI agents
 Author-email: Microsoft <support@microsoft.com>
 License: MIT

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/__init__.py

@@ -28,11 +28,12 @@ from .invoke_agent_scope import InvokeAgentScope
 from .middleware.baggage_builder import BaggageBuilder
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
-from .source_metadata import SourceMetadata
+from .channel import Channel
 from .tenant_details import TenantDetails
 from .tool_call_details import ToolCallDetails
 from .tool_type import ToolType
 from .trace_processor.span_processor import SpanProcessor
+from .utils import extract_context_from_headers, get_traceparent
 
 __all__ = [
     # Main SDK functions
@@ -63,7 +64,7 @@ __all__ = [
     "AgentDetails",
     "TenantDetails",
     "ToolCallDetails",
-    "SourceMetadata",
+    "Channel",
     "Request",
     "InferenceCallDetails",
     "ServiceEndpoint",
@@ -71,6 +72,9 @@ __all__ = [
     "ExecutionType",
     "InferenceOperationType",
     "ToolType",
+    # Utility functions
+    "extract_context_from_headers",
+    "get_traceparent",
     # Constants
     # all constants from constants.py are exported via *
 ]

microsoft_agents_a365_observability_core-0.2.1.dev44/microsoft_agents_a365/observability/core/channel.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# Channel class.
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Channel:
+    """Channel information for agent execution context."""
+
+    name: str | None = None
+    link: str | None = None

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/constants.py

@@ -60,15 +60,15 @@ GEN_AI_TOOL_ARGS_KEY = "gen_ai.tool.call.arguments"
 GEN_AI_TOOL_CALL_RESULT_KEY = "gen_ai.tool.call.result"
 GEN_AI_TOOL_TYPE_KEY = "gen_ai.tool.type"
 
-# Agent user (user tied to agent instance during creation) or caller dimensions
-GEN_AI_CALLER_ID_KEY = "microsoft.caller.id"
-GEN_AI_CALLER_NAME_KEY = "microsoft.caller.name"
-GEN_AI_CALLER_UPN_KEY = "microsoft.caller.upn"
+# Human caller dimensions (OTel user.* namespace)
+USER_ID_KEY = "user.id"
+USER_NAME_KEY = "user.name"
+USER_EMAIL_KEY = "user.email"
 GEN_AI_CALLER_CLIENT_IP_KEY = "client.address"
 
 # Agent to Agent caller agent dimensions
 GEN_AI_CALLER_AGENT_USER_ID_KEY = "microsoft.a365.caller.agent.user.id"
-GEN_AI_CALLER_AGENT_UPN_KEY = "microsoft.a365.caller.agent.user.upn"
+GEN_AI_CALLER_AGENT_EMAIL_KEY = "microsoft.a365.caller.agent.user.email"
 GEN_AI_CALLER_AGENT_NAME_KEY = "microsoft.a365.caller.agent.name"
 GEN_AI_CALLER_AGENT_ID_KEY = "microsoft.a365.caller.agent.id"
 GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY = "microsoft.a365.caller.agent.blueprint.id"
@@ -84,7 +84,7 @@ TENANT_ID_KEY = "microsoft.tenant.id"
 
 # Baggage keys
 GEN_AI_AGENT_AUID_KEY = "microsoft.agent.user.id"
-GEN_AI_AGENT_UPN_KEY = "microsoft.agent.user.upn"
+GEN_AI_AGENT_EMAIL_KEY = "microsoft.agent.user.email"
 GEN_AI_AGENT_BLUEPRINT_ID_KEY = "microsoft.a365.agent.blueprint.id"
 
 # Execution context dimensions

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/execute_tool_scope.py

@@ -3,6 +3,7 @@
 
 from datetime import datetime
 
+from opentelemetry.context import Context
 from opentelemetry.trace import SpanKind
 
 from .agent_details import AgentDetails
@@ -33,7 +34,7 @@ class ExecuteToolScope(OpenTelemetryScope):
         agent_details: AgentDetails,
         tenant_details: TenantDetails,
         request: Request | None = None,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
         span_kind: SpanKind | None = None,
@@ -45,8 +46,9 @@ class ExecuteToolScope(OpenTelemetryScope):
             agent_details: The details of the agent making the call
             tenant_details: The details of the tenant
             request: Optional request details for additional context
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object. Useful when
                 recording a tool call after execution has already completed.
             end_time: Optional explicit end time as a datetime object. When provided,
@@ -63,7 +65,7 @@ class ExecuteToolScope(OpenTelemetryScope):
             agent_details,
             tenant_details,
             request,
-            parent_id,
+            parent_context,
             start_time,
             end_time,
             span_kind,
@@ -75,7 +77,7 @@ class ExecuteToolScope(OpenTelemetryScope):
         agent_details: AgentDetails,
         tenant_details: TenantDetails,
         request: Request | None = None,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
         span_kind: SpanKind | None = None,
@@ -87,8 +89,9 @@ class ExecuteToolScope(OpenTelemetryScope):
             agent_details: The details of the agent making the call
             tenant_details: The details of the tenant
             request: Optional request details for additional context
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object. Useful when
                 recording a tool call after execution has already completed.
             end_time: Optional explicit end time as a datetime object. When provided,
@@ -103,7 +106,7 @@ class ExecuteToolScope(OpenTelemetryScope):
             activity_name=f"{EXECUTE_TOOL_OPERATION_NAME} {details.tool_name}",
             agent_details=agent_details,
             tenant_details=tenant_details,
-            parent_id=parent_id,
+            parent_context=parent_context,
             start_time=start_time,
             end_time=end_time,
         )
@@ -128,9 +131,9 @@ class ExecuteToolScope(OpenTelemetryScope):
                 self.set_tag_maybe(SERVER_PORT_KEY, endpoint.port)
 
         # Set request metadata if provided
-        if request and request.source_metadata:
-            self.set_tag_maybe(CHANNEL_NAME_KEY, request.source_metadata.name)
-            self.set_tag_maybe(CHANNEL_LINK_KEY, request.source_metadata.description)
+        if request and request.channel:
+            self.set_tag_maybe(CHANNEL_NAME_KEY, request.channel.name)
+            self.set_tag_maybe(CHANNEL_LINK_KEY, request.channel.link)
 
     def record_response(self, response: str) -> None:
         """Records response information for telemetry tracking.

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/inference_scope.py

@@ -4,6 +4,8 @@
 from datetime import datetime
 from typing import List
 
+from opentelemetry.context import Context
+
 from .agent_details import AgentDetails
 from .constants import (
     CHANNEL_LINK_KEY,
@@ -36,7 +38,7 @@ class InferenceScope(OpenTelemetryScope):
         agent_details: AgentDetails,
         tenant_details: TenantDetails,
         request: Request | None = None,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
     ) -> "InferenceScope":
@@ -47,8 +49,9 @@ class InferenceScope(OpenTelemetryScope):
             agent_details: The details of the agent making the call
             tenant_details: The details of the tenant
             request: Optional request details for additional context
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
 
@@ -56,7 +59,7 @@ class InferenceScope(OpenTelemetryScope):
             A new InferenceScope instance
         """
         return InferenceScope(
-            details, agent_details, tenant_details, request, parent_id, start_time, end_time
+            details, agent_details, tenant_details, request, parent_context, start_time, end_time
         )
 
     def __init__(
@@ -65,7 +68,7 @@ class InferenceScope(OpenTelemetryScope):
         agent_details: AgentDetails,
         tenant_details: TenantDetails,
         request: Request | None = None,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
     ):
@@ -76,8 +79,9 @@ class InferenceScope(OpenTelemetryScope):
             agent_details: The details of the agent making the call
             tenant_details: The details of the tenant
             request: Optional request details for additional context
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
         """
@@ -88,7 +92,7 @@ class InferenceScope(OpenTelemetryScope):
             activity_name=f"{details.operationName.value} {details.model}",
             agent_details=agent_details,
             tenant_details=tenant_details,
-            parent_id=parent_id,
+            parent_context=parent_context,
             start_time=start_time,
             end_time=end_time,
         )
@@ -120,9 +124,9 @@ class InferenceScope(OpenTelemetryScope):
                 self.set_tag_maybe(SERVER_PORT_KEY, str(details.endpoint.port))
 
         # Set request metadata if provided
-        if request and request.source_metadata:
-            self.set_tag_maybe(CHANNEL_NAME_KEY, request.source_metadata.name)
-            self.set_tag_maybe(CHANNEL_LINK_KEY, request.source_metadata.description)
+        if request and request.channel:
+            self.set_tag_maybe(CHANNEL_NAME_KEY, request.channel.name)
+            self.set_tag_maybe(CHANNEL_LINK_KEY, request.channel.link)
 
     def record_input_messages(self, messages: List[str]) -> None:
         """Records the input messages for telemetry tracking.

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/invoke_agent_scope.py

@@ -6,6 +6,7 @@
 import logging
 from datetime import datetime
 
+from opentelemetry.context import Context
 from opentelemetry.trace import SpanKind
 
 from .agent_details import AgentDetails
@@ -13,15 +14,12 @@ from .constants import (
     CHANNEL_LINK_KEY,
     CHANNEL_NAME_KEY,
     GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY,
+    GEN_AI_CALLER_AGENT_EMAIL_KEY,
     GEN_AI_CALLER_AGENT_ID_KEY,
     GEN_AI_CALLER_AGENT_NAME_KEY,
     GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY,
-    GEN_AI_CALLER_AGENT_UPN_KEY,
     GEN_AI_CALLER_AGENT_USER_ID_KEY,
     GEN_AI_CALLER_CLIENT_IP_KEY,
-    GEN_AI_CALLER_ID_KEY,
-    GEN_AI_CALLER_NAME_KEY,
-    GEN_AI_CALLER_UPN_KEY,
     GEN_AI_EXECUTION_TYPE_KEY,
     GEN_AI_INPUT_MESSAGES_KEY,
     GEN_AI_OUTPUT_MESSAGES_KEY,
@@ -29,6 +27,9 @@ from .constants import (
     SERVER_ADDRESS_KEY,
     SERVER_PORT_KEY,
     SESSION_ID_KEY,
+    USER_EMAIL_KEY,
+    USER_ID_KEY,
+    USER_NAME_KEY,
 )
 from .invoke_agent_details import InvokeAgentDetails
 from .models.caller_details import CallerDetails
@@ -50,6 +51,7 @@ class InvokeAgentScope(OpenTelemetryScope):
         request: Request | None = None,
         caller_agent_details: AgentDetails | None = None,
         caller_details: CallerDetails | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
         span_kind: SpanKind | None = None,
@@ -63,6 +65,9 @@ class InvokeAgentScope(OpenTelemetryScope):
             request: Optional request details for additional context
             caller_agent_details: Optional details of the caller agent
             caller_details: Optional details of the non-agentic caller
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
             span_kind: Optional span kind override. Defaults to ``SpanKind.CLIENT``.
@@ -77,6 +82,7 @@ class InvokeAgentScope(OpenTelemetryScope):
             request,
             caller_agent_details,
             caller_details,
+            parent_context,
             start_time,
             end_time,
             span_kind,
@@ -89,6 +95,7 @@ class InvokeAgentScope(OpenTelemetryScope):
         request: Request | None = None,
         caller_agent_details: AgentDetails | None = None,
         caller_details: CallerDetails | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
         span_kind: SpanKind | None = None,
@@ -101,6 +108,9 @@ class InvokeAgentScope(OpenTelemetryScope):
             request: Optional request details for additional context
             caller_agent_details: Optional details of the caller agent
             caller_details: Optional details of the non-agentic caller
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
             span_kind: Optional span kind override. Defaults to ``SpanKind.CLIENT``.
@@ -118,6 +128,7 @@ class InvokeAgentScope(OpenTelemetryScope):
             activity_name=activity_name,
             agent_details=invoke_agent_details.details,
             tenant_details=tenant_details,
+            parent_context=parent_context,
             start_time=start_time,
             end_time=end_time,
         )
@@ -138,9 +149,9 @@ class InvokeAgentScope(OpenTelemetryScope):
 
         # Set request metadata if provided
         if request:
-            if request.source_metadata:
-                self.set_tag_maybe(CHANNEL_NAME_KEY, request.source_metadata.name)
-                self.set_tag_maybe(CHANNEL_LINK_KEY, request.source_metadata.description)
+            if request.channel:
+                self.set_tag_maybe(CHANNEL_NAME_KEY, request.channel.name)
+                self.set_tag_maybe(CHANNEL_LINK_KEY, request.channel.link)
 
             self.set_tag_maybe(
                 GEN_AI_EXECUTION_TYPE_KEY,
@@ -150,9 +161,9 @@ class InvokeAgentScope(OpenTelemetryScope):
 
         # Set caller details tags
         if caller_details:
-            self.set_tag_maybe(GEN_AI_CALLER_ID_KEY, caller_details.caller_id)
-            self.set_tag_maybe(GEN_AI_CALLER_UPN_KEY, caller_details.caller_upn)
-            self.set_tag_maybe(GEN_AI_CALLER_NAME_KEY, caller_details.caller_name)
+            self.set_tag_maybe(USER_ID_KEY, caller_details.caller_id)
+            self.set_tag_maybe(USER_EMAIL_KEY, caller_details.caller_upn)
+            self.set_tag_maybe(USER_NAME_KEY, caller_details.caller_name)
             # Validate and set caller client IP
             self.set_tag_maybe(
                 GEN_AI_CALLER_CLIENT_IP_KEY,
@@ -167,7 +178,7 @@ class InvokeAgentScope(OpenTelemetryScope):
                 GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY, caller_agent_details.agent_blueprint_id
             )
             self.set_tag_maybe(GEN_AI_CALLER_AGENT_USER_ID_KEY, caller_agent_details.agent_auid)
-            self.set_tag_maybe(GEN_AI_CALLER_AGENT_UPN_KEY, caller_agent_details.agent_upn)
+            self.set_tag_maybe(GEN_AI_CALLER_AGENT_EMAIL_KEY, caller_agent_details.agent_upn)
             self.set_tag_maybe(
                 GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY, caller_agent_details.agent_platform_id
             )

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/middleware/baggage_builder.py

@@ -14,21 +14,21 @@ from ..constants import (
     GEN_AI_AGENT_AUID_KEY,
     GEN_AI_AGENT_BLUEPRINT_ID_KEY,
     GEN_AI_AGENT_DESCRIPTION_KEY,
+    GEN_AI_AGENT_EMAIL_KEY,
     GEN_AI_AGENT_ID_KEY,
     GEN_AI_AGENT_NAME_KEY,
-    GEN_AI_AGENT_UPN_KEY,
     GEN_AI_CALLER_CLIENT_IP_KEY,
-    GEN_AI_CALLER_ID_KEY,
-    GEN_AI_CALLER_NAME_KEY,
-    GEN_AI_CALLER_UPN_KEY,
     GEN_AI_CONVERSATION_ID_KEY,
     GEN_AI_CONVERSATION_ITEM_LINK_KEY,
     SERVICE_NAME_KEY,
     SESSION_DESCRIPTION_KEY,
     SESSION_ID_KEY,
     TENANT_ID_KEY,
+    USER_EMAIL_KEY,
+    USER_ID_KEY,
+    USER_NAME_KEY,
 )
-from ..utils import deprecated, validate_and_normalize_ip
+from ..utils import validate_and_normalize_ip
 
 logger = logging.getLogger(__name__)
 
@@ -115,7 +115,7 @@ class BaggageBuilder:
         Returns:
             Self for method chaining
         """
-        self._set(GEN_AI_AGENT_UPN_KEY, value)
+        self._set(GEN_AI_AGENT_EMAIL_KEY, value)
         return self
 
     def agent_blueprint_id(self, value: str | None) -> "BaggageBuilder":
@@ -139,7 +139,7 @@ class BaggageBuilder:
         Returns:
             Self for method chaining
         """
-        self._set(GEN_AI_CALLER_ID_KEY, value)
+        self._set(USER_ID_KEY, value)
         return self
 
     def agent_name(self, value: str | None) -> "BaggageBuilder":
@@ -154,12 +154,12 @@ class BaggageBuilder:
 
     def caller_name(self, value: str | None) -> "BaggageBuilder":
         """Set the caller name baggage value."""
-        self._set(GEN_AI_CALLER_NAME_KEY, value)
+        self._set(USER_NAME_KEY, value)
         return self
 
     def caller_upn(self, value: str | None) -> "BaggageBuilder":
         """Set the caller UPN baggage value."""
-        self._set(GEN_AI_CALLER_UPN_KEY, value)
+        self._set(USER_EMAIL_KEY, value)
         return self
 
     def caller_client_ip(self, value: str | None) -> "BaggageBuilder":
@@ -177,16 +177,6 @@ class BaggageBuilder:
         self._set(GEN_AI_CONVERSATION_ITEM_LINK_KEY, value)
         return self
 
-    @deprecated("Use channel_name() instead")
-    def source_metadata_name(self, value: str | None) -> "BaggageBuilder":
-        """Set the execution source metadata name (e.g., channel name)."""
-        return self.channel_name(value)
-
-    @deprecated("Use channel_links() instead")
-    def source_metadata_description(self, value: str | None) -> "BaggageBuilder":
-        """Set the execution source metadata description (e.g., channel description)."""
-        return self.channel_links(value)
-
     def session_id(self, value: str | None) -> "BaggageBuilder":
         """Set the session ID baggage value."""
         self._set(SESSION_ID_KEY, value)
@@ -203,7 +193,7 @@ class BaggageBuilder:
         return self
 
     def channel_links(self, value: str | None) -> "BaggageBuilder":
-        """Sets the channel link baggage value. (e.g., channel links or description)."""
+        """Sets the channel link baggage value."""
         self._set(CHANNEL_LINK_KEY, value)
         return self
 

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/opentelemetry_scope.py

@@ -10,6 +10,8 @@ from threading import Lock
 from typing import TYPE_CHECKING, Any
 
 from opentelemetry import context, trace
+from opentelemetry.context import Context
+from opentelemetry.propagate import inject
 from opentelemetry.trace import (
     Span,
     SpanKind,
@@ -26,10 +28,10 @@ from .constants import (
     GEN_AI_AGENT_AUID_KEY,
     GEN_AI_AGENT_BLUEPRINT_ID_KEY,
     GEN_AI_AGENT_DESCRIPTION_KEY,
+    GEN_AI_AGENT_EMAIL_KEY,
     GEN_AI_AGENT_ID_KEY,
     GEN_AI_AGENT_NAME_KEY,
     GEN_AI_AGENT_PLATFORM_ID_KEY,
-    GEN_AI_AGENT_UPN_KEY,
     GEN_AI_CONVERSATION_ID_KEY,
     GEN_AI_ICON_URI_KEY,
     GEN_AI_OPERATION_NAME_KEY,
@@ -43,7 +45,7 @@ from .constants import (
     TELEMETRY_SDK_VERSION_KEY,
     TENANT_ID_KEY,
 )
-from .utils import get_sdk_version, parse_parent_id_to_context
+from .utils import get_sdk_version
 
 if TYPE_CHECKING:
     from .agent_details import AgentDetails
@@ -97,7 +99,7 @@ class OpenTelemetryScope:
         activity_name: str,
         agent_details: "AgentDetails | None" = None,
         tenant_details: "TenantDetails | None" = None,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
     ):
@@ -111,8 +113,9 @@ class OpenTelemetryScope:
             activity_name: The name of the activity for display purposes
             agent_details: Optional agent details
             tenant_details: Optional tenant details
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to extract a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
                 Useful when recording an operation after it has already completed.
             end_time: Optional explicit end time as a datetime object.
@@ -146,9 +149,8 @@ class OpenTelemetryScope:
                     activity_kind = SpanKind.CONSUMER
 
             # Get context for parent relationship
-            # If parent_id is provided, parse it and use it as the parent context
+            # If parent_context is provided, use it directly
             # Otherwise, use the current context
-            parent_context = parse_parent_id_to_context(parent_id)
             span_context = parent_context if parent_context else context.get_current()
 
             # Convert custom start time to OTel-compatible format (nanoseconds since epoch)
@@ -185,7 +187,7 @@ class OpenTelemetryScope:
                         GEN_AI_AGENT_DESCRIPTION_KEY, agent_details.agent_description
                     )
                     self.set_tag_maybe(GEN_AI_AGENT_AUID_KEY, agent_details.agent_auid)
-                    self.set_tag_maybe(GEN_AI_AGENT_UPN_KEY, agent_details.agent_upn)
+                    self.set_tag_maybe(GEN_AI_AGENT_EMAIL_KEY, agent_details.agent_upn)
                     self.set_tag_maybe(
                         GEN_AI_AGENT_BLUEPRINT_ID_KEY, agent_details.agent_blueprint_id
                     )
@@ -286,6 +288,49 @@ class OpenTelemetryScope:
             else:
                 self._span.end()
 
+    def get_context(self) -> Context | None:
+        """Get the OpenTelemetry context for this scope's span.
+
+        This method returns a Context object containing this scope's span,
+        which can be used to propagate trace context to child operations
+        or downstream services.
+
+        Returns:
+            A Context containing this scope's span, or None if telemetry
+            is disabled or no span exists.
+        """
+        if self._span and self._is_telemetry_enabled():
+            return set_span_in_context(self._span)
+        return None
+
+    def inject_context_to_headers(self) -> dict[str, str]:
+        """Inject this span's trace context into W3C HTTP headers.
+
+        Returns a dictionary of headers containing ``traceparent`` and
+        optionally ``tracestate`` that can be forwarded to downstream services
+        or stored for later context propagation.
+
+        Example usage:
+
+        .. code-block:: python
+
+            scope = OpenTelemetryScope(...)
+            headers = scope.inject_context_to_headers()
+            # Add headers to outgoing HTTP request
+            requests.get("https://downstream-service/api", headers=headers)
+
+        Returns:
+            A dictionary containing W3C trace context headers. Returns an
+            empty dictionary if telemetry is disabled or no span exists.
+        """
+        headers: dict[str, str] = {}
+        if self._span and self._is_telemetry_enabled():
+            # Create a context with the current span
+            ctx = set_span_in_context(self._span)
+            # Use the global propagator to inject trace context into headers
+            inject(headers, context=ctx)
+        return headers
+
     def __enter__(self):
         """Enter the context manager and make span active."""
         if self._span and self._is_telemetry_enabled():

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/request.py

@@ -6,7 +6,7 @@
 from dataclasses import dataclass
 
 from .execution_type import ExecutionType
-from .source_metadata import SourceMetadata
+from .channel import Channel
 
 
 @dataclass
@@ -16,4 +16,4 @@ class Request:
     content: str
     execution_type: ExecutionType
     session_id: str | None = None
-    source_metadata: SourceMetadata | None = None
+    channel: Channel | None = None

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/spans_scopes/output_scope.py

@@ -3,6 +3,8 @@
 
 from datetime import datetime
 
+from opentelemetry.context import Context
+
 from ..agent_details import AgentDetails
 from ..constants import GEN_AI_OUTPUT_MESSAGES_KEY
 from ..models.response import Response
@@ -23,7 +25,7 @@ class OutputScope(OpenTelemetryScope):
         agent_details: AgentDetails,
         tenant_details: TenantDetails,
         response: Response,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
     ) -> "OutputScope":
@@ -33,22 +35,25 @@ class OutputScope(OpenTelemetryScope):
             agent_details: The details of the agent
             tenant_details: The details of the tenant
             response: The response details from the agent
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
 
         Returns:
             A new OutputScope instance
         """
-        return OutputScope(agent_details, tenant_details, response, parent_id, start_time, end_time)
+        return OutputScope(
+            agent_details, tenant_details, response, parent_context, start_time, end_time
+        )
 
     def __init__(
         self,
         agent_details: AgentDetails,
         tenant_details: TenantDetails,
         response: Response,
-        parent_id: str | None = None,
+        parent_context: Context | None = None,
         start_time: datetime | None = None,
         end_time: datetime | None = None,
     ):
@@ -58,8 +63,9 @@ class OutputScope(OpenTelemetryScope):
             agent_details: The details of the agent
             tenant_details: The details of the tenant
             response: The response details from the agent
-            parent_id: Optional parent Activity ID used to link this span to an upstream
-                operation
+            parent_context: Optional OpenTelemetry Context used to link this span to an
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
+                Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
         """
@@ -69,7 +75,7 @@ class OutputScope(OpenTelemetryScope):
             activity_name=(f"{OUTPUT_OPERATION_NAME} {agent_details.agent_id}"),
             agent_details=agent_details,
             tenant_details=tenant_details,
-            parent_id=parent_id,
+            parent_context=parent_context,
             start_time=start_time,
             end_time=end_time,
         )

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/trace_processor/util.py

@@ -14,7 +14,7 @@ COMMON_ATTRIBUTES = [
     consts.GEN_AI_AGENT_ID_KEY,  # gen_ai.agent.id
     consts.GEN_AI_AGENT_NAME_KEY,  # gen_ai.agent.name
     consts.GEN_AI_AGENT_DESCRIPTION_KEY,  # gen_ai.agent.description
-    consts.GEN_AI_AGENT_UPN_KEY,  # microsoft.agent.user.upn
+    consts.GEN_AI_AGENT_EMAIL_KEY,  # microsoft.agent.user.email
     consts.GEN_AI_AGENT_BLUEPRINT_ID_KEY,  # microsoft.a365.agent.blueprint.id
     consts.GEN_AI_AGENT_AUID_KEY,  # microsoft.agent.user.id
     consts.GEN_AI_AGENT_PLATFORM_ID_KEY,  # microsoft.a365.agent.platform.id
@@ -29,14 +29,14 @@ COMMON_ATTRIBUTES = [
 # Invoke Agent–specific attributes
 INVOKE_AGENT_ATTRIBUTES = [
     # Caller / Invoker attributes
-    consts.GEN_AI_CALLER_ID_KEY,  # microsoft.caller.id
-    consts.GEN_AI_CALLER_NAME_KEY,  # microsoft.caller.name
-    consts.GEN_AI_CALLER_UPN_KEY,  # microsoft.caller.upn
+    consts.USER_ID_KEY,  # user.id
+    consts.USER_NAME_KEY,  # user.name
+    consts.USER_EMAIL_KEY,  # user.email
     # Caller Agent (A2A) attributes
     consts.GEN_AI_CALLER_AGENT_ID_KEY,  # microsoft.a365.caller.agent.id
     consts.GEN_AI_CALLER_AGENT_NAME_KEY,  # microsoft.a365.caller.agent.name
     consts.GEN_AI_CALLER_AGENT_USER_ID_KEY,  # microsoft.a365.caller.agent.user.id
-    consts.GEN_AI_CALLER_AGENT_UPN_KEY,  # microsoft.a365.caller.agent.user.upn
+    consts.GEN_AI_CALLER_AGENT_EMAIL_KEY,  # microsoft.a365.caller.agent.user.email
     consts.GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY,  # microsoft.a365.caller.agent.blueprint.id
     consts.GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY,  # microsoft.a365.caller.agent.platform.id
     consts.GEN_AI_EXECUTION_TYPE_KEY,  # gen_ai.execution.type

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365/observability/core/utils.py

@@ -15,11 +15,12 @@ from threading import RLock
 from typing import Any, Generic, TypeVar, cast
 
 from opentelemetry import context
+from opentelemetry.propagate import extract
 from opentelemetry.semconv.attributes.exception_attributes import (
     EXCEPTION_MESSAGE,
     EXCEPTION_STACKTRACE,
 )
-from opentelemetry.trace import NonRecordingSpan, Span, SpanContext, TraceFlags, set_span_in_context
+from opentelemetry.trace import Span
 from opentelemetry.util.types import AttributeValue
 from wrapt import ObjectProxy
 
@@ -29,126 +30,58 @@ logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
 
-# W3C Trace Context constants
-W3C_TRACE_CONTEXT_VERSION = "00"
-W3C_TRACE_ID_LENGTH = 32  # 32 hex chars = 128 bits
-W3C_SPAN_ID_LENGTH = 16  # 16 hex chars = 64 bits
+def extract_context_from_headers(headers: dict[str, str]) -> context.Context:
+    """Extract an OpenTelemetry Context from W3C trace HTTP headers.
 
-
-def validate_w3c_trace_context_version(version: str) -> bool:
-    """Validate W3C Trace Context version.
+    Parses ``traceparent`` (and optionally ``tracestate``) headers and returns
+    an OpenTelemetry Context that can be passed as ``parent_context`` to any
+    scope's ``start()`` method.
 
     Args:
-        version: The version string to validate
+        headers: Dictionary of HTTP headers containing trace context.
+            Expected keys include ``traceparent`` and optionally ``tracestate``.
 
     Returns:
-        True if valid, False otherwise
-    """
-    return version == W3C_TRACE_CONTEXT_VERSION
+        An OpenTelemetry Context containing the extracted trace information.
+        If no valid trace context is found, returns an empty context.
 
+    Example::
 
-def _is_valid_hex(hex_string: str) -> bool:
-    """Check if a string contains only valid hexadecimal characters.
-
-    Args:
-        hex_string: The string to validate
+        .. code-block:: python
 
-    Returns:
-        True if all characters are valid hexadecimal (0-9, a-f, A-F), False otherwise
+            headers = {
+                "traceparent": "00-1234567890abcdef1234567890abcdef-abcdefabcdef1234-01"
+            }
+            parent_context = extract_context_from_headers(headers)
+            with InferenceScope.start(
+                details, agent, tenant, parent_context=parent_context
+            ):
+                pass
     """
-    return all(c in "0123456789abcdefABCDEF" for c in hex_string)
+    return extract(headers)
 
 
-def validate_trace_id(trace_id_hex: str) -> bool:
-    """Validate W3C Trace Context trace_id format.
+def get_traceparent(headers: dict[str, str]) -> str | None:
+    """Return the W3C ``traceparent`` value from a headers dictionary.
 
     Args:
-        trace_id_hex: The trace_id hex string to validate (should be 32 hex chars)
+        headers: Dictionary of HTTP headers, typically obtained from
+            :meth:`OpenTelemetryScope.inject_context_to_headers`.
 
     Returns:
-        True if valid (32 hex chars), False otherwise
-    """
-    return len(trace_id_hex) == W3C_TRACE_ID_LENGTH and _is_valid_hex(trace_id_hex)
+        The traceparent string (e.g.
+        ``"00-<trace-id>-<span-id>-<flags>"``), or ``None`` if the
+        key is not present.
 
+    Example::
 
-def validate_span_id(span_id_hex: str) -> bool:
-    """Validate W3C Trace Context span_id format.
-
-    Args:
-        span_id_hex: The span_id hex string to validate (should be 16 hex chars)
+        .. code-block:: python
 
-    Returns:
-        True if valid (16 hex chars), False otherwise
+            # Extract traceparent from incoming HTTP request headers
+            traceparent = get_traceparent(request.headers)
+            turn_context.turn_state[A365_PARENT_TRACEPARENT_KEY] = traceparent
     """
-    return len(span_id_hex) == W3C_SPAN_ID_LENGTH and _is_valid_hex(span_id_hex)
-
-
-def parse_parent_id_to_context(parent_id: str | None) -> context.Context | None:
-    """Parse a W3C trace context parent ID and return a context with the parent span.
-
-    The parent_id format is expected to be W3C Trace Context format:
-    "00-{trace_id}-{span_id}-{trace_flags}"
-    Example: "00-1234567890abcdef1234567890abcdef-abcdefabcdef1234-01"
-
-    Args:
-        parent_id: The W3C Trace Context format parent ID string
-
-    Returns:
-        A context containing the parent span, or None if parent_id is invalid
-    """
-    if not parent_id:
-        return None
-
-    try:
-        # W3C Trace Context format: "00-{trace_id}-{span_id}-{trace_flags}"
-        parts = parent_id.split("-")
-        if len(parts) != 4:
-            logger.warning(f"Invalid parent_id format (expected 4 parts): {parent_id}")
-            return None
-
-        version, trace_id_hex, span_id_hex, trace_flags_hex = parts
-
-        # Validate W3C Trace Context version
-        if not validate_w3c_trace_context_version(version):
-            logger.warning(f"Unsupported W3C Trace Context version: {version}")
-            return None
-
-        # Validate trace_id (must be 32 hex chars)
-        if not validate_trace_id(trace_id_hex):
-            logger.warning(
-                f"Invalid trace_id (expected {W3C_TRACE_ID_LENGTH} hex chars): '{trace_id_hex}'"
-            )
-            return None
-
-        # Validate span_id (must be 16 hex chars)
-        if not validate_span_id(span_id_hex):
-            logger.warning(
-                f"Invalid span_id (expected {W3C_SPAN_ID_LENGTH} hex chars): '{span_id_hex}'"
-            )
-            return None
-
-        # Parse the hex values
-        trace_id = int(trace_id_hex, 16)
-        span_id = int(span_id_hex, 16)
-        trace_flags = TraceFlags(int(trace_flags_hex, 16))
-
-        # Create a SpanContext from the parsed values
-        parent_span_context = SpanContext(
-            trace_id=trace_id,
-            span_id=span_id,
-            is_remote=True,
-            trace_flags=trace_flags,
-        )
-
-        # Create a NonRecordingSpan with the parent context
-        parent_span = NonRecordingSpan(parent_span_context)
-
-        # Create a context with the parent span
-        return set_span_in_context(parent_span)
-
-    except (ValueError, IndexError) as e:
-        logger.warning(f"Failed to parse parent_id '{parent_id}': {e}")
-        return None
+    return headers.get("traceparent")
 
 
 def safe_json_dumps(obj: Any, **kwargs: Any) -> str:

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365_observability_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-a365-observability-core
-Version: 0.2.1.dev42
+Version: 0.2.1.dev44
 Summary: Telemetry, tracing, and monitoring components for AI agents
 Author-email: Microsoft <support@microsoft.com>
 License: MIT

{microsoft_agents_a365_observability_core-0.2.1.dev42 → microsoft_agents_a365_observability_core-0.2.1.dev44}/microsoft_agents_a365_observability_core.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 setup.py
 microsoft_agents_a365/observability/core/__init__.py
 microsoft_agents_a365/observability/core/agent_details.py
+microsoft_agents_a365/observability/core/channel.py
 microsoft_agents_a365/observability/core/config.py
 microsoft_agents_a365/observability/core/constants.py
 microsoft_agents_a365/observability/core/execute_tool_scope.py
@@ -14,7 +15,6 @@ microsoft_agents_a365/observability/core/invoke_agent_details.py
 microsoft_agents_a365/observability/core/invoke_agent_scope.py
 microsoft_agents_a365/observability/core/opentelemetry_scope.py
 microsoft_agents_a365/observability/core/request.py
-microsoft_agents_a365/observability/core/source_metadata.py
 microsoft_agents_a365/observability/core/tenant_details.py
 microsoft_agents_a365/observability/core/tool_call_details.py
 microsoft_agents_a365/observability/core/tool_type.py

microsoft_agents_a365_observability_core-0.2.1.dev42/microsoft_agents_a365/observability/core/source_metadata.py

@@ -1,16 +0,0 @@
-# Copyright (c) Microsoft Corporation.
-# Licensed under the MIT License.
-
-# Source metadata class.
-
-from dataclasses import dataclass
-
-
-@dataclass
-class SourceMetadata:
-    """Source metadata for agent execution context."""
-
-    id: str | None = None
-    name: str | None = None
-    icon_uri: str | None = None
-    description: str | None = None