Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions python/packages/openai/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 7 additions & 0 deletions python/packages/openai/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 15 additions & 0 deletions python/packages/openai/agent_framework_openai/_chat_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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 {}
Expand Down Expand Up @@ -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:
Expand All @@ -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"))
Expand Down
131 changes: 128 additions & 3 deletions python/packages/openai/tests/openai/test_openai_chat_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -92,6 +95,7 @@
OpenAIChatClient,
OpenAIChatCompletionClient,
OpenAIChatOptions,
OpenAIContinuationToken,
RawOpenAIChatClient,
RawOpenAIChatCompletionClient,
)
Expand Down Expand Up @@ -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")
Expand All @@ -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")
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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"),
],
)
Expand Down
Loading