fix: reparent agent spans according to handoff attributes

Author: liramon2

src/strands_evals/mappers/openai_agents_otel_session_mapper.py

@@ -4,8 +4,8 @@
 (produced by opentelemetry-instrumentation-openai-agents from Traceloop's OpenLLMetry project)
 
 Supports two trace formats:
-1. ADOT/CloudWatch: Messages in gen_ai.* attributes
-2. Live instrumentation: Messages in gen_ai.* attributes
+1. Live instrumentation: Messages in gen_ai.* attributes
+2. ADOT/CloudWatch: the same as above plus `aws.*` attributes
 """
 
 import logging
@@ -30,9 +30,6 @@ class OpenAIAgentsOtelSessionMapper(GenericGenAISessionMapper):
     """Maps OpenAI Agents SDK OTel spans to Session format.
 
     Inherits from GenericGenAISessionMapper to reuse GenAI semantic conventions parsing.
-    Overrides workflow-span skipping and tool back-filling which assume a single-agent-per-
-    workflow trace shape and would break multi-agent traces or frameworks that use empty
-    invoke_agent spans as session anchors if applied in the base class.
     """
 
     def map_to_session(self, data: Any, session_id: str) -> Session:
@@ -45,27 +42,23 @@ def map_to_session(self, data: Any, session_id: str) -> Session:
         Returns:
             Session object ready for evaluation.
         """
-        # Normalize input to flat spans
         spans = self._normalize_to_flat_spans(data)
 
-        # Filter to only spans from this scope
         openai_agents_spans = [s for s in spans if get_scope_name(s) in (SCOPE_OPENAI_AGENTS, "")]
 
         return super().map_to_session(openai_agents_spans, session_id)
 
     def _convert_trace(self, trace_id: str, spans: list[dict], session_id: str) -> Trace:
-        """Convert a list of dict spans to a Trace, with per-agent tool back-filling.
-
-        After base conversion (which sets agent_span_id via Trace.model_post_init),
-        assigns each ToolExecutionSpan's tool only to its owning AgentInvocationSpan.
-        """
+        """Convert a list of dict spans to a Trace."""
         trace = super()._convert_trace(trace_id, spans, session_id)
 
-        # Back-fill available_tools scoped per agent using agent_span_id (set by model_post_init).
         agent_spans = {
             s.span_info.span_id: s for s in trace.spans if isinstance(s, AgentInvocationSpan) and s.span_info.span_id
         }
 
+        self._apply_handoff_reparenting(agent_spans, spans)
+
+        # Back-fill agent's available_tools, which is not otherwise provided in the trace.
         for span in trace.spans:
             if isinstance(span, ToolExecutionSpan) and span.tool_call.name:
                 owner_id = span.agent_span_id
@@ -76,15 +69,45 @@ def _convert_trace(self, trace_id: str, spans: list[dict], session_id: str) -> T
 
         return trace
 
+    def _apply_handoff_reparenting(
+        self,
+        agent_spans: dict[str, AgentInvocationSpan],
+        raw_spans: list[dict],
+    ) -> None:
+        """Re-parent agent invocation spans using OpenAI Agent's agent_handoff span."""
+        agent_spans_by_name: dict[str, AgentInvocationSpan] = {}
+        handoffs: list[tuple[str, str]] = []
+
+        # Collect converted agent spans and handoff edges
+        for raw_span in raw_spans:
+            attrs = raw_span.get("attributes", {})
+            op = attrs.get("gen_ai.operation.name", "")
+            if op == "invoke_agent":
+                name = attrs.get("gen_ai.agent.name", "")
+                span_id = raw_span.get("span_id", "")
+                if name and span_id and span_id in agent_spans:
+                    agent_spans_by_name[name] = agent_spans[span_id]
+            elif op == "agent_handoff":
+                from_name = attrs.get("gen_ai.handoff.from_agent", "")
+                to_name = attrs.get("gen_ai.handoff.to_agent", "")
+                if from_name and to_name:
+                    handoffs.append((from_name, to_name))
+
+        # Re-parent sub-agents to parent agents
+        for from_name, to_name in handoffs:
+            from_span = agent_spans_by_name.get(from_name)
+            to_span = agent_spans_by_name.get(to_name)
+            if from_span and to_span and from_span.span_info.span_id:
+                to_span.span_info.parent_span_id = from_span.span_info.span_id
+
     def _convert_agent_invocation_span(self, span: dict, span_info: SpanInfo) -> AgentInvocationSpan | None:
         """Convert an 'invoke_agent' span to AgentInvocationSpan.
 
-        Skips the root "Agent workflow" span emitted by Traceloop's instrumentation.
-        This span has invoke_agent operation but no agent_name or input messages —
-        it's a structural wrapper, not a real agent invocation.
+        Skips the root "Agent workflow" wrapper emitted by Traceloop's instrumentation.
         """
         attrs = span.get("attributes", {})
 
+        # Agent workflow span has no agent_name or input messages
         if not attrs.get("gen_ai.agent.name") and not attrs.get("gen_ai.input.messages"):
             return None
 

tests/strands_evals/mappers/test_openai_agents_otel_session_mapper.py

@@ -160,6 +160,35 @@ def test_session_has_agent_invocation_spans(self, adot_session):
         agent_spans = [s for s in all_spans if isinstance(s, AgentInvocationSpan)]
         assert len(agent_spans) > 0
 
+    def test_handoff_reparents_math_specialist_under_coordinator(self, adot_session):
+        """agent_handoff span should re-parent math_specialist under coordinator."""
+        all_spans = [s for t in adot_session.traces for s in t.spans]
+        agent_spans = [s for s in all_spans if isinstance(s, AgentInvocationSpan)]
+
+        coordinator = next(s for s in agent_spans if s.span_info.span_id == "1afcb5ca9fe89dda")
+        math_specialist = next(s for s in agent_spans if s.span_info.span_id == "c2828d53371818f0")
+
+        assert math_specialist.span_info.parent_span_id == coordinator.span_info.span_id
+        agent_span_ids = {s.span_info.span_id for s in agent_spans}
+        assert coordinator.span_info.parent_span_id not in agent_span_ids
+
+    def test_adot_coordinator_tools_empty(self, adot_session):
+        """ADOT coordinator has no structured tool calls (handoffs emitted as repr text)."""
+        all_spans = [s for t in adot_session.traces for s in t.spans]
+        coordinator = next(
+            s for s in all_spans if isinstance(s, AgentInvocationSpan) and s.span_info.span_id == "1afcb5ca9fe89dda"
+        )
+        assert coordinator.available_tools == []
+
+    def test_adot_math_specialist_tools(self, adot_session):
+        """ADOT math_specialist should have multiply_numbers back-filled."""
+        all_spans = [s for t in adot_session.traces for s in t.spans]
+        math_specialist = next(
+            s for s in all_spans if isinstance(s, AgentInvocationSpan) and s.span_info.span_id == "c2828d53371818f0"
+        )
+        tool_names = sorted(t.name for t in math_specialist.available_tools)
+        assert tool_names == ["multiply_numbers"]
+
 
 # =============================================================================
 # Per-Agent Tool Attribution Tests
@@ -194,8 +223,8 @@ def test_math_specialist_tools(self, live_session):
         assert tool_names == ["divide_numbers", "multiply_numbers"]
 
     def test_tools_not_shared_across_agents(self, live_session):
-        """No tool should appear in both agents' available_tools lists."""
+        """No tool should appear in multiple agents' available_tools lists."""
         all_spans = [s for t in live_session.traces for s in t.spans]
         agent_spans = [s for s in all_spans if isinstance(s, AgentInvocationSpan)]
-        tool_sets = [frozenset(t.name for t in s.available_tools) for s in agent_spans]
-        assert tool_sets[0] & tool_sets[1] == frozenset()
+        tool_sets = [set(t.name for t in s.available_tools) for s in agent_spans]
+        assert not set.intersection(*tool_sets)