fix(tracing): mark the agent span when a non-streaming run fails

The streamed run loop attaches an "Error in agent run" SpanError to the
active agent span, but the non-streaming failure handler only recorded
run_exception, so Runner.run() and Runner.run_sync() left the agent span
unmarked. Failures raised outside a generation or function span, such as a
lifecycle hook error, produced a trace with no error at all.

Attach the same SpanError from the non-streaming handler. The span is left
alone when it already carries a more specific error, such as "Max turns
exceeded", and cancellation is excluded because it is not an agent failure.
Move the shared exclusion predicate into error_handlers so both paths use
one source of truth.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: hsusul

src/agents/run.py

@@ -73,6 +73,7 @@
     create_message_output_item,
     format_final_output_text,
     resolve_run_error_handler_result,
+    should_attach_generic_agent_error,
     validate_handler_final_output,
 )
 from .run_internal.items import (
@@ -1587,6 +1588,29 @@ def _finalize_result(result: RunResult) -> RunResult:
                         turn_result.new_step_items.clear()
             except BaseException as exc:
                 run_exception = exc
+                if (
+                    current_span is not None
+                    and current_span.error is None
+                    and isinstance(exc, Exception)
+                    and should_attach_generic_agent_error(exc)
+                ):
+                    # Mirror the streamed run loop so both paths report the failing agent. A span
+                    # that already carries a more specific error keeps it, and cancellation is
+                    # excluded because it is not an agent failure.
+                    _error_tracing.attach_error_to_span(
+                        current_span,
+                        SpanError(
+                            message="Error in agent run",
+                            data={
+                                "error": _error_tracing.get_trace_error(
+                                    trace_include_sensitive_data=(
+                                        run_config.trace_include_sensitive_data
+                                    ),
+                                    error_message=str(exc),
+                                )
+                            },
+                        ),
+                    )
                 if isinstance(exc, AgentsException):
                     exc.run_data = RunErrorDetails(
                         input=original_input,

src/agents/run_internal/error_handlers.py

@@ -8,7 +8,14 @@
 
 from ..agent import Agent
 from ..agent_output import _WRAPPER_DICT_KEY, AgentOutputSchema
-from ..exceptions import MaxTurnsExceeded, ModelBehaviorError, ModelRefusalError, UserError
+from ..exceptions import (
+    InputGuardrailTripwireTriggered,
+    MaxTurnsExceeded,
+    ModelBehaviorError,
+    ModelRefusalError,
+    OutputGuardrailTripwireTriggered,
+    UserError,
+)
 from ..items import (
     ItemHelpers,
     MessageOutputItem,
@@ -30,6 +37,18 @@
 RunErrorHandlerKind = Literal["max_turns", "model_refusal", "invalid_final_output"]
 
 
+def should_attach_generic_agent_error(exc: Exception) -> bool:
+    """Return whether a failed run still needs the generic agent-span error.
+
+    Failures that already write their own agent-span error, or that a dedicated child span
+    reports, are excluded so the span keeps the more specific diagnosis.
+    """
+    return not isinstance(
+        exc,
+        ModelBehaviorError | InputGuardrailTripwireTriggered | OutputGuardrailTripwireTriggered,
+    )
+
+
 def build_run_error_data(
     *,
     input: str | list[TResponseInputItem],

src/agents/run_internal/run_loop.py

@@ -110,6 +110,7 @@
     create_message_output_item,
     format_final_output_text,
     resolve_run_error_handler_result,
+    should_attach_generic_agent_error,
     validate_handler_final_output,
 )
 from .guardrails import (
@@ -284,13 +285,6 @@ def _agent_diagnostic_extra(agent: Agent[Any]) -> dict[str, object]:
     return {"agent_name": agent.name}
 
 
-def _should_attach_generic_agent_error(exc: Exception) -> bool:
-    return not isinstance(
-        exc,
-        ModelBehaviorError | InputGuardrailTripwireTriggered | OutputGuardrailTripwireTriggered,
-    )
-
-
 async def _should_persist_stream_items(
     *,
     session: Session | None,
@@ -1247,7 +1241,7 @@ async def _save_stream_items_without_count(
                         streamed_result._event_queue.put_nowait(QueueCompleteSentinel())
                         break
             except Exception as e:
-                if current_span and _should_attach_generic_agent_error(e):
+                if current_span and should_attach_generic_agent_error(e):
                     _error_tracing.attach_error_to_span(
                         current_span,
                         SpanError(
@@ -1277,7 +1271,7 @@ async def _save_stream_items_without_count(
         )
         raise
     except Exception as e:
-        if current_span and _should_attach_generic_agent_error(e):
+        if current_span and should_attach_generic_agent_error(e):
             _error_tracing.attach_error_to_span(
                 current_span,
                 SpanError(

tests/test_tracing_errors.py

@@ -13,11 +13,17 @@
     InputGuardrail,
     InputGuardrailTripwireTriggered,
     MaxTurnsExceeded,
+    ModelBehaviorError,
+    ModelRefusalError,
+    RunConfig,
     RunContextWrapper,
     Runner,
     TResponseInputItem,
+    UserError,
     _debug,
 )
+from agents.tracing.span_data import AgentSpanData
+from agents.tracing.spans import SpanImpl
 
 from .fake_model import FakeModel
 from .test_responses import (
@@ -27,7 +33,7 @@
     get_handoff_tool_call,
     get_text_message,
 )
-from .testing_processor import fetch_normalized_spans
+from .testing_processor import SPAN_PROCESSOR_TESTING, fetch_normalized_spans, fetch_span_errors
 
 
 @pytest.mark.asyncio
@@ -49,6 +55,7 @@ async def test_single_turn_model_error():
                 "children": [
                     {
                         "type": "agent",
+                        "error": {"message": "Error in agent run", "data": {"error": "test error"}},
                         "data": {
                             "name": "test_agent",
                             "handoffs": [],
@@ -102,6 +109,7 @@ async def test_multi_turn_no_handoffs():
                 "children": [
                     {
                         "type": "agent",
+                        "error": {"message": "Error in agent run", "data": {"error": "test error"}},
                         "data": {
                             "name": "test_agent",
                             "handoffs": [],
@@ -558,3 +566,167 @@ async def test_guardrail_error():
             }
         ]
     )
+
+
+SENSITIVE_ERROR_MESSAGE = "sensitive-error-detail"
+
+
+@pytest.mark.asyncio
+async def test_run_marks_agent_span_with_generic_error():
+    """A generic run failure marks the agent span, matching the streamed path."""
+    model = FakeModel(tracing_enabled=True)
+    model.set_next_output(ValueError("test error"))
+
+    with pytest.raises(ValueError, match="test error"):
+        await Runner.run(Agent(name="test_agent", model=model), input="first_test")
+
+    assert fetch_span_errors("agent") == [
+        {"message": "Error in agent run", "data": {"error": "test error"}}
+    ]
+
+
+def test_run_sync_marks_agent_span_with_generic_error():
+    model = FakeModel(tracing_enabled=True)
+    model.set_next_output(ValueError("test error"))
+
+    with pytest.raises(ValueError, match="test error"):
+        Runner.run_sync(Agent(name="test_agent", model=model), input="first_test")
+
+    assert fetch_span_errors("agent") == [
+        {"message": "Error in agent run", "data": {"error": "test error"}}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_run_agent_span_error_matches_streamed_path():
+    """The non-streamed and streamed paths record the same agent span error."""
+    non_streamed_model = FakeModel(tracing_enabled=True)
+    non_streamed_model.set_next_output(ValueError("test error"))
+    with pytest.raises(ValueError):
+        await Runner.run(Agent(name="test_agent", model=non_streamed_model), input="first_test")
+    non_streamed_errors = fetch_span_errors("agent")
+
+    SPAN_PROCESSOR_TESTING.clear()
+
+    streamed_model = FakeModel(tracing_enabled=True)
+    streamed_model.set_next_output(ValueError("test error"))
+    result = Runner.run_streamed(Agent(name="test_agent", model=streamed_model), input="first_test")
+    with pytest.raises(ValueError):
+        async for _ in result.stream_events():
+            pass
+
+    assert non_streamed_errors == fetch_span_errors("agent")
+
+
+@pytest.mark.asyncio
+async def test_run_agent_span_error_redacts_sensitive_data():
+    model = FakeModel(tracing_enabled=False)
+    model.set_next_output(ValueError(SENSITIVE_ERROR_MESSAGE))
+
+    with pytest.raises(ValueError):
+        await Runner.run(
+            Agent(name="test_agent", model=model),
+            input="first_test",
+            run_config=RunConfig(trace_include_sensitive_data=False),
+        )
+
+    assert fetch_span_errors("agent") == [
+        {
+            "message": "Error in agent run",
+            "data": {"error": "Error details are redacted."},
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_run_does_not_mark_agent_span_for_model_behavior_error():
+    """ModelBehaviorError is reported by the generation span, so the agent span stays clean."""
+    model = FakeModel(tracing_enabled=True)
+    model.set_next_output(ModelBehaviorError("bad model output"))
+
+    with pytest.raises(ModelBehaviorError):
+        await Runner.run(Agent(name="test_agent", model=model), input="first_test")
+
+    assert fetch_span_errors("agent") == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("error", "expected_detail"),
+    [
+        pytest.param(
+            ModelRefusalError("refused"),
+            "Model refused to produce output: refused",
+            id="model-refusal-error",
+        ),
+        pytest.param(UserError("user problem"), "user problem", id="user-error"),
+    ],
+)
+async def test_run_marks_agent_span_for_other_agents_exceptions(
+    error: Exception, expected_detail: str
+):
+    """Agents exceptions without a dedicated agent-span error match the streamed path."""
+    model = FakeModel(tracing_enabled=True)
+    model.set_next_output(error)
+
+    with pytest.raises(type(error)):
+        await Runner.run(Agent(name="test_agent", model=model), input="first_test")
+
+    assert fetch_span_errors("agent") == [
+        {"message": "Error in agent run", "data": {"error": expected_detail}}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_run_keeps_specific_max_turns_agent_span_error():
+    """A more specific span error already on the agent span is not overwritten."""
+    model = FakeModel(tracing_enabled=True)
+    agent = Agent(name="test_agent", model=model, tools=[get_function_tool("foo", "res")])
+    model.add_multiple_turn_outputs(
+        [
+            [get_function_tool_call("foo", json.dumps({"a": "b"}), call_id="c1")],
+            [get_function_tool_call("foo", json.dumps({"a": "b"}), call_id="c2")],
+            [get_function_tool_call("foo", json.dumps({"a": "b"}), call_id="c3")],
+        ]
+    )
+
+    with pytest.raises(MaxTurnsExceeded):
+        await Runner.run(agent, input="first_test", max_turns=2)
+
+    assert fetch_span_errors("agent") == [
+        {"message": "Max turns exceeded", "data": {"max_turns": 2}}
+    ]
+
+
+@pytest.mark.asyncio
+async def test_run_attaches_agent_span_error_exactly_once(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """The generic error is recorded once, not re-applied by nested handlers."""
+    recorded: list[Any] = []
+    original_set_error = SpanImpl.set_error
+
+    def counting_set_error(self: Any, error: Any) -> None:
+        if isinstance(self.span_data, AgentSpanData):
+            recorded.append(error)
+        original_set_error(self, error)
+
+    monkeypatch.setattr(SpanImpl, "set_error", counting_set_error)
+
+    model = FakeModel(tracing_enabled=True)
+    model.set_next_output(ValueError("test error"))
+    with pytest.raises(ValueError):
+        await Runner.run(Agent(name="test_agent", model=model), input="first_test")
+
+    assert recorded == [{"message": "Error in agent run", "data": {"error": "test error"}}]
+
+
+@pytest.mark.asyncio
+async def test_successful_run_leaves_agent_span_without_error():
+    model = FakeModel(tracing_enabled=True)
+    model.set_next_output([get_text_message("done")])
+
+    result = await Runner.run(Agent(name="test_agent", model=model), input="first_test")
+
+    assert result.final_output == "done"
+    assert fetch_span_errors("agent") == []