add input output message format

Author: nikhilc-microsoft

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

@@ -19,13 +19,37 @@
     unregister_span_enricher,
 )
 from .exporters.spectra_exporter_options import SpectraExporterOptions
-from .inference_call_details import InferenceCallDetails, ServiceEndpoint
+from .inference_call_details import InferenceCallDetails
+from .models.service_endpoint import ServiceEndpoint
 from .inference_operation_type import InferenceOperationType
 from .inference_scope import InferenceScope
 from .invoke_agent_details import InvokeAgentScopeDetails
 from .invoke_agent_scope import InvokeAgentScope
 from .middleware.baggage_builder import BaggageBuilder
 from .models.caller_details import CallerDetails
+from .models.messages import (
+    BlobPart,
+    ChatMessage,
+    FilePart,
+    FinishReason,
+    GenericPart,
+    InputMessages,
+    InputMessagesParam,
+    MessagePart,
+    MessageRole,
+    Modality,
+    OutputMessage,
+    OutputMessages,
+    OutputMessagesParam,
+    ReasoningPart,
+    ServerToolCallPart,
+    ServerToolCallResponsePart,
+    TextPart,
+    ToolCallRequestPart,
+    ToolCallResponsePart,
+    UriPart,
+)
+from .models.response import Response
 from .models.user_details import UserDetails
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
@@ -70,12 +94,34 @@
     "ToolCallDetails",
     "Channel",
     "Request",
+    "Response",
     "SpanDetails",
     "InferenceCallDetails",
     "ServiceEndpoint",
     # Enums
     "InferenceOperationType",
     "ToolType",
+    # OTEL gen-ai message format types
+    "MessageRole",
+    "FinishReason",
+    "Modality",
+    "TextPart",
+    "ToolCallRequestPart",
+    "ToolCallResponsePart",
+    "ReasoningPart",
+    "BlobPart",
+    "FilePart",
+    "UriPart",
+    "ServerToolCallPart",
+    "ServerToolCallResponsePart",
+    "GenericPart",
+    "MessagePart",
+    "ChatMessage",
+    "OutputMessage",
+    "InputMessages",
+    "OutputMessages",
+    "InputMessagesParam",
+    "OutputMessagesParam",
     # Utility functions
     "extract_context_from_headers",
     "get_traceparent",

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/execution_type.py

@@ -4,17 +4,7 @@
 from dataclasses import dataclass
 
 from .inference_operation_type import InferenceOperationType
-
-
-@dataclass
-class ServiceEndpoint:
-    """Represents a service endpoint with hostname and optional port."""
-
-    hostname: str
-    """The hostname of the service endpoint."""
-
-    port: int | None = None
-    """The port of the service endpoint."""
+from .models.service_endpoint import ServiceEndpoint
 
 
 @dataclass

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/inference_call_details.py

@@ -27,6 +27,12 @@
     GEN_AI_CALLER_CLIENT_IP_KEY,
 )
 from .inference_call_details import InferenceCallDetails
+from .message_utils import (
+    normalize_input_messages,
+    normalize_output_messages,
+    serialize_messages,
+)
+from .models.messages import InputMessagesParam, OutputMessagesParam
 from .models.user_details import UserDetails
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
@@ -97,7 +103,9 @@ def __init__(
         )
 
         if request.content:
-            self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, request.content)
+            # Wrap bare string into list for backward compatibility
+            content = [request.content] if isinstance(request.content, str) else request.content
+            self.record_input_messages(content)
         self.set_tag_maybe(GEN_AI_CONVERSATION_ID_KEY, request.conversation_id)
 
         self.set_tag_maybe(GEN_AI_OPERATION_NAME_KEY, details.operationName.value)
@@ -138,21 +146,29 @@ def __init__(
                 validate_and_normalize_ip(user_details.user_client_ip),
             )
 
-    def record_input_messages(self, messages: List[str]) -> None:
+    def record_input_messages(self, messages: InputMessagesParam) -> None:
         """Records the input messages for telemetry tracking.
 
+        Accepts plain strings (auto-wrapped as OTEL ChatMessage with role ``user``)
+        or a versioned ``InputMessages`` wrapper.
+
         Args:
-            messages: List of input messages
+            messages: List of input message strings or an InputMessages wrapper
         """
