openai-agents 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

agents/models/chatcmpl_converter.py

@@ -51,6 +51,8 @@ from ..model_settings import MCPToolChoice
 from ..tool import FunctionTool, Tool
 from .fake_id import FAKE_RESPONSES_ID
 
+ResponseInputContentWithAudioParam = Union[ResponseInputContentParam, ResponseInputAudioParam]
+
 
 class Converter:
     @classmethod
@@ -136,7 +138,9 @@ class Converter:
         )
         if message.content:
             message_item.content.append(
-                ResponseOutputText(text=message.content, type="output_text", annotations=[])
+                ResponseOutputText(
+                    text=message.content, type="output_text", annotations=[], logprobs=[]
+                )
             )
         if message.refusal:
             message_item.content.append(
@@ -246,7 +250,7 @@ class Converter:
 
     @classmethod
     def extract_text_content(
-        cls, content: str | Iterable[ResponseInputContentParam]
+        cls, content: str | Iterable[ResponseInputContentWithAudioParam]
     ) -> str | list[ChatCompletionContentPartTextParam]:
         all_content = cls.extract_all_content(content)
         if isinstance(all_content, str):
@@ -259,7 +263,7 @@ class Converter:
 
     @classmethod
     def extract_all_content(
-        cls, content: str | Iterable[ResponseInputContentParam]
+        cls, content: str | Iterable[ResponseInputContentWithAudioParam]
     ) -> str | list[ChatCompletionContentPartParam]:
         if isinstance(content, str):
             return content
@@ -535,7 +539,7 @@ class Converter:
             elif func_output := cls.maybe_function_tool_call_output(item):
                 flush_assistant_message()
                 output_content = cast(
-                    Union[str, Iterable[ResponseInputContentParam]], func_output["output"]
+                    Union[str, Iterable[ResponseInputContentWithAudioParam]], func_output["output"]
                 )
                 msg: ChatCompletionToolMessageParam = {
                     "role": "tool",

agents/models/chatcmpl_stream_handler.py

@@ -150,6 +150,12 @@ class ChatCmplStreamHandler:
                     )
 
                 if reasoning_content and state.reasoning_content_index_and_output:
+                    # Ensure summary list has at least one element
+                    if not state.reasoning_content_index_and_output[1].summary:
+                        state.reasoning_content_index_and_output[1].summary = [
+                            Summary(text="", type="summary_text")
+                        ]
+
                     yield ResponseReasoningSummaryTextDeltaEvent(
                         delta=reasoning_content,
                         item_id=FAKE_RESPONSES_ID,
@@ -201,7 +207,7 @@ class ChatCmplStreamHandler:
                     )
 
                     # Create a new summary with updated text
-                    if state.reasoning_content_index_and_output[1].content is None:
+                    if not state.reasoning_content_index_and_output[1].content:
                         state.reasoning_content_index_and_output[1].content = [
                             Content(text="", type="reasoning_text")
                         ]
@@ -225,6 +231,7 @@ class ChatCmplStreamHandler:
                             text="",
                             type="output_text",
                             annotations=[],
+                            logprobs=[],
                         ),
                     )
                     # Start a new assistant message stream
@@ -252,6 +259,7 @@ class ChatCmplStreamHandler:
                             text="",
                             type="output_text",
                             annotations=[],
+                            logprobs=[],
                         ),
                         type="response.content_part.added",
                         sequence_number=sequence_number.get_and_increment(),
