openai-agents 0.3.3__py3-none-any.whl → 0.4.1__py3-none-any.whl

agents/models/chatcmpl_converter.py

@@ -2,12 +2,13 @@ from __future__ import annotations
 
 import json
 from collections.abc import Iterable
-from typing import Any, Literal, cast
+from typing import Any, Literal, Union, cast
 
-from openai import NOT_GIVEN, NotGiven
+from openai import Omit, omit
 from openai.types.chat import (
     ChatCompletionAssistantMessageParam,
     ChatCompletionContentPartImageParam,
+    ChatCompletionContentPartInputAudioParam,
     ChatCompletionContentPartParam,
     ChatCompletionContentPartTextParam,
     ChatCompletionDeveloperMessageParam,
@@ -27,6 +28,7 @@ from openai.types.responses import (
     ResponseFileSearchToolCallParam,
     ResponseFunctionToolCall,
     ResponseFunctionToolCallParam,
+    ResponseInputAudioParam,
     ResponseInputContentParam,
     ResponseInputFileParam,
     ResponseInputImageParam,
@@ -54,9 +56,9 @@ class Converter:
     @classmethod
     def convert_tool_choice(
         cls, tool_choice: Literal["auto", "required", "none"] | str | MCPToolChoice | None
-    ) -> ChatCompletionToolChoiceOptionParam | NotGiven:
+    ) -> ChatCompletionToolChoiceOptionParam | Omit:
         if tool_choice is None:
-            return NOT_GIVEN
+            return omit
         elif isinstance(tool_choice, MCPToolChoice):
             raise UserError("MCPToolChoice is not supported for Chat Completions models")
         elif tool_choice == "auto":
@@ -76,9 +78,9 @@ class Converter:
     @classmethod
     def convert_response_format(
         cls, final_output_schema: AgentOutputSchemaBase | None
-    ) -> ResponseFormat | NotGiven:
+    ) -> ResponseFormat | Omit:
         if not final_output_schema or final_output_schema.is_plain_text():
-            return NOT_GIVEN
+            return omit
 
         return {
             "type": "json_schema",
@@ -287,23 +289,44 @@ class Converter:
                         },
                     )
                 )
+            elif isinstance(c, dict) and c.get("type") == "input_audio":
+                casted_audio_param = cast(ResponseInputAudioParam, c)
+                audio_payload = casted_audio_param.get("input_audio")
+                if not audio_payload:
+                    raise UserError(
+                        f"Only audio data is supported for input_audio {casted_audio_param}"
+                    )
+                if not isinstance(audio_payload, dict):
+                    raise UserError(
+                        f"input_audio must provide audio data and format {casted_audio_param}"
+                    )
+                audio_data = audio_payload.get("data")
+                audio_format = audio_payload.get("format")
+                if not audio_data or not audio_format:
+                    raise UserError(
+                        f"input_audio requires both data and format {casted_audio_param}"
+                    )
+                out.append(
+                    ChatCompletionContentPartInputAudioParam(
+                        type="input_audio",
+                        input_audio={
+                            "data": audio_data,
+                            "format": audio_format,
+                        },
+                    )
+                )
             elif isinstance(c, dict) and c.get("type") == "input_file":
                 casted_file_param = cast(ResponseInputFileParam, c)
                 if "file_data" not in casted_file_param or not casted_file_param["file_data"]:
                     raise UserError(
                         f"Only file_data is supported for input_file {casted_file_param}"
                     )
-                if "filename" not in casted_file_param or not casted_file_param["filename"]:
-                    raise UserError(f"filename must be provided for input_file {casted_file_param}")
-                out.append(
-                    File(
-                        type="file",
-                        file=FileFile(
-                            file_data=casted_file_param["file_data"],
-                            filename=casted_file_param["filename"],
-                        ),
-                    )
-                )
+                filedata = FileFile(file_data=casted_file_param["file_data"])
+
+                if "filename" in casted_file_param and casted_file_param["filename"]:
+                    filedata["filename"] = casted_file_param["filename"]
+
+                out.append(File(type="file", file=filedata))
             else:
                 raise UserError(f"Unknown content: {c}")
         return out
