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..5f52cc3efec 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,129 @@ 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 + + +@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") @@ -10341,7 +10468,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 +10614,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 +10647,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"), ], )