-        self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, safe_json_dumps(messages))
+        wrapper = normalize_input_messages(messages)
+        self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, serialize_messages(wrapper))
 
-    def record_output_messages(self, messages: List[str]) -> None:
+    def record_output_messages(self, messages: OutputMessagesParam) -> None:
         """Records the output messages for telemetry tracking.
 
+        Accepts plain strings (auto-wrapped as OTEL OutputMessage with role ``assistant``)
+        or a versioned ``OutputMessages`` wrapper.
+
         Args:
-            messages: List of output messages
+            messages: List of output message strings or an OutputMessages wrapper
         """
-        self.set_tag_maybe(GEN_AI_OUTPUT_MESSAGES_KEY, safe_json_dumps(messages))
+        wrapper = normalize_output_messages(messages)
+        self.set_tag_maybe(GEN_AI_OUTPUT_MESSAGES_KEY, serialize_messages(wrapper))
 
     def record_input_tokens(self, input_tokens: int) -> None:
         """Records the number of input tokens for telemetry tracking.

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/inference_scope.py

@@ -4,11 +4,12 @@
 # Data class for invoke agent scope details.
 
 from dataclasses import dataclass
-from urllib.parse import ParseResult
+
+from .models.service_endpoint import ServiceEndpoint
 
 
 @dataclass
 class InvokeAgentScopeDetails:
     """Scope-level configuration for agent invocation tracing."""
 
-    endpoint: ParseResult | None = None
+    endpoint: ServiceEndpoint | None = None

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/invoke_agent_details.py

@@ -31,11 +31,17 @@
     USER_NAME_KEY,
 )
 from .invoke_agent_details import InvokeAgentScopeDetails
+from .message_utils import (
+    normalize_input_messages,
+    normalize_output_messages,
+    serialize_messages,
+)
 from .models.caller_details import CallerDetails
+from .models.messages import InputMessagesParam, OutputMessagesParam
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
 from .span_details import SpanDetails
-from .utils import safe_json_dumps, validate_and_normalize_ip
+from .utils import validate_and_normalize_ip
 
 logger = logging.getLogger(__name__)
 
@@ -130,7 +136,9 @@ def __init__(
             self.set_tag_maybe(CHANNEL_NAME_KEY, request.channel.name)
             self.set_tag_maybe(CHANNEL_LINK_KEY, request.channel.link)
         if request.content:
-            self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, safe_json_dumps([request.content]))
+            # Wrap bare string into list for backward compatibility
+            content = [request.content] if isinstance(request.content, str) else request.content
+            self.record_input_messages(content)
 
         # Set caller details tags
         if caller_details:
@@ -176,18 +184,26 @@ def record_response(self, response: str) -> None:
         """
         self.record_output_messages([response])
 
-    def record_input_messages(self, messages: list[str]) -> None:
+    def record_input_messages(self, messages: InputMessagesParam) -> None:
         """Record the input messages for telemetry tracking.
 
+        Accepts plain strings (auto-wrapped as OTEL ChatMessage with role ``user``)
+        or a versioned ``InputMessages`` wrapper.
+
         Args:
-            messages: List of input messages to record
+            messages: List of input message strings or an InputMessages wrapper
         """
-        self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, safe_json_dumps(messages))
+        wrapper = normalize_input_messages(messages)
+        self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, serialize_messages(wrapper))
 
-    def record_output_messages(self, messages: list[str]) -> None:
+    def record_output_messages(self, messages: OutputMessagesParam) -> None:
         """Record the output messages for telemetry tracking.
 
+        Accepts plain strings (auto-wrapped as OTEL OutputMessage with role ``assistant``)
+        or a versioned ``OutputMessages`` wrapper.
+
         Args:
-            messages: List of output messages to record
+            messages: List of output message strings or an OutputMessages wrapper
         """
-        self.set_tag_maybe(GEN_AI_OUTPUT_MESSAGES_KEY, safe_json_dumps(messages))
+        wrapper = normalize_output_messages(messages)
+        self.set_tag_maybe(GEN_AI_OUTPUT_MESSAGES_KEY, serialize_messages(wrapper))

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/invoke_agent_scope.py

