From 6d95a3f191cac4cb1328b5ff428a8aa9dd2d729c Mon Sep 17 00:00:00 2001
From: pakrym-oai <pakrym@openai.com>
Date: Wed, 26 Mar 2025 07:44:59 -0700
Subject: [PATCH] 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"
/>
---
 src/agents/_run_impl.py               | 13 ++++++++++++-
 tests/test_tracing_errors.py          | 27 +++++++++++++++++++++++++--
 tests/test_tracing_errors_streamed.py | 13 ++++++++++++-
 3 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/src/agents/_run_impl.py b/src/agents/_run_impl.py
index 61ca4a0..94c181b 100644
--- a/src/agents/_run_impl.py
+++ b/src/agents/_run_impl.py
@@ -529,7 +529,8 @@ class RunImpl:
         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 @@ class RunImpl:
                 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 --git a/tests/test_tracing_errors.py b/tests/test_tracing_errors.py
index baa7768..6d698bc 100644
--- a/tests/test_tracing_errors.py
+++ b/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 --git a/tests/test_tracing_errors_streamed.py b/tests/test_tracing_errors_streamed.py
index 7e65ff1..416793e 100644
--- a/tests/test_tracing_errors_streamed.py
+++ b/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"},
                             },
                         ],