fix: surface model refusals as final output

Author: cyphercodes

src/agents/items.py

@@ -722,6 +722,19 @@ def extract_text(cls, message: TResponseOutputItem) -> str | None:
 
         return text or None
 
+    @classmethod
+    def extract_refusal(cls, message: TResponseOutputItem) -> str | None:
+        """Extracts all refusal content from a message, if any. Ignores text."""
+        if not isinstance(message, ResponseOutputMessage):
+            return None
+
+        refusal = ""
+        for content_item in message.content:
+            if isinstance(content_item, ResponseOutputRefusal):
+                refusal += content_item.refusal or ""
+
+        return refusal or None
+
     @classmethod
     def input_to_new_input_list(
         cls, input: str | list[TResponseInputItem]

src/agents/run_internal/turn_resolution.py

@@ -671,6 +671,9 @@ async def execute_tools_and_side_effects(
     potential_final_output_text = (
         ItemHelpers.extract_text(message_items[-1].raw_item) if message_items else None
     )
+    potential_final_output_refusal = (
+        ItemHelpers.extract_refusal(message_items[-1].raw_item) if message_items else None
+    )
 
     if not processed_response.has_tools_or_approvals_to_run():
         has_tool_activity_without_message = not message_items and bool(
@@ -691,14 +694,33 @@ async def execute_tools_and_side_effects(
                     tool_input_guardrail_results=tool_input_guardrail_results,
                     tool_output_guardrail_results=tool_output_guardrail_results,
                 )
+            if (
+                output_schema
+                and not output_schema.is_plain_text()
+                and potential_final_output_refusal
+            ):
+                return await execute_final_output_call(
+                    public_agent=public_agent,
+                    original_input=original_input,
+                    new_response=new_response,
+                    pre_step_items=pre_step_items,
+                    new_step_items=new_step_items,
+                    final_output=potential_final_output_refusal,
+                    hooks=hooks,
+                    context_wrapper=context_wrapper,
+                    tool_input_guardrail_results=tool_input_guardrail_results,
+                    tool_output_guardrail_results=tool_output_guardrail_results,
+                )
             if not output_schema or output_schema.is_plain_text():
                 return await execute_final_output_call(
                     public_agent=public_agent,
                     original_input=original_input,
                     new_response=new_response,
                     pre_step_items=pre_step_items,
                     new_step_items=new_step_items,
-                    final_output=potential_final_output_text or "",
+                    final_output=potential_final_output_text
+                    or potential_final_output_refusal
+                    or "",
                     hooks=hooks,
                     context_wrapper=context_wrapper,
                     tool_input_guardrail_results=tool_input_guardrail_results,

tests/test_items_helpers.py

@@ -128,6 +128,27 @@ def test_extract_text_concatenates_all_text_segments() -> None:
     )
 
 
+def test_extract_refusal_concatenates_all_refusal_segments() -> None:
+    first_refusal = ResponseOutputRefusal(refusal="no", type="refusal")
+    text = ResponseOutputText(annotations=[], text="ignored", type="output_text", logprobs=[])
+    second_refusal = ResponseOutputRefusal(refusal=" way", type="refusal")
+    message = make_message([first_refusal, text, second_refusal])
+
+    assert ItemHelpers.extract_refusal(message) == "no way"
+    assert (
+        ItemHelpers.extract_refusal(
+            ResponseFunctionToolCall(
+                id="tool123",
+                arguments="{}",
+                call_id="call123",
+                name="func",
+                type="function_call",
+            )
+        )
+        is None
+    )
+
+
 def test_extract_text_tolerates_none_text_content() -> None:
     """Regression: ``content_item.text`` can be ``None`` when output items
     are assembled via ``model_construct`` (e.g. partial streaming responses)

tests/test_max_turns.py

@@ -3,6 +3,8 @@
 import json
 
 import pytest
+from openai.types.responses.response_output_message import ResponseOutputMessage
+from openai.types.responses.response_output_refusal import ResponseOutputRefusal
 from pydantic import BaseModel
 from typing_extensions import TypedDict
 
@@ -21,6 +23,16 @@
 from .test_responses import get_function_tool, get_function_tool_call, get_text_message
 
 
+def get_refusal_message(refusal: str) -> ResponseOutputMessage:
+    return ResponseOutputMessage(
+        id="1",
+        type="message",
+        role="assistant",
+        content=[ResponseOutputRefusal(type="refusal", refusal=refusal)],
+        status="completed",
+    )
+
+
 @pytest.mark.asyncio
 async def test_non_streamed_max_turns():
     model = FakeModel()
@@ -141,6 +153,57 @@ async def test_structured_output_streamed_max_turns():
             pass
 
 
+@pytest.mark.asyncio
+async def test_structured_output_refusal_finishes_without_retries():
+    refusal = "I can't help with that request."
+    model = FakeModel(initial_output=[get_refusal_message(refusal)])
+    agent = Agent(
+        name="test_1",
+        model=model,
+        output_type=Foo,
+    )
+
+    result = await Runner.run(agent, input="user_message", max_turns=3)
+
+    assert result.final_output == refusal
+    assert len(result.raw_responses) == 1
+    assert ItemHelpers.extract_refusal(result.raw_responses[0].output[0]) == refusal
+
+
+@pytest.mark.asyncio
+async def test_structured_output_refusal_streamed_finishes_without_retries():
+    refusal = "I can't help with that request."
+    model = FakeModel(initial_output=[get_refusal_message(refusal)])
+    agent = Agent(
+        name="test_1",
+        model=model,
+        output_type=Foo,
+    )
+
+    result = Runner.run_streamed(agent, input="user_message", max_turns=3)
+    async for _ in result.stream_events():
+        pass
+
+    assert result.final_output == refusal
+    assert len(result.raw_responses) == 1
+    assert ItemHelpers.extract_refusal(result.raw_responses[0].output[0]) == refusal
+
+
+@pytest.mark.asyncio
+async def test_plain_text_refusal_finishes_as_final_output():
+    refusal = "I can't help with that request."
+    model = FakeModel(initial_output=[get_refusal_message(refusal)])
+    agent = Agent(
+        name="test_1",
+        model=model,
+    )
+
+    result = await Runner.run(agent, input="user_message", max_turns=3)
+
+    assert result.final_output == refusal
+    assert len(result.raw_responses) == 1
+
+
 @pytest.mark.asyncio
 async def test_structured_output_max_turns_handler_invalid_output():
     model = FakeModel()

tests/test_run_step_execution.py

@@ -409,7 +409,7 @@ async def test_plaintext_agent_hosted_shell_with_refusal_message_is_final_output
     assert isinstance(result.generated_items[1], ToolCallOutputItem)
     assert isinstance(result.generated_items[2], MessageOutputItem)
     assert isinstance(result.next_step, NextStepFinalOutput)
-    assert result.next_step.output == ""
+    assert result.next_step.output == "I cannot help with that."
 
 
 @pytest.mark.asyncio