@@ -511,10 +534,13 @@ class Converter:
             # 5) function call output => tool message
             elif func_output := cls.maybe_function_tool_call_output(item):
                 flush_assistant_message()
+                output_content = cast(
+                    Union[str, Iterable[ResponseInputContentParam]], func_output["output"]
+                )
                 msg: ChatCompletionToolMessageParam = {
                     "role": "tool",
                     "tool_call_id": func_output["call_id"],
-                    "content": func_output["output"],
+                    "content": cls.extract_text_content(output_content),
                 }
                 result.append(msg)
 

agents/models/openai_chatcompletions.py

@@ -3,9 +3,9 @@ from __future__ import annotations
 import json
 import time
 from collections.abc import AsyncIterator
-from typing import TYPE_CHECKING, Any, Literal, overload
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
-from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream
+from openai import AsyncOpenAI, AsyncStream, Omit, omit
 from openai.types import ChatModel
 from openai.types.chat import ChatCompletion, ChatCompletionChunk, ChatCompletionMessage
 from openai.types.chat.chat_completion import Choice
@@ -44,8 +44,8 @@ class OpenAIChatCompletionsModel(Model):
         self.model = model
         self._client = openai_client
 
-    def _non_null_or_not_given(self, value: Any) -> Any:
-        return value if value is not None else NOT_GIVEN
+    def _non_null_or_omit(self, value: Any) -> Any:
+        return value if value is not None else omit
 
     async def get_response(
         self,
@@ -243,13 +243,12 @@ class OpenAIChatCompletionsModel(Model):
         if tracing.include_data():
             span.span_data.input = converted_messages
 
-        parallel_tool_calls = (
-            True
-            if model_settings.parallel_tool_calls and tools and len(tools) > 0
-            else False
-            if model_settings.parallel_tool_calls is False
-            else NOT_GIVEN
-        )
+        if model_settings.parallel_tool_calls and tools:
+            parallel_tool_calls: bool | Omit = True
+        elif model_settings.parallel_tool_calls is False:
+            parallel_tool_calls = False
+        else:
+            parallel_tool_calls = omit
         tool_choice = Converter.convert_tool_choice(model_settings.tool_choice)
         response_format = Converter.convert_response_format(output_schema)
 
@@ -259,6 +258,7 @@ class OpenAIChatCompletionsModel(Model):
             converted_tools.append(Converter.convert_handoff_tool(handoff))
 
         converted_tools = _to_dump_compatible(converted_tools)
+        tools_param = converted_tools if converted_tools else omit
 
         if _debug.DONT_LOG_MODEL_DATA:
             logger.debug("Calling LLM")
@@ -288,28 +288,30 @@ class OpenAIChatCompletionsModel(Model):
             self._get_client(), model_settings, stream=stream
         )
 