@@ -0,0 +1,137 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Conversion and serialization helpers for OTEL gen-ai message format.
+
+Provides normalization from plain ``list[str]`` (backward compat) to the
+versioned wrapper format, and a non-throwing ``serialize_messages`` function.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict
+from typing import Union
+
+from .models.messages import (
+    A365_MESSAGE_SCHEMA_VERSION,
+    ChatMessage,
+    InputMessages,
+    InputMessagesParam,
+    MessageRole,
+    OutputMessage,
+    OutputMessages,
+    OutputMessagesParam,
+    TextPart,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def is_string_list(
+    param: Union[InputMessagesParam, OutputMessagesParam],
+) -> bool:
+    """Return ``True`` when *param* is a plain ``list[str]``."""
+    return isinstance(param, list) and all(isinstance(item, str) for item in param)
+
+
+def is_wrapped_messages(
+    param: Union[InputMessagesParam, OutputMessagesParam],
+) -> bool:
+    """Return ``True`` when *param* is a versioned wrapper (``InputMessages`` or ``OutputMessages``)."""
+    return isinstance(param, (InputMessages, OutputMessages))
+
+
+# ---------------------------------------------------------------------------
+# Plain-string → structured conversion
+# ---------------------------------------------------------------------------
+
+
+def to_input_messages(messages: list[str]) -> list[ChatMessage]:
+    """Convert plain input strings into OTEL ``ChatMessage`` objects."""
+    return [
+        ChatMessage(role=MessageRole.USER.value, parts=[TextPart(content=content)])
+        for content in messages
+    ]
+
+
+def to_output_messages(messages: list[str]) -> list[OutputMessage]:
+    """Convert plain output strings into OTEL ``OutputMessage`` objects."""
+    return [
+        OutputMessage(role=MessageRole.ASSISTANT.value, parts=[TextPart(content=content)])
+        for content in messages
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Normalization (union → versioned wrapper)
+# ---------------------------------------------------------------------------
+
+
+def normalize_input_messages(param: InputMessagesParam) -> InputMessages:
+    """Normalize an ``InputMessagesParam`` to a versioned ``InputMessages`` wrapper.
+
+    - ``list[str]`` → converted to ``ChatMessage`` list and wrapped.
+    - ``InputMessages`` → returned as-is.
+    """
+    if is_string_list(param):
+        return InputMessages(messages=to_input_messages(param))  # type: ignore[arg-type]
+    return param  # type: ignore[return-value]
+
+
+def normalize_output_messages(param: OutputMessagesParam) -> OutputMessages:
+    """Normalize an ``OutputMessagesParam`` to a versioned ``OutputMessages`` wrapper.
+
+    - ``list[str]`` → converted to ``OutputMessage`` list and wrapped.
+    - ``OutputMessages`` → returned as-is.
+    """
+    if is_string_list(param):
+        return OutputMessages(messages=to_output_messages(param))  # type: ignore[arg-type]
+    return param  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# Serialization
+# ---------------------------------------------------------------------------
+
+
+def _message_dict_factory(items: list[tuple[str, object]]) -> dict[str, object]:
+    """Custom dict factory for ``dataclasses.asdict`` that drops ``None`` values."""
+    return {k: v for k, v in items if v is not None}
+
+
+def serialize_messages(wrapper: Union[InputMessages, OutputMessages]) -> str:
+    """Serialize a versioned message wrapper to JSON.
+
+    The output is the full wrapper object:
+    ``{"version":"0.1.0","messages":[...]}``.
+
+    The try/except ensures telemetry recording is non-throwing even when
+    message parts contain non-JSON-serializable values.
+    """
+    try:
+        return json.dumps(
+            asdict(wrapper, dict_factory=_message_dict_factory),
+            default=str,
+            ensure_ascii=False,
+        )
+    except Exception:
+        logger.warning("Failed to serialize messages; using fallback.", exc_info=True)
+        count = len(wrapper.messages)
+        noun = "message" if count == 1 else "messages"
+        fallback = {
+            "version": A365_MESSAGE_SCHEMA_VERSION,
+            "messages": [
+                {
+                    "role": MessageRole.SYSTEM.value,
+                    "parts": [
+                        {
+                            "type": "text",
+                            "content": f"[serialization failed: {count} {noun}]",
+                        }
+                    ],
+                }
+            ],
+        }
+        return json.dumps(fallback, ensure_ascii=False)