Mark handoff span as errored when multiple handoffs are requested (#344)

Also includes the set of requested agents in the error data.
<img width="968" alt="image"
src="https://github.com/user-attachments/assets/0c5c2e81-08f7-445c-bbb0-3e169ef744a5"
/>

Author: pakrym-oai

Diff for: src/agents/_run_impl.py

@@ -529,7 +529,8 @@ async def execute_handoffs(
         run_config: RunConfig,
     ) -> SingleStepResult:
         # If there is more than one handoff, add tool responses that reject those handoffs
-        if len(run_handoffs) > 1:
+        multiple_handoffs = len(run_handoffs) > 1
+        if multiple_handoffs:
             output_message = "Multiple handoffs detected, ignoring this one."
             new_step_items.extend(
                 [
@@ -551,6 +552,16 @@ async def execute_handoffs(
                 context_wrapper, actual_handoff.tool_call.arguments
             )
             span_handoff.span_data.to_agent = new_agent.name
+            if multiple_handoffs:
+                requested_agents = [handoff.handoff.agent_name for handoff in run_handoffs]
+                span_handoff.set_error(
+                    SpanError(
+                        message="Multiple handoffs requested",
+                        data={
+                            "requested_agents": requested_agents,
+                        },
+                    )
+                )
 
             # Append a tool output item for the handoff
             new_step_items.append(

Diff for: tests/test_tracing_errors.py

@@ -244,7 +244,18 @@ async def test_multiple_handoff_doesnt_error():
                                 },
                             },
                             {"type": "generation"},
-                            {"type": "handoff", "data": {"from_agent": "test", "to_agent": "test"}},
+                            {"type": "handoff",
+                             "data": {"from_agent": "test", "to_agent": "test"},
+                             "error": {
+                                    "data": {
+                                        "requested_agents": [
+                                            "test",
+                                            "test",
+                                        ],
+                                    },
+                                    "message": "Multiple handoffs requested",
+                                },
+                             },
                         ],
                     },
                     {
@@ -372,7 +383,19 @@ async def test_handoffs_lead_to_correct_agent_spans():
                             {"type": "generation"},
                             {
                                 "type": "handoff",
-                                "data": {"from_agent": "test_agent_3", "to_agent": "test_agent_1"},
+                                "data": {
+                                    "from_agent": "test_agent_3",
+                                    "to_agent": "test_agent_1"
+                                },
+                                "error": {
+                                    "data": {
+                                        "requested_agents": [
+                                            "test_agent_1",
+                                            "test_agent_2",
+                                        ],
+                                    },
+                                    "message": "Multiple handoffs requested",
+                                },
                             },
                         ],
                     },

Diff for: tests/test_tracing_errors_streamed.py

@@ -262,7 +262,14 @@ async def test_multiple_handoff_doesnt_error():
                                 },
                             },
                             {"type": "generation"},
-                            {"type": "handoff", "data": {"from_agent": "test", "to_agent": "test"}},
+                            {
+                                "type": "handoff",
+                                "data": {"from_agent": "test", "to_agent": "test"},
+                                "error": {
+                                    "data": {"requested_agents": ["test", "test"]},
+                                    "message": "Multiple handoffs requested",
+                                },
+                            },
                         ],
                     },
                     {
@@ -396,6 +403,10 @@ async def test_handoffs_lead_to_correct_agent_spans():
                             {"type": "generation"},
                             {
                                 "type": "handoff",
+                                "error": {
+                                    "message": "Multiple handoffs requested",
+                                    "data": {"requested_agents": ["test_agent_1", "test_agent_2"]},
+                                },
                                 "data": {"from_agent": "test_agent_3", "to_agent": "test_agent_1"},
                             },
                         ],