+        stream_param: Literal[True] | Omit = True if stream else omit
+
         ret = await self._get_client().chat.completions.create(
             model=self.model,
             messages=converted_messages,
-            tools=converted_tools or NOT_GIVEN,
-            temperature=self._non_null_or_not_given(model_settings.temperature),
-            top_p=self._non_null_or_not_given(model_settings.top_p),
-            frequency_penalty=self._non_null_or_not_given(model_settings.frequency_penalty),
-            presence_penalty=self._non_null_or_not_given(model_settings.presence_penalty),
-            max_tokens=self._non_null_or_not_given(model_settings.max_tokens),
+            tools=tools_param,
+            temperature=self._non_null_or_omit(model_settings.temperature),
+            top_p=self._non_null_or_omit(model_settings.top_p),
+            frequency_penalty=self._non_null_or_omit(model_settings.frequency_penalty),
+            presence_penalty=self._non_null_or_omit(model_settings.presence_penalty),
+            max_tokens=self._non_null_or_omit(model_settings.max_tokens),
             tool_choice=tool_choice,
             response_format=response_format,
             parallel_tool_calls=parallel_tool_calls,
-            stream=stream,
-            stream_options=self._non_null_or_not_given(stream_options),
-            store=self._non_null_or_not_given(store),
-            reasoning_effort=self._non_null_or_not_given(reasoning_effort),
-            verbosity=self._non_null_or_not_given(model_settings.verbosity),
-            top_logprobs=self._non_null_or_not_given(model_settings.top_logprobs),
+            stream=cast(Any, stream_param),
+            stream_options=self._non_null_or_omit(stream_options),
+            store=self._non_null_or_omit(store),
+            reasoning_effort=self._non_null_or_omit(reasoning_effort),
+            verbosity=self._non_null_or_omit(model_settings.verbosity),
+            top_logprobs=self._non_null_or_omit(model_settings.top_logprobs),
             extra_headers=self._merge_headers(model_settings),
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
-            metadata=self._non_null_or_not_given(model_settings.metadata),
+            metadata=self._non_null_or_omit(model_settings.metadata),
             **(model_settings.extra_args or {}),
         )
 
@@ -319,14 +321,13 @@ class OpenAIChatCompletionsModel(Model):
         responses_tool_choice = OpenAIResponsesConverter.convert_tool_choice(
             model_settings.tool_choice
         )
-        if responses_tool_choice is None or responses_tool_choice == NOT_GIVEN:
+        if responses_tool_choice is None or responses_tool_choice is omit:
             # For Responses API data compatibility with Chat Completions patterns,
             # we need to set "none" if tool_choice is absent.
             # Without this fix, you'll get the following error:
             # pydantic_core._pydantic_core.ValidationError: 4 validation errors for Response
             # tool_choice.literal['none','auto','required']
             #   Input should be 'none', 'auto' or 'required'
-            #   [type=literal_error, input_value=NOT_GIVEN, input_type=NotGiven]
             # see also: https://github.com/openai/openai-agents-python/issues/980
             responses_tool_choice = "auto"
 

agents/models/openai_responses.py

@@ -4,9 +4,9 @@ import json
 from collections.abc import AsyncIterator
 from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, cast, overload
+from typing import TYPE_CHECKING, Any, Literal, Union, cast, overload
 
