fix: #3055 surface model refusals during run resolution (#3057)

Author: seratch

docs/running_agents.md

@@ -410,7 +410,7 @@ Set the hook per run via `run_config` to redact sensitive data, trim long histor
 
 ### Error handlers
 
-All `Runner` entry points accept `error_handlers`, a dict keyed by error kind. Today, the supported key is `"max_turns"`. Use it when you want to return a controlled final output instead of raising `MaxTurnsExceeded`.
+All `Runner` entry points accept `error_handlers`, a dict keyed by error kind. The supported keys are `"max_turns"` and `"model_refusal"`. Use them when you want to return a controlled final output instead of raising `MaxTurnsExceeded` or `ModelRefusalError`.
 
 ```python
 from agents import (
@@ -441,6 +441,38 @@ print(result.final_output)
 
 Set `include_in_history=False` when you do not want the fallback output appended to conversation history.
 
+Use `"model_refusal"` when a model refusal should produce an application-specific fallback instead of ending the run with `ModelRefusalError`.
+
+```python
+from pydantic import BaseModel
+
+from agents import Agent, ModelRefusalError, RunErrorHandlerInput, Runner
+
+
+class Recipe(BaseModel):
+    ingredients: list[str]
+    refusal_reason: str | None = None
+
+
+def on_model_refusal(data: RunErrorHandlerInput[None]) -> Recipe:
+    assert isinstance(data.error, ModelRefusalError)
+    return Recipe(ingredients=[], refusal_reason=data.error.refusal)
+
+
+agent = Agent(
+    name="Recipe assistant",
+    instructions="Return a structured recipe.",
+    output_type=Recipe,
+)
+
+result = Runner.run_sync(
+    agent,
+    "Make me something unsafe.",
+    error_handlers={"model_refusal": on_model_refusal},
+)
+print(result.final_output)
+```
+
 ## Durable execution integrations and human-in-the-loop
 
 For tool approval pause/resume patterns, start with the dedicated [Human-in-the-loop guide](human_in_the_loop.md).

src/agents/__init__.py

@@ -22,6 +22,7 @@
     InputGuardrailTripwireTriggered,
     MaxTurnsExceeded,
     ModelBehaviorError,
+    ModelRefusalError,
     OutputGuardrailTripwireTriggered,
     RunErrorDetails,
     ToolInputGuardrailTripwireTriggered,
@@ -362,6 +363,7 @@ def enable_verbose_stdout_logging():
     "Prompt",
     "MaxTurnsExceeded",
     "ModelBehaviorError",
+    "ModelRefusalError",
     "ToolTimeoutError",
     "UserError",
     "InputGuardrail",

src/agents/exceptions.py

@@ -65,6 +65,17 @@ def __init__(self, message: str):
         super().__init__(message)
 
 
+class ModelRefusalError(AgentsException):
+    """Exception raised when the model refuses to produce the requested output."""
+
+    refusal: str
+    """The refusal text returned by the model."""
+
+    def __init__(self, refusal: str):
+        self.refusal = refusal
+        super().__init__(f"Model refused to produce output: {refusal}")
+
+
 class UserError(AgentsException):
     """Exception raised when the user makes an error using the SDK."""
 

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 refusal content from a message, if any."""
+        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.py

@@ -1196,6 +1196,7 @@ def _finalize_result(result: RunResult) -> RunResult:
                                     ),
                                     reasoning_item_id_policy=resolved_reasoning_item_id_policy,
                                     prompt_cache_key_resolver=prompt_cache_key_resolver,
+                                    error_handlers=error_handlers,
                                 )
                             )
 
@@ -1251,6 +1252,7 @@ def _finalize_result(result: RunResult) -> RunResult:
                                 ),
                                 reasoning_item_id_policy=resolved_reasoning_item_id_policy,
                                 prompt_cache_key_resolver=prompt_cache_key_resolver,
+                                error_handlers=error_handlers,
                             )
                     finally:
                         attach_usage_to_span(

src/agents/run_error_handlers.py

@@ -7,7 +7,7 @@
 from typing_extensions import TypedDict
 
 from .agent import Agent
-from .exceptions import MaxTurnsExceeded
+from .exceptions import MaxTurnsExceeded, ModelRefusalError
 from .items import ModelResponse, RunItem, TResponseInputItem
 from .run_context import RunContextWrapper, TContext
 from .util._types import MaybeAwaitable
@@ -27,7 +27,7 @@ class RunErrorData:
 
 @dataclass
 class RunErrorHandlerInput(Generic[TContext]):
-    error: MaxTurnsExceeded
+    error: MaxTurnsExceeded | ModelRefusalError
     context: RunContextWrapper[TContext]
     run_data: RunErrorData
 
@@ -51,6 +51,7 @@ class RunErrorHandlers(TypedDict, Generic[TContext], total=False):
     """Error handlers keyed by error kind."""
 
     max_turns: RunErrorHandler[TContext]
+    model_refusal: RunErrorHandler[TContext]
 
 
 __all__ = [

src/agents/run_internal/error_handlers.py

@@ -8,7 +8,7 @@
 
 from ..agent import Agent
 from ..agent_output import _WRAPPER_DICT_KEY, AgentOutputSchema
-from ..exceptions import MaxTurnsExceeded, ModelBehaviorError, UserError
+from ..exceptions import MaxTurnsExceeded, ModelBehaviorError, ModelRefusalError, UserError
 from ..items import (
     ItemHelpers,
     MessageOutputItem,
@@ -128,13 +128,16 @@ def create_message_output_item(agent: Agent[Any], output_text: str) -> MessageOu
 async def resolve_run_error_handler_result(
     *,
     error_handlers: RunErrorHandlers[TContext] | None,
-    error: MaxTurnsExceeded,
+    error: MaxTurnsExceeded | ModelRefusalError,
     context_wrapper: RunContextWrapper[TContext],
     run_data: RunErrorData,
 ) -> RunErrorHandlerResult | None:
     if not error_handlers:
         return None
-    handler = error_handlers.get("max_turns")
+    if isinstance(error, ModelRefusalError):
+        handler = error_handlers.get("model_refusal")
+    else:
+        handler = error_handlers.get("max_turns")
     if handler is None:
         return None
     handler_input = RunErrorHandlerInput(

src/agents/run_internal/run_loop.py

@@ -1030,6 +1030,7 @@ async def _save_stream_items_without_count(
                         ),
                         reasoning_item_id_policy=resolved_reasoning_item_id_policy,
                         prompt_cache_key_resolver=prompt_cache_key_resolver,
+                        error_handlers=error_handlers,
                     )
                 finally:
                     attach_usage_to_span(
@@ -1248,6 +1249,7 @@ async def run_single_turn_streamed(
     pending_server_items: list[RunItem] | None = None,
     reasoning_item_id_policy: ReasoningItemIdPolicy | None = None,
     prompt_cache_key_resolver: PromptCacheKeyResolver | None = None,
+    error_handlers: RunErrorHandlers[TContext] | None = None,
 ) -> SingleStepResult:
     """Run a single streamed turn and emit events as results arrive."""
     public_agent = bindings.public_agent
@@ -1643,6 +1645,7 @@ async def rewind_model_request() -> None:
         hooks=hooks,
         context_wrapper=context_wrapper,
         run_config=run_config,
+        error_handlers=error_handlers,
         tool_use_tracker=tool_use_tracker,
         server_manages_conversation=server_conversation_tracker is not None,
         event_queue=streamed_result._event_queue,
@@ -1708,6 +1711,7 @@ async def run_single_turn(
     session_items_to_rewind: list[TResponseInputItem] | None = None,
     reasoning_item_id_policy: ReasoningItemIdPolicy | None = None,
     prompt_cache_key_resolver: PromptCacheKeyResolver | None = None,
+    error_handlers: RunErrorHandlers[TContext] | None = None,
 ) -> SingleStepResult:
     """Run a single non-streaming turn of the agent loop."""
     public_agent = bindings.public_agent
@@ -1775,6 +1779,7 @@ async def run_single_turn(
         hooks=hooks,
         context_wrapper=context_wrapper,
         run_config=run_config,
+        error_handlers=error_handlers,
         tool_use_tracker=tool_use_tracker,
         server_manages_conversation=server_conversation_tracker is not None,
     )

src/agents/run_internal/turn_resolution.py

@@ -42,7 +42,7 @@
 from ..agent import Agent, ToolsToFinalOutputResult
 from ..agent_output import AgentOutputSchemaBase
 from ..agent_tool_state import get_agent_tool_state_scope, peek_agent_tool_run_result
-from ..exceptions import ModelBehaviorError, UserError
+from ..exceptions import ModelBehaviorError, ModelRefusalError, UserError
 from ..handoffs import Handoff, HandoffInputData, HandoffInputFilter, nest_handoff_history
 from ..items import (
     CompactionItem,
@@ -68,6 +68,7 @@
 from ..logger import logger
 from ..run_config import RunConfig
 from ..run_context import AgentHookContext, RunContextWrapper, TContext
+from ..run_error_handlers import RunErrorHandlers
 from ..run_state import RunState
 from ..stream_events import StreamEvent
 from ..tool import (
@@ -89,6 +90,13 @@
 from ..util import _coro, _error_tracing
 from ..util._approvals import evaluate_needs_approval_setting
 from .agent_bindings import AgentBindings
+from .error_handlers import (
+    build_run_error_data,
+    create_message_output_item,
+    format_final_output_text,
+    resolve_run_error_handler_result,
+    validate_handler_final_output,
+)
 from .items import (
     REJECTION_MESSAGE,
     apply_patch_rejection_item,
@@ -555,6 +563,7 @@ async def execute_tools_and_side_effects(
     hooks: RunHooks[TContext],
     context_wrapper: RunContextWrapper[TContext],
     run_config: RunConfig,
+    error_handlers: RunErrorHandlers[TContext] | None = None,
     server_manages_conversation: bool = False,
 ) -> SingleStepResult:
     """Run one turn of the loop, coordinating tools, approvals, guardrails, and handoffs."""
@@ -668,6 +677,7 @@ async def execute_tools_and_side_effects(
         return tool_final_output
 
     message_items = [item for item in new_step_items if isinstance(item, MessageOutputItem)]
+    refusal = ItemHelpers.extract_refusal(message_items[-1].raw_item) if message_items else None
     potential_final_output_text = (
         ItemHelpers.extract_text(message_items[-1].raw_item) if message_items else None
     )
@@ -677,6 +687,41 @@ async def execute_tools_and_side_effects(
             processed_response.tools_used
         )
         if not has_tool_activity_without_message:
+            if refusal:
+                refusal_error = ModelRefusalError(refusal)
+                run_error_data = build_run_error_data(
+                    input=original_input,
+                    new_items=pre_step_items + new_step_items,
+                    raw_responses=[new_response],
+                    last_agent=public_agent,
+                )
+                handler_result = await resolve_run_error_handler_result(
+                    error_handlers=error_handlers,
+                    error=refusal_error,
+                    context_wrapper=context_wrapper,
+                    run_data=run_error_data,
+                )
+                if handler_result is None:
+                    raise refusal_error
+
+                final_output = validate_handler_final_output(
+                    public_agent, handler_result.final_output
+                )
+                if handler_result.include_in_history:
+                    output_text = format_final_output_text(public_agent, final_output)
+                    new_step_items.append(create_message_output_item(public_agent, output_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=final_output,
+                    hooks=hooks,
+                    context_wrapper=context_wrapper,
+                    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_text:
                 final_output = output_schema.validate_json(potential_final_output_text)
                 return await execute_final_output_call(
@@ -1871,6 +1916,7 @@ async def get_single_step_result_from_response(
     context_wrapper: RunContextWrapper[TContext],
     run_config: RunConfig,
     tool_use_tracker,
+    error_handlers: RunErrorHandlers[TContext] | None = None,
     server_manages_conversation: bool = False,
     event_queue: asyncio.Queue[StreamEvent | QueueCompleteSentinel] | None = None,
     before_side_effects: Callable[[], Awaitable[None]] | None = None,
@@ -1907,5 +1953,6 @@ async def get_single_step_result_from_response(
         hooks=hooks,
         context_wrapper=context_wrapper,
         run_config=run_config,
+        error_handlers=error_handlers,
         server_manages_conversation=server_manages_conversation,
     )