@@ -303,12 +311,10 @@ class ChatCmplStreamHandler:
                     yield ResponseContentPartAddedEvent(
                         content_index=state.refusal_content_index_and_output[0],
                         item_id=FAKE_RESPONSES_ID,
-                        output_index=state.reasoning_content_index_and_output
-                        is not None,  # fixed 0 -> 0 or 1
-                        part=ResponseOutputText(
-                            text="",
-                            type="output_text",
-                            annotations=[],
+                        output_index=(1 if state.reasoning_content_index_and_output else 0),
+                        part=ResponseOutputRefusal(
+                            refusal="",
+                            type="refusal",
                         ),
                         type="response.content_part.added",
                         sequence_number=sequence_number.get_and_increment(),

agents/realtime/config.py

@@ -184,6 +184,9 @@ class RealtimeRunConfig(TypedDict):
     tracing_disabled: NotRequired[bool]
     """Whether tracing is disabled for this run."""
 
+    async_tool_calls: NotRequired[bool]
+    """Whether function tool calls should run asynchronously. Defaults to True."""
+
     # TODO (rm) Add history audio storage config
 
 

agents/realtime/events.py

@@ -69,6 +69,10 @@ class RealtimeToolStart:
     """The agent that updated."""
 
     tool: Tool
+    """The tool being called."""
+
+    arguments: str
+    """The arguments passed to the tool as a JSON string."""
 
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
@@ -86,6 +90,9 @@ class RealtimeToolEnd:
     tool: Tool
     """The tool that was called."""
 
+    arguments: str
+    """The arguments passed to the tool as a JSON string."""
+
     output: Any
     """The output of the tool call."""
 

agents/realtime/model.py

@@ -139,6 +139,13 @@ class RealtimeModelConfig(TypedDict):
     is played to the user.
     """
 
+    call_id: NotRequired[str]
+    """Attach to an existing realtime call instead of creating a new session.
+
+    When provided, the transport connects using the `call_id` query string parameter rather than a
+    model name. This is used for SIP-originated calls that are accepted via the Realtime Calls API.
+    """
+
 
 class RealtimeModel(abc.ABC):
     """Interface for connecting to a realtime model and sending/receiving events."""

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

@@ -208,7 +208,18 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
         self._playback_tracker = options.get("playback_tracker", None)
 
-        self.model = model_settings.get("model_name", self.model)
+        call_id = options.get("call_id")
+        model_name = model_settings.get("model_name")
+        if call_id and model_name:
+            error_message = (
+                "Cannot specify both `call_id` and `model_name` "
+                "when attaching to an existing realtime call."
+            )
+            raise UserError(error_message)
+
+        if model_name:
+            self.model = model_name
+
         api_key = await get_api_key(options.get("api_key"))
 
         if "tracing" in model_settings:
@@ -216,7 +227,10 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         else:
             self._tracing_config = "auto"
 
-        url = options.get("url", f"wss://api.openai.com/v1/realtime?model={self.model}")
+        if call_id:
+            url = options.get("url", f"wss://api.openai.com/v1/realtime?call_id={call_id}")
+        else:
+            url = options.get("url", f"wss://api.openai.com/v1/realtime?model={self.model}")
 
         headers: dict[str, str] = {}
         if options.get("headers") is not None:
@@ -266,7 +280,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 +409,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 +417,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 +446,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 +535,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,12 +639,13 @@ 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()
-            # Avoid sending conversation.item.truncate here; when GA is set to
-            # interrupt on VAD start, the server will handle truncation.
+            # Avoid sending conversation.item.truncate here. When the session's
+            # turn_detection.interrupt_response is enabled (GA default), the server emits
+            # conversation.item.truncated after the VAD start and takes care of history updates.
         elif parsed.type == "response.created":
             self._ongoing_response = True
             await self._emit_event(RealtimeModelTurnStartedEvent())
@@ -920,6 +944,18 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         return converted_tools
 
 
+class OpenAIRealtimeSIPModel(OpenAIRealtimeWebSocketModel):
+    """Realtime model that attaches to SIP-originated calls using a call ID."""
+
+    async def connect(self, options: RealtimeModelConfig) -> None:
+        call_id = options.get("call_id")
+        if not call_id:
+            raise UserError("OpenAIRealtimeSIPModel requires `call_id` in the model configuration.")
+
+        sip_options = options.copy()
+        await super().connect(sip_options)
+
+
 class _ConversionHelper:
     @classmethod
     def conversation_item_to_realtime_message_item(

agents/realtime/session.py

@@ -112,7 +112,7 @@ class RealtimeSession(RealtimeModelListener):
         }
         self._event_queue: asyncio.Queue[RealtimeSessionEvent] = asyncio.Queue()
         self._closed = False
-        self._stored_exception: Exception | None = None
+        self._stored_exception: BaseException | None = None
 
         # Guardrails state tracking
         self._interrupted_response_ids: set[str] = set()
@@ -123,6 +123,8 @@ class RealtimeSession(RealtimeModelListener):
         )
 
         self._guardrail_tasks: set[asyncio.Task[Any]] = set()
+        self._tool_call_tasks: set[asyncio.Task[Any]] = set()
+        self._async_tool_calls: bool = bool(self._run_config.get("async_tool_calls", True))
 
     @property
     def model(self) -> RealtimeModel:
@@ -216,7 +218,11 @@ class RealtimeSession(RealtimeModelListener):
         if event.type == "error":
             await self._put_event(RealtimeError(info=self._event_info, error=event.error))
         elif event.type == "function_call":
-            await self._handle_tool_call(event)
+            agent_snapshot = self._current_agent
+            if self._async_tool_calls:
+                self._enqueue_tool_call_task(event, agent_snapshot)
+            else:
+                await self._handle_tool_call(event, agent_snapshot=agent_snapshot)
         elif event.type == "audio":
             await self._put_event(
                 RealtimeAudio(
@@ -384,11 +390,17 @@ class RealtimeSession(RealtimeModelListener):
         """Put an event into the queue."""
         await self._event_queue.put(event)
 
-    async def _handle_tool_call(self, event: RealtimeModelToolCallEvent) -> None:
+    async def _handle_tool_call(
+        self,
+        event: RealtimeModelToolCallEvent,
+        *,
+        agent_snapshot: RealtimeAgent | None = None,
+    ) -> None:
         """Handle a tool call event."""
+        agent = agent_snapshot or self._current_agent
         tools, handoffs = await asyncio.gather(
-            self._current_agent.get_all_tools(self._context_wrapper),
-            self._get_handoffs(self._current_agent, self._context_wrapper),
+            agent.get_all_tools(self._context_wrapper),
+            self._get_handoffs(agent, self._context_wrapper),
         )
         function_map = {tool.name: tool for tool in tools if isinstance(tool, FunctionTool)}
         handoff_map = {handoff.tool_name: handoff for handoff in handoffs}
@@ -398,7 +410,8 @@ class RealtimeSession(RealtimeModelListener):
                 RealtimeToolStart(
                     info=self._event_info,
                     tool=function_map[event.name],
-                    agent=self._current_agent,
+                    agent=agent,
+                    arguments=event.arguments,
                 )
             )
 
@@ -423,7 +436,8 @@ class RealtimeSession(RealtimeModelListener):
                     info=self._event_info,
                     tool=func_tool,
                     output=result,
-                    agent=self._current_agent,
+                    agent=agent,
+                    arguments=event.arguments,
                 )
             )
         elif event.name in handoff_map:
@@ -444,7 +458,7 @@ class RealtimeSession(RealtimeModelListener):
                 )
 
             # Store previous agent for event
-            previous_agent = self._current_agent
+            previous_agent = agent
 
             # Update current agent
             self._current_agent = result
@@ -704,7 +718,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]
@@ -752,10 +766,49 @@ class RealtimeSession(RealtimeModelListener):
                 task.cancel()
         self._guardrail_tasks.clear()
 
+    def _enqueue_tool_call_task(
+        self, event: RealtimeModelToolCallEvent, agent_snapshot: RealtimeAgent
+    ) -> None:
+        """Run tool calls in the background to avoid blocking realtime transport."""
+        task = asyncio.create_task(self._handle_tool_call(event, agent_snapshot=agent_snapshot))
+        self._tool_call_tasks.add(task)
+        task.add_done_callback(self._on_tool_call_task_done)
+
+    def _on_tool_call_task_done(self, task: asyncio.Task[Any]) -> None:
+        self._tool_call_tasks.discard(task)
+
+        if task.cancelled():
+            return
+
+        exception = task.exception()
+        if exception is None:
+            return
+
+        logger.exception("Realtime tool call task failed", exc_info=exception)
+
+        if self._stored_exception is None:
+            self._stored_exception = exception
+
+        asyncio.create_task(
+            self._put_event(
+                RealtimeError(
+                    info=self._event_info,
+                    error={"message": f"Tool call task failed: {exception}"},
+                )
+            )
+        )
+
+    def _cleanup_tool_call_tasks(self) -> None:
+        for task in self._tool_call_tasks:
+            if not task.done():
+                task.cancel()
+        self._tool_call_tasks.clear()
+
     async def _cleanup(self) -> None:
         """Clean up all resources and mark session as closed."""
         # Cancel and cleanup guardrail tasks
         self._cleanup_guardrail_tasks()
+        self._cleanup_tool_call_tasks()
 
         # Remove ourselves as a listener
         self._model.remove_listener(self)

agents/run.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import inspect
 import os
+import warnings
 from dataclasses import dataclass, field
 from typing import Any, Callable, Generic, cast, get_args
 
@@ -720,7 +722,40 @@ class AgentRunner:
         conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
 
-        return asyncio.get_event_loop().run_until_complete(
+        # Python 3.14 stopped implicitly wiring up a default event loop
+        # when synchronous code touches asyncio APIs for the first time.
+        # Several of our synchronous entry points (for example the Redis/SQLAlchemy session helpers)
+        # construct asyncio primitives like asyncio.Lock during __init__,
+        # which binds them to whatever loop happens to be the thread's default at that moment.
+        # To keep those locks usable we must ensure that run_sync reuses that same default loop
+        # instead of hopping over to a brand-new asyncio.run() loop.
+        try:
+            already_running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            already_running_loop = None
+
+        if already_running_loop is not None:
+            # This method is only expected to run when no loop is already active.
+            # (Each thread has its own default loop; concurrent sync runs should happen on
+            # different threads. In a single thread use the async API to interleave work.)
+            raise RuntimeError(
+                "AgentRunner.run_sync() cannot be called when an event loop is already running."
+            )
+
+        policy = asyncio.get_event_loop_policy()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            try:
+                default_loop = policy.get_event_loop()
+            except RuntimeError:
+                default_loop = policy.new_event_loop()
+                policy.set_event_loop(default_loop)
+
+        # We intentionally leave the default loop open even if we had to create one above. Session
+        # instances and other helpers stash loop-bound primitives between calls and expect to find
+        # the same default loop every time run_sync is invoked on this thread.
+        # Schedule the async run on the default loop so that we can manage cancellation explicitly.
+        task = default_loop.create_task(
             self.run(
                 starting_agent,
                 input,
@@ -734,6 +769,24 @@ class AgentRunner:
             )
         )
 
+        try:
+            # Drive the coroutine to completion, harvesting the final RunResult.
+            return default_loop.run_until_complete(task)
+        except BaseException:
+            # If the sync caller aborts (KeyboardInterrupt, etc.), make sure the scheduled task
+            # does not linger on the shared loop by cancelling it and waiting for completion.
+            if not task.done():
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    default_loop.run_until_complete(task)
+            raise
+        finally:
+            if not default_loop.is_closed():
+                # The loop stays open for subsequent runs, but we still need to flush any pending
+                # async generators so their cleanup code executes promptly.
+                with contextlib.suppress(RuntimeError):
+                    default_loop.run_until_complete(default_loop.shutdown_asyncgens())
+
     def run_streamed(
         self,
         starting_agent: Agent[TContext],
@@ -1138,6 +1191,15 @@ class AgentRunner:
 
             streamed_result.is_complete = True
         finally:
+            if streamed_result._input_guardrails_task:
+                try:
+                    await AgentRunner._input_guardrail_tripwire_triggered_for_stream(
+                        streamed_result
+                    )
+                except Exception as e:
+                    logger.debug(
+                        f"Error in streamed_result finalize for agent {current_agent.name} - {e}"
+                    )
             if current_span:
                 current_span.finish(reset_current=True)
             if streamed_result.trace:

agents/stream_events.py

@@ -37,6 +37,7 @@ class RunItemStreamEvent:
         "tool_output",
         "reasoning_item_created",
         "mcp_approval_requested",
+        "mcp_approval_response",
         "mcp_list_tools",
     ]
     """The name of the event."""

agents/tool.py

@@ -15,7 +15,7 @@ from openai.types.responses.response_output_item import LocalShellCall, McpAppro
 from openai.types.responses.tool_param import CodeInterpreter, ImageGeneration, Mcp
 from openai.types.responses.web_search_tool import Filters as WebSearchToolFilters
 from openai.types.responses.web_search_tool_param import UserLocation
-from pydantic import BaseModel, TypeAdapter, ValidationError
+from pydantic import BaseModel, TypeAdapter, ValidationError, model_validator
 from typing_extensions import Concatenate, NotRequired, ParamSpec, TypedDict
 
 from . import _debug
@@ -75,6 +75,13 @@ class ToolOutputImage(BaseModel):
     file_id: str | None = None
     detail: Literal["low", "high", "auto"] | None = None
 
+    @model_validator(mode="after")
+    def check_at_least_one_required_field(self) -> ToolOutputImage:
+        """Validate that at least one of image_url or file_id is provided."""
+        if self.image_url is None and self.file_id is None:
+            raise ValueError("At least one of image_url or file_id must be provided")
+        return self
+
 
 class ToolOutputImageDict(TypedDict, total=False):
     """TypedDict variant for image tool outputs."""
@@ -98,6 +105,13 @@ class ToolOutputFileContent(BaseModel):
     file_id: str | None = None
     filename: str | None = None
 
+    @model_validator(mode="after")
+    def check_at_least_one_required_field(self) -> ToolOutputFileContent:
+        """Validate that at least one of file_data, file_url, or file_id is provided."""
+        if self.file_data is None and self.file_url is None and self.file_id is None:
+            raise ValueError("At least one of file_data, file_url, or file_id must be provided")
+        return self
+
 
 class ToolOutputFileContentDict(TypedDict, total=False):
     """TypedDict variant for file content tool outputs."""