-from openai import NOT_GIVEN, APIStatusError, AsyncOpenAI, AsyncStream, NotGiven
+from openai import APIStatusError, AsyncOpenAI, AsyncStream, Omit, omit
 from openai.types import ChatModel
 from openai.types.responses import (
     Response,
@@ -69,8 +69,8 @@ class OpenAIResponsesModel(Model):
         self.model = model
         self._client = openai_client
 
-    def _non_null_or_not_given(self, value: Any) -> Any:
-        return value if value is not None else NOT_GIVEN
+    def _non_null_or_omit(self, value: Any) -> Any:
+        return value if value is not None else omit
 
     async def get_response(
         self,
@@ -249,13 +249,12 @@ class OpenAIResponsesModel(Model):
         list_input = ItemHelpers.input_to_new_input_list(input)
         list_input = _to_dump_compatible(list_input)
 
-        parallel_tool_calls = (
-            True
-            if model_settings.parallel_tool_calls and tools and len(tools) > 0
-            else False
-            if model_settings.parallel_tool_calls is False
-            else NOT_GIVEN
-        )
+        if model_settings.parallel_tool_calls and tools:
+            parallel_tool_calls: bool | Omit = True
+        elif model_settings.parallel_tool_calls is False:
+            parallel_tool_calls = False
+        else:
+            parallel_tool_calls = omit
 
         tool_choice = Converter.convert_tool_choice(model_settings.tool_choice)
         converted_tools = Converter.convert_tools(tools, handoffs)
@@ -297,36 +296,39 @@ class OpenAIResponsesModel(Model):
         if model_settings.top_logprobs is not None:
             extra_args["top_logprobs"] = model_settings.top_logprobs
         if model_settings.verbosity is not None:
-            if response_format != NOT_GIVEN:
+            if response_format is not omit:
                 response_format["verbosity"] = model_settings.verbosity  # type: ignore [index]
             else:
                 response_format = {"verbosity": model_settings.verbosity}
 
-        return await self._client.responses.create(
-            previous_response_id=self._non_null_or_not_given(previous_response_id),
-            conversation=self._non_null_or_not_given(conversation_id),
-            instructions=self._non_null_or_not_given(system_instructions),
+        stream_param: Literal[True] | Omit = True if stream else omit
+
+        response = await self._client.responses.create(
+            previous_response_id=self._non_null_or_omit(previous_response_id),
+            conversation=self._non_null_or_omit(conversation_id),
+            instructions=self._non_null_or_omit(system_instructions),
             model=self.model,
             input=list_input,
             include=include,
             tools=converted_tools_payload,
-            prompt=self._non_null_or_not_given(prompt),
-            temperature=self._non_null_or_not_given(model_settings.temperature),
-            top_p=self._non_null_or_not_given(model_settings.top_p),
-            truncation=self._non_null_or_not_given(model_settings.truncation),
-            max_output_tokens=self._non_null_or_not_given(model_settings.max_tokens),
+            prompt=self._non_null_or_omit(prompt),
+            temperature=self._non_null_or_omit(model_settings.temperature),
+            top_p=self._non_null_or_omit(model_settings.top_p),
+            truncation=self._non_null_or_omit(model_settings.truncation),
+            max_output_tokens=self._non_null_or_omit(model_settings.max_tokens),
             tool_choice=tool_choice,
             parallel_tool_calls=parallel_tool_calls,
-            stream=stream,
+            stream=cast(Any, stream_param),
             extra_headers=self._merge_headers(model_settings),
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             text=response_format,
-            store=self._non_null_or_not_given(model_settings.store),
-            reasoning=self._non_null_or_not_given(model_settings.reasoning),
-            metadata=self._non_null_or_not_given(model_settings.metadata),
+            store=self._non_null_or_omit(model_settings.store),
+            reasoning=self._non_null_or_omit(model_settings.reasoning),
+            metadata=self._non_null_or_omit(model_settings.metadata),
             **extra_args,
         )
+        return cast(Union[Response, AsyncStream[ResponseStreamEvent]], response)
 
     def _get_client(self) -> AsyncOpenAI:
         if self._client is None:
@@ -351,9 +353,9 @@ class Converter:
     @classmethod
     def convert_tool_choice(
         cls, tool_choice: Literal["auto", "required", "none"] | str | MCPToolChoice | None
-    ) -> response_create_params.ToolChoice | NotGiven:
+    ) -> response_create_params.ToolChoice | Omit:
         if tool_choice is None:
-            return NOT_GIVEN
+            return omit
         elif isinstance(tool_choice, MCPToolChoice):
             return {
                 "server_label": tool_choice.server_label,
@@ -404,9 +406,9 @@ class Converter:
     @classmethod
     def get_response_format(
         cls, output_schema: AgentOutputSchemaBase | None
-    ) -> ResponseTextConfigParam | NotGiven:
+    ) -> ResponseTextConfigParam | Omit:
         if output_schema is None or output_schema.is_plain_text():
-            return NOT_GIVEN
+            return omit
         else:
             return {
                 "format": {

agents/realtime/handoffs.py

@@ -13,10 +13,10 @@ from ..strict_schema import ensure_strict_json_schema
 from ..tracing.spans import SpanError
 from ..util import _error_tracing, _json
 from ..util._types import MaybeAwaitable
+from . import RealtimeAgent
 
 if TYPE_CHECKING:
     from ..agent import AgentBase
-    from . import RealtimeAgent
 
 
 # The handoff input type is the type of data passed when the agent is called via a handoff.

agents/realtime/model_inputs.py

@@ -95,6 +95,9 @@ class RealtimeModelSendToolOutput:
 class RealtimeModelSendInterrupt:
     """Send an interrupt to the model."""
 
+    force_response_cancel: bool = False
+    """Force sending a response.cancel event even if automatic cancellation is enabled."""
+
 
 @dataclass
 class RealtimeModelSendSessionUpdate:

agents/realtime/openai_realtime.py

@@ -266,7 +266,8 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
     async def _emit_event(self, event: RealtimeModelEvent) -> None:
         """Emit an event to the listeners."""
-        for listener in self._listeners:
+        # Copy list to avoid modification during iteration
+        for listener in list(self._listeners):
             await listener.on_event(event)
 
     async def _listen_for_messages(self):
@@ -394,6 +395,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         current_item_id = playback_state.get("current_item_id")
         current_item_content_index = playback_state.get("current_item_content_index")
         elapsed_ms = playback_state.get("elapsed_ms")
+
         if current_item_id is None or elapsed_ms is None:
             logger.debug(
                 "Skipping interrupt. "
@@ -401,29 +403,28 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                 f"elapsed ms: {elapsed_ms}, "
                 f"content index: {current_item_content_index}"
             )
-            return
-
-        current_item_content_index = current_item_content_index or 0
-        if elapsed_ms > 0:
-            await self._emit_event(
-                RealtimeModelAudioInterruptedEvent(
-                    item_id=current_item_id,
-                    content_index=current_item_content_index,
-                )
-            )
-            converted = _ConversionHelper.convert_interrupt(
-                current_item_id,
-                current_item_content_index,
-                int(elapsed_ms),
-            )
-            await self._send_raw_message(converted)
         else:
-            logger.debug(
-                "Didn't interrupt bc elapsed ms is < 0. "
-                f"Item id: {current_item_id}, "
-                f"elapsed ms: {elapsed_ms}, "
-                f"content index: {current_item_content_index}"
-            )
+            current_item_content_index = current_item_content_index or 0
+            if elapsed_ms > 0:
+                await self._emit_event(
+                    RealtimeModelAudioInterruptedEvent(
+                        item_id=current_item_id,
+                        content_index=current_item_content_index,
+                    )
+                )
+                converted = _ConversionHelper.convert_interrupt(
+                    current_item_id,
+                    current_item_content_index,
+                    int(elapsed_ms),
+                )
+                await self._send_raw_message(converted)
+            else:
+                logger.debug(
+                    "Didn't interrupt bc elapsed ms is < 0. "
+                    f"Item id: {current_item_id}, "
+                    f"elapsed ms: {elapsed_ms}, "
+                    f"content index: {current_item_content_index}"
+                )
 
         session = self._created_session
         automatic_response_cancellation_enabled = (
@@ -431,14 +432,18 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             and session.audio is not None
             and session.audio.input is not None
             and session.audio.input.turn_detection is not None
-            and session.audio.input.turn_detection.interrupt_response is True,
+            and session.audio.input.turn_detection.interrupt_response is True
         )
-        if not automatic_response_cancellation_enabled:
+        should_cancel_response = event.force_response_cancel or (
+            not automatic_response_cancellation_enabled
+        )
+        if should_cancel_response:
             await self._cancel_response()
 
-        self._audio_state_tracker.on_interrupted()
-        if self._playback_tracker:
-            self._playback_tracker.on_interrupted()
+        if current_item_id is not None and elapsed_ms is not None:
+            self._audio_state_tracker.on_interrupted()
+            if self._playback_tracker:
+                self._playback_tracker.on_interrupted()
 
     async def _send_session_update(self, event: RealtimeModelSendSessionUpdate) -> None:
         """Send a session update to the model."""
@@ -516,6 +521,10 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             self._websocket = None
         if self._websocket_task:
             self._websocket_task.cancel()
+            try:
+                await self._websocket_task
+            except asyncio.CancelledError:
+                pass
             self._websocket_task = None
 
     async def _cancel_response(self) -> None:
@@ -616,7 +625,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                     and session.audio is not None
                     and session.audio.input is not None
                     and session.audio.input.turn_detection is not None
-                    and session.audio.input.turn_detection.interrupt_response is True,
+                    and session.audio.input.turn_detection.interrupt_response is True
                 )
                 if not automatic_response_cancellation_enabled:
                     await self._cancel_response()

agents/realtime/session.py

@@ -704,7 +704,7 @@ class RealtimeSession(RealtimeModelListener):
             )
 
             # Interrupt the model
-            await self._model.send_event(RealtimeModelSendInterrupt())
+            await self._model.send_event(RealtimeModelSendInterrupt(force_response_cancel=True))
 
             # Send guardrail triggered message
             guardrail_names = [result.guardrail.get_name() for result in triggered_results]

agents/result.py

@@ -4,7 +4,7 @@ import abc
 import asyncio
 from collections.abc import AsyncIterator
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, Literal, cast
 
 from typing_extensions import TypeVar
 
@@ -164,6 +164,9 @@ class RunResultStreaming(RunResultBase):
     _output_guardrails_task: asyncio.Task[Any] | None = field(default=None, repr=False)
     _stored_exception: Exception | None = field(default=None, repr=False)
 
+    # Soft cancel state
+    _cancel_mode: Literal["none", "immediate", "after_turn"] = field(default="none", repr=False)
+
     @property
     def last_agent(self) -> Agent[Any]:
         """The last agent that was run. Updates as the agent run progresses, so the true last agent
@@ -171,17 +174,51 @@ class RunResultStreaming(RunResultBase):
         """
         return self.current_agent
 
-    def cancel(self) -> None:
-        """Cancels the streaming run, stopping all background tasks and marking the run as
-        complete."""
-        self._cleanup_tasks()  # Cancel all running tasks
-        self.is_complete = True  # Mark the run as complete to stop event streaming
+    def cancel(self, mode: Literal["immediate", "after_turn"] = "immediate") -> None:
+        """Cancel the streaming run.
 
-        # Optionally, clear the event queue to prevent processing stale events
-        while not self._event_queue.empty():
-            self._event_queue.get_nowait()
-        while not self._input_guardrail_queue.empty():
-            self._input_guardrail_queue.get_nowait()
+        Args:
+            mode: Cancellation strategy:
+                - "immediate": Stop immediately, cancel all tasks, clear queues (default)
+                - "after_turn": Complete current turn gracefully before stopping
+                    * Allows LLM response to finish
+                    * Executes pending tool calls
+                    * Saves session state properly
+                    * Tracks usage accurately
+                    * Stops before next turn begins
+
+        Example:
+            ```python
+            result = Runner.run_streamed(agent, "Task", session=session)
+
+            async for event in result.stream_events():
+                if user_interrupted():
+                    result.cancel(mode="after_turn")  # Graceful
+                    # result.cancel()  # Immediate (default)
+            ```
+
+        Note: After calling cancel(), you should continue consuming stream_events()
+        to allow the cancellation to complete properly.
+        """
+        # Store the cancel mode for the background task to check
+        self._cancel_mode = mode
+
+        if mode == "immediate":
+            # Existing behavior - immediate shutdown
+            self._cleanup_tasks()  # Cancel all running tasks
+            self.is_complete = True  # Mark the run as complete to stop event streaming
+
+            # Optionally, clear the event queue to prevent processing stale events
+            while not self._event_queue.empty():
+                self._event_queue.get_nowait()
+            while not self._input_guardrail_queue.empty():
+                self._input_guardrail_queue.get_nowait()
+
+        elif mode == "after_turn":
+            # Soft cancel - just set the flag
+            # The streaming loop will check this and stop gracefully
+            # Don't call _cleanup_tasks() or clear queues yet
+            pass
 
     async def stream_events(self) -> AsyncIterator[StreamEvent]:
         """Stream deltas for new items as they are generated. We're using the types from the