From 81e2793f49a9fc1e19858987af3c5bbc519badf5 Mon Sep 17 00:00:00 2001 From: Sumedh Aerram Date: Sat, 31 Oct 2026 16:23:26 -0700 Subject: [PATCH 1/2] Python: Surface failed OpenAI Responses as client exceptions Failed Responses API objects and terminal stream snapshots discarded provider errors and returned empty success. Raise through the existing client exception path and clear failed background resume tokens before parsing. --- python/packages/openai/AGENTS.md | 4 ++ python/packages/openai/README.md | 7 ++ .../agent_framework_openai/_chat_client.py | 15 +++++ .../tests/openai/test_openai_chat_client.py | 64 ++++++++++++++++++- 4 files changed, 87 insertions(+), 3 deletions(-) diff --git a/python/packages/openai/AGENTS.md b/python/packages/openai/AGENTS.md index da64504352a..3c4be7bbad3 100644 --- a/python/packages/openai/AGENTS.md +++ b/python/packages/openai/AGENTS.md @@ -74,6 +74,10 @@ Native Responses and Chat Completions refusals remain ordinary text content with the provider's native refusal field without splitting mixed text/refusal turns; non-assistant marked text is sent as ordinary input text. +Responses with `status="failed"` raise `ChatClientException` with available provider error details +in both response modes, including a terminal `response.created` event. Background polling must clear +the caller-owned continuation token before parsing can raise on a failed response. + Responses citations remain `Content.annotations`, including annotation-only updates parsed from completed text parts and output messages. Streaming deduplication is request-local and keyed by item ID, content index, and annotation index, so separate references to the same URL remain distinct. `_parse_chunk_from_openai` retains diff --git a/python/packages/openai/README.md b/python/packages/openai/README.md index 9198b8f1011..7cc772e7d82 100644 --- a/python/packages/openai/README.md +++ b/python/packages/openai/README.md @@ -24,6 +24,13 @@ Use `OpenAIChatClient` for new work unless you specifically need the Chat Comple The previous deprecated Responses alias has been removed. Use `OpenAIChatClient` directly. +## Failed responses + +`OpenAIChatClient` raises `ChatClientException` when the Responses API returns +`status="failed"`, including failed background polls and streaming terminal events. +The exception includes the provider's error code and message when available. +Failed background polls clear their continuation token before raising. + ## Citations and annotations `OpenAIChatClient` exposes Responses API URL, file, file-path, and container-file citations through diff --git a/python/packages/openai/agent_framework_openai/_chat_client.py b/python/packages/openai/agent_framework_openai/_chat_client.py index 1e0255ff6ce..60248491d33 100644 --- a/python/packages/openai/agent_framework_openai/_chat_client.py +++ b/python/packages/openai/agent_framework_openai/_chat_client.py @@ -888,6 +888,16 @@ def _handle_request_error(self, ex: Exception) -> NoReturn: inner_exception=ex, ) from ex + def _raise_for_failed_response(self, response: OpenAIResponse | ParsedResponse[BaseModel]) -> None: + """Surface terminal provider failures before returning any response output.""" + if response.status == "failed": + error_details = ( + f"{response.error.code}: {response.error.message}" + if response.error is not None + else "No error details." + ) + self._handle_request_error(RuntimeError(f"OpenAI response failed: {error_details}")) + @override async def close(self) -> None: """Close the connector-owned SDK connection, not caller-supplied credentials.""" @@ -1044,6 +1054,8 @@ async def _get_response() -> ChatResponse: response = raw_response.parse() except Exception as ex: self._handle_request_error(ex) + if response.status == "failed" and isinstance(options, dict): + options.pop("continuation_token", None) chat_response = self._parse_response_from_openai(response, options=validated_options) # See note above on ``raw_stream_response.headers``. served_model = self._extract_served_model(getattr(raw_response, "headers", None)) @@ -3512,6 +3524,7 @@ def _parse_response_from_openai( options: dict[str, Any], ) -> ChatResponse: """Parse an OpenAI Responses API response into a ChatResponse.""" + self._raise_for_failed_response(response) structured_response: BaseModel | None = response.output_parsed if isinstance(response, ParsedResponse) else None # type: ignore[reportUnknownMemberType] metadata: dict[str, Any] = response.metadata or {} @@ -4206,6 +4219,7 @@ def parse_annotations( ) metadata.update(self._get_metadata_from_response(event)) case "response.created": + self._raise_for_failed_response(event.response) response_id = event.response.id conversation_id = self._get_conversation_id(event.response, options.get("store")) if event.response.status in _TERMINAL_RESPONSE_STATUSES: @@ -4217,6 +4231,7 @@ def parse_annotations( conversation_id = self._get_conversation_id(event.response, options.get("store")) continuation_token = OpenAIContinuationToken(response_id=event.response.id) case "response.completed" | "response.incomplete" | "response.failed": + self._raise_for_failed_response(event.response) operation_state = "terminal" response_id = event.response.id conversation_id = self._get_conversation_id(event.response, options.get("store")) diff --git a/python/packages/openai/tests/openai/test_openai_chat_client.py b/python/packages/openai/tests/openai/test_openai_chat_client.py index ea20a55ef35..ad241647a15 100644 --- a/python/packages/openai/tests/openai/test_openai_chat_client.py +++ b/python/packages/openai/tests/openai/test_openai_chat_client.py @@ -56,10 +56,13 @@ ) from openai import AsyncOpenAI, BadRequestError, DefaultAsyncHttpxClient from openai.types.responses import ( + Response, ResponseComputerToolCall, ResponseComputerToolCallOutputItem, ResponseContentPartDoneEvent, + ResponseCreatedEvent, ResponseErrorEvent, + ResponseFailedEvent, ResponseFunctionShellToolCall, ResponseFunctionShellToolCallOutput, ResponseFunctionToolCall, @@ -92,6 +95,7 @@ OpenAIChatClient, OpenAIChatCompletionClient, OpenAIChatOptions, + OpenAIContinuationToken, RawOpenAIChatClient, RawOpenAIChatCompletionClient, ) @@ -10321,6 +10325,62 @@ async def test_resumed_stream_error_clears_continuation_token() -> None: assert "continuation_token" not in options +@pytest.mark.parametrize("request_path", ["create", "structured", "resume"]) +@pytest.mark.parametrize("event_type", [None, "response.failed", "response.created"]) +@pytest.mark.parametrize("with_error", [True, False]) +async def test_failed_response_raises_and_clears_resume_token( + request_path: str, event_type: str | None, with_error: bool +) -> None: + client = OpenAIChatClient(model="test-model", api_key="test-key") + response = Response.model_validate({ + "id": "resp_failed", + "object": "response", + "created_at": 1.0, + "model": "test-model", + "status": "failed", + "error": {"code": "server_error", "message": "Generation failed."} if with_error else None, + "output": [], + "parallel_tool_calls": True, + "tool_choice": "auto", + "tools": [], + }) + options: OpenAIChatOptions[Any] = {} + if request_path == "structured": + options["response_format"] = OutputStruct + if request_path == "resume": + options["continuation_token"] = OpenAIContinuationToken(response_id=response.id) + + if event_type is None: + raw_response = MagicMock() + raw_response.parse.return_value = response + method = {"create": "create", "structured": "parse", "resume": "retrieve"}[request_path] + request_patch = patch.object(client.client.responses.with_raw_response, method, return_value=raw_response) + else: + event_class = ResponseFailedEvent if event_type == "response.failed" else ResponseCreatedEvent + event = event_class.model_validate({"type": event_type, "sequence_number": 1, "response": response}) + events = _FakeAsyncEventStream([event]) + if request_path == "structured": + request_patch = patch.object(client.client.responses, "stream", return_value=events) + else: + method = "retrieve" if request_path == "resume" else "create" + request_patch = patch.object(client.client.responses.with_raw_response, method, return_value=events) + + with request_patch, pytest.raises(ChatClientException, match="OpenAI response failed") as exc_info: + result = client._inner_get_response( + messages=[Message(role="user", contents=["test"])], options=options, stream=event_type is not None + ) + if isinstance(result, ResponseStream): + await result.get_final_response() + else: + await result + + if with_error: + assert "server_error: Generation failed." in str(exc_info.value) + assert isinstance(exc_info.value.__cause__, RuntimeError) + if request_path == "resume": + assert "continuation_token" not in options + + def test_streaming_response_created_with_in_progress_status_sets_continuation_token() -> None: """Test that response.created with in_progress status sets continuation_token.""" client = OpenAIChatClient(model="test-model", api_key="test-key") @@ -10341,7 +10401,7 @@ def test_streaming_response_created_with_in_progress_status_sets_continuation_to assert _response_id_from_token(update.continuation_token) == "resp_created_123" -@pytest.mark.parametrize("status", ["completed", "failed", "incomplete", "cancelled"]) +@pytest.mark.parametrize("status", ["completed", "incomplete", "cancelled"]) def test_streaming_response_created_with_terminal_status_clears_continuation_token(status: str) -> None: """A terminal status embedded in response.created should terminate the operation.""" client = OpenAIChatClient(model="test-model", api_key="test-key") @@ -10487,7 +10547,6 @@ def test_parse_response_from_openai_sets_finish_reason() -> None: ("response.completed", "completed", None, "function_call", "tool_calls"), ("response.incomplete", "incomplete", "max_output_tokens", None, "length"), ("response.incomplete", "incomplete", "content_filter", None, "content_filter"), - ("response.failed", "failed", None, None, None), ], ) def test_streaming_terminal_response_sets_finish_reason( @@ -10521,7 +10580,6 @@ def test_streaming_terminal_response_sets_finish_reason( @pytest.mark.parametrize( ("event_type", "status", "incomplete_reason"), [ - ("response.failed", "failed", None), ("response.incomplete", "incomplete", "other"), ], ) From c34e408c3e5764f93376aadd19b9ef5fff92c25e Mon Sep 17 00:00:00 2001 From: Sumedh Aerram Date: Mon, 2 Nov 2026 11:05:03 -0800 Subject: [PATCH 2/2] Python: Cover tool-call safety for failed OpenAI Responses A failed Response or response.failed event that carries a function call must raise without invoking the local tool or sending a follow-up request, for both non-streaming and streaming calls. --- .../tests/openai/test_openai_chat_client.py | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/python/packages/openai/tests/openai/test_openai_chat_client.py b/python/packages/openai/tests/openai/test_openai_chat_client.py index ad241647a15..5f52cc3efec 100644 --- a/python/packages/openai/tests/openai/test_openai_chat_client.py +++ b/python/packages/openai/tests/openai/test_openai_chat_client.py @@ -10381,6 +10381,73 @@ async def test_failed_response_raises_and_clears_resume_token( assert "continuation_token" not in options +@pytest.mark.parametrize("stream", [False, True]) +async def test_failed_response_with_function_call_does_not_invoke_tool(stream: bool) -> None: + from openai.types.responses import ResponseOutputItemAddedEvent + + invocations: list[str] = [] + + @tool(approval_mode="never_require") + def lookup(query: str) -> str: + """Look up a value.""" + invocations.append(query) + return "value" + + client = OpenAIChatClient(model="test-model", api_key="test-key") + function_call = { + "type": "function_call", + "id": "fc_1", + "call_id": "call_1", + "name": "lookup", + "arguments": '{"query": "x"}', + "status": "completed", + } + response = Response.model_validate({ + "id": "resp_failed", + "object": "response", + "created_at": 1.0, + "model": "test-model", + "status": "failed", + "error": {"code": "server_error", "message": "Generation failed."}, + "output": [function_call], + "parallel_tool_calls": True, + "tool_choice": "auto", + "tools": [], + }) + if stream: + create_result: object = _FakeAsyncEventStream([ + ResponseOutputItemAddedEvent.model_validate({ + "type": "response.output_item.added", + "sequence_number": 1, + "output_index": 0, + "item": function_call, + }), + ResponseOutputItemDoneEvent.model_validate({ + "type": "response.output_item.done", + "sequence_number": 2, + "output_index": 0, + "item": function_call, + }), + ResponseFailedEvent.model_validate({"type": "response.failed", "sequence_number": 3, "response": response}), + ]) + else: + create_result = MagicMock() + create_result.parse.return_value = response + + with ( + patch.object(client.client.responses.with_raw_response, "create", return_value=create_result) as create, + pytest.raises(ChatClientException, match="server_error: Generation failed."), + ): + messages = [Message(role="user", contents=["test"])] + if stream: + await client.get_response(messages=messages, options={"tools": [lookup]}, stream=True).get_final_response() + else: + await client.get_response(messages=messages, options={"tools": [lookup]}) + + assert invocations == [] + assert create.call_count == 1 + + def test_streaming_response_created_with_in_progress_status_sets_continuation_token() -> None: """Test that response.created with in_progress status sets continuation_token.""" client = OpenAIChatClient(model="test-model", api_key="test-key")