openai-agents 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

agents/agent.py

@@ -214,7 +214,7 @@ class Agent(AgentBase, Generic[TContext]):
       calls result in a final output.
 
       NOTE: This configuration is specific to FunctionTools. Hosted tools, such as file search,
-      web search, etc are always processed by the LLM.
+      web search, etc. are always processed by the LLM.
     """
 
     reset_tool_choice: bool = True
@@ -289,30 +289,3 @@ class Agent(AgentBase, Generic[TContext]):
     ) -> ResponsePromptParam | None:
         """Get the prompt for the agent."""
         return await PromptUtil.to_model_input(self.prompt, run_context, self)
-
-    async def get_mcp_tools(self, run_context: RunContextWrapper[TContext]) -> list[Tool]:
-        """Fetches the available tools from the MCP servers."""
-        convert_schemas_to_strict = self.mcp_config.get("convert_schemas_to_strict", False)
-        return await MCPUtil.get_all_function_tools(
-            self.mcp_servers, convert_schemas_to_strict, run_context, self
-        )
-
-    async def get_all_tools(self, run_context: RunContextWrapper[Any]) -> list[Tool]:
-        """All agent tools, including MCP tools and function tools."""
-        mcp_tools = await self.get_mcp_tools(run_context)
-
-        async def _check_tool_enabled(tool: Tool) -> bool:
-            if not isinstance(tool, FunctionTool):
-                return True
-
-            attr = tool.is_enabled
-            if isinstance(attr, bool):
-                return attr
-            res = attr(run_context, self)
-            if inspect.isawaitable(res):
-                return bool(await res)
-            return bool(res)
-
-        results = await asyncio.gather(*(_check_tool_enabled(t) for t in self.tools))
-        enabled: list[Tool] = [t for t, ok in zip(self.tools, results) if ok]
-        return [*mcp_tools, *enabled]

agents/agent_output.py

@@ -116,7 +116,7 @@ class AgentOutputSchema(AgentOutputSchemaBase):
                 raise UserError(
                     "Strict JSON schema is enabled, but the output type is not valid. "
                     "Either make the output type strict, "
-                    "or wrap your type with AgentOutputSchema(your_type, strict_json_schema=False)"
+                    "or wrap your type with AgentOutputSchema(YourType, strict_json_schema=False)"
                 ) from e
 
     def is_plain_text(self) -> bool:

agents/extensions/models/litellm_model.py

@@ -45,6 +45,14 @@ from ...tracing.spans import Span
 from ...usage import Usage
 
 
+class InternalChatCompletionMessage(ChatCompletionMessage):
+    """
+    An internal subclass to carry reasoning_content without modifying the original model.
+    """
+
+    reasoning_content: str
+
+
 class LitellmModel(Model):
     """This class enables using any model via LiteLLM. LiteLLM allows you to acess OpenAPI,
     Anthropic, Gemini, Mistral, and many other models.
@@ -364,13 +372,18 @@ class LitellmConverter:
             provider_specific_fields.get("refusal", None) if provider_specific_fields else None
         )
 
-        return ChatCompletionMessage(
+        reasoning_content = ""
+        if hasattr(message, "reasoning_content") and message.reasoning_content:
+            reasoning_content = message.reasoning_content
+
+        return InternalChatCompletionMessage(
             content=message.content,
             refusal=refusal,
             role="assistant",
             annotations=cls.convert_annotations_to_openai(message),
             audio=message.get("audio", None),  # litellm deletes audio if not present
             tool_calls=tool_calls,
+            reasoning_content=reasoning_content,
         )
 
     @classmethod

agents/function_schema.py

@@ -76,7 +76,7 @@ class FuncSchema:
 
 @dataclass
 class FuncDocumentation:
-    """Contains metadata about a python function, extracted from its docstring."""
+    """Contains metadata about a Python function, extracted from its docstring."""
 
     name: str
     """The name of the function, via `__name__`."""
@@ -194,7 +194,7 @@ def function_schema(
     strict_json_schema: bool = True,
 ) -> FuncSchema:
     """
-    Given a python function, extracts a `FuncSchema` from it, capturing the name, description,
+    Given a Python function, extracts a `FuncSchema` from it, capturing the name, description,
     parameter descriptions, and other metadata.
 
     Args:
@@ -208,7 +208,7 @@ def function_schema(
             descriptions.
         strict_json_schema: Whether the JSON schema is in strict mode. If True, we'll ensure that
             the schema adheres to the "strict" standard the OpenAI API expects. We **strongly**
-            recommend setting this to True, as it increases the likelihood of the LLM providing
+            recommend setting this to True, as it increases the likelihood of the LLM producing
             correct JSON input.
 
     Returns:

agents/guardrail.py

@@ -78,8 +78,9 @@ class InputGuardrail(Generic[TContext]):
     You can use the `@input_guardrail()` decorator to turn a function into an `InputGuardrail`, or
     create an `InputGuardrail` manually.
 
-    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, the agent
-    execution will immediately stop and a `InputGuardrailTripwireTriggered` exception will be raised
+    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`,
+    the agent's execution will immediately stop, and
+    an `InputGuardrailTripwireTriggered` exception will be raised
     """
 
     guardrail_function: Callable[
@@ -132,7 +133,7 @@ class OutputGuardrail(Generic[TContext]):
     You can use the `@output_guardrail()` decorator to turn a function into an `OutputGuardrail`,
     or create an `OutputGuardrail` manually.
 
-    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, a
+    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, an
     `OutputGuardrailTripwireTriggered` exception will be raised.
     """
 
@@ -316,7 +317,7 @@ def output_guardrail(
     ) -> OutputGuardrail[TContext_co]:
         return OutputGuardrail(
             guardrail_function=f,
-            # Guardrail name defaults to function name when not specified (None).
+            # Guardrail name defaults to function's name when not specified (None).
             name=name if name else f.__name__,
         )
 

agents/models/chatcmpl_converter.py

@@ -36,6 +36,7 @@ from openai.types.responses import (
     ResponseOutputRefusal,
     ResponseOutputText,
     ResponseReasoningItem,
+    ResponseReasoningItemParam,
 )
 from openai.types.responses.response_input_param import FunctionCallOutput, ItemReference, Message
 from openai.types.responses.response_reasoning_item import Summary
@@ -210,6 +211,12 @@ class Converter:
             return cast(ResponseOutputMessageParam, item)
         return None
 
+    @classmethod
+    def maybe_reasoning_message(cls, item: Any) -> ResponseReasoningItemParam | None:
+        if isinstance(item, dict) and item.get("type") == "reasoning":
+            return cast(ResponseReasoningItemParam, item)
+        return None
+
     @classmethod
     def extract_text_content(
         cls, content: str | Iterable[ResponseInputContentParam]
@@ -459,7 +466,11 @@ class Converter:
                     f"Encountered an item_reference, which is not supported: {item_ref}"
                 )
 
-            # 7) If we haven't recognized it => fail or ignore
+            # 7) reasoning message => not handled
+            elif cls.maybe_reasoning_message(item):
+                pass
+
+            # 8) If we haven't recognized it => fail or ignore
             else:
                 raise UserError(f"Unhandled item type or structure: {item}")
 

agents/models/chatcmpl_stream_handler.py

@@ -198,6 +198,7 @@ class ChatCmplStreamHandler:
                     is not None,  # fixed 0 -> 0 or 1
                     type="response.output_text.delta",
                     sequence_number=sequence_number.get_and_increment(),
+                    logprobs=[],
                 )
                 # Accumulate the text into the response part
                 state.text_content_index_and_output[1].text += delta.content
@@ -288,10 +289,11 @@ class ChatCmplStreamHandler:
                     function_call = state.function_calls[tc_delta.index]
 
                     # Start streaming as soon as we have function name and call_id
-                    if (not state.function_call_streaming[tc_delta.index] and
-                        function_call.name and
-                        function_call.call_id):
-
+                    if (
+                        not state.function_call_streaming[tc_delta.index]
+                        and function_call.name
+                        and function_call.call_id
+                    ):
                         # Calculate the output index for this function call
                         function_call_starting_index = 0
                         if state.reasoning_content_index_and_output:
@@ -308,9 +310,9 @@ class ChatCmplStreamHandler:
 
                         # Mark this function call as streaming and store its output index
                         state.function_call_streaming[tc_delta.index] = True
-                        state.function_call_output_idx[
-                            tc_delta.index
-                        ] = function_call_starting_index
+                        state.function_call_output_idx[tc_delta.index] = (
+                            function_call_starting_index
+                        )
 
                         # Send initial function call added event
                         yield ResponseOutputItemAddedEvent(
@@ -327,10 +329,11 @@ class ChatCmplStreamHandler:
                         )
 
                     # Stream arguments if we've started streaming this function call
-                    if (state.function_call_streaming.get(tc_delta.index, False) and
-                        tc_function and
-                        tc_function.arguments):
-
+                    if (
+                        state.function_call_streaming.get(tc_delta.index, False)
+                        and tc_function
+                        and tc_function.arguments
+                    ):
                         output_index = state.function_call_output_idx[tc_delta.index]
                         yield ResponseFunctionCallArgumentsDeltaEvent(
                             delta=tc_function.arguments,

agents/realtime/__init__.py

@@ -47,6 +47,8 @@ from .model import (
     RealtimeModel,
     RealtimeModelConfig,
     RealtimeModelListener,
+    RealtimePlaybackState,
+    RealtimePlaybackTracker,
 )
 from .model_events import (
     RealtimeConnectionStatus,
@@ -139,6 +141,8 @@ __all__ = [
     "RealtimeModel",
     "RealtimeModelConfig",
     "RealtimeModelListener",
+    "RealtimePlaybackTracker",
+    "RealtimePlaybackState",
     # Model Events
     "RealtimeConnectionStatus",
     "RealtimeModelAudioDoneEvent",

agents/realtime/_default_tracker.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ._util import calculate_audio_length_ms
+from .config import RealtimeAudioFormat
+
+
+@dataclass
+class ModelAudioState:
+    initial_received_time: datetime
+    audio_length_ms: float
+
+
+class ModelAudioTracker:
+    def __init__(self) -> None:
+        # (item_id, item_content_index) -> ModelAudioState
+        self._states: dict[tuple[str, int], ModelAudioState] = {}
+        self._last_audio_item: tuple[str, int] | None = None
+
+    def set_audio_format(self, format: RealtimeAudioFormat) -> None:
+        """Called when the model wants to set the audio format."""
+        self._format = format
+
+    def on_audio_delta(self, item_id: str, item_content_index: int, audio_bytes: bytes) -> None:
+        """Called when an audio delta is received from the model."""
+        ms = calculate_audio_length_ms(self._format, audio_bytes)
+        new_key = (item_id, item_content_index)
+
+        self._last_audio_item = new_key
+        if new_key not in self._states:
+            self._states[new_key] = ModelAudioState(datetime.now(), ms)
+        else:
+            self._states[new_key].audio_length_ms += ms
+
+    def on_interrupted(self) -> None:
+        """Called when the audio playback has been interrupted."""
+        self._last_audio_item = None
+
+    def get_state(self, item_id: str, item_content_index: int) -> ModelAudioState | None:
+        """Called when the model wants to get the current playback state."""
+        return self._states.get((item_id, item_content_index))
+
+    def get_last_audio_item(self) -> tuple[str, int] | None:
+        """Called when the model wants to get the last audio item ID and content index."""
+        return self._last_audio_item

agents/realtime/_util.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .config import RealtimeAudioFormat
+
+
+def calculate_audio_length_ms(format: RealtimeAudioFormat | None, audio_bytes: bytes) -> float:
+    if format and format.startswith("g711"):
+        return (len(audio_bytes) / 8000) * 1000
+    return (len(audio_bytes) / 24 / 2) * 1000

agents/realtime/events.py

@@ -115,6 +115,12 @@ class RealtimeAudioEnd:
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_end"] = "audio_end"
 
 
@@ -125,6 +131,12 @@ class RealtimeAudio:
     audio: RealtimeModelAudioEvent
     """The audio event from the model layer."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
 
@@ -140,6 +152,12 @@ class RealtimeAudioInterrupted:
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_interrupted"] = "audio_interrupted"
 
 

agents/realtime/model.py

@@ -6,13 +6,95 @@ from typing import Callable
 from typing_extensions import NotRequired, TypedDict
 
 from ..util._types import MaybeAwaitable
+from ._util import calculate_audio_length_ms
 from .config import (
+    RealtimeAudioFormat,
     RealtimeSessionModelSettings,
 )
 from .model_events import RealtimeModelEvent
 from .model_inputs import RealtimeModelSendEvent
 
 
+class RealtimePlaybackState(TypedDict):
+    current_item_id: str | None
+    """The item ID of the current item being played."""
+
+    current_item_content_index: int | None
+    """The index of the current item content being played."""
+
+    elapsed_ms: float | None
+    """The number of milliseconds of audio that have been played."""
+
+
+class RealtimePlaybackTracker:
+    """If you have custom playback logic or expect that audio is played with delays or at different
+    speeds, create an instance of RealtimePlaybackTracker and pass it to the session. You are
+    responsible for tracking the audio playback progress and calling `on_play_bytes` or
+    `on_play_ms` when the user has played some audio."""
+
+    def __init__(self) -> None:
+        self._format: RealtimeAudioFormat | None = None
+        # (item_id, item_content_index)
+        self._current_item: tuple[str, int] | None = None
+        self._elapsed_ms: float | None = None
+
+    def on_play_bytes(self, item_id: str, item_content_index: int, bytes: bytes) -> None:
+        """Called by you when you have played some audio.
+
+        Args:
+            item_id: The item ID of the audio being played.
+            item_content_index: The index of the audio content in `item.content`
+            bytes: The audio bytes that have been fully played.
+        """
+        ms = calculate_audio_length_ms(self._format, bytes)
+        self.on_play_ms(item_id, item_content_index, ms)
+
+    def on_play_ms(self, item_id: str, item_content_index: int, ms: float) -> None:
+        """Called by you when you have played some audio.
+
+        Args:
+            item_id: The item ID of the audio being played.
+            item_content_index: The index of the audio content in `item.content`
+            ms: The number of milliseconds of audio that have been played.
+        """
+        if self._current_item != (item_id, item_content_index):
+            self._current_item = (item_id, item_content_index)
+            self._elapsed_ms = ms
+        else:
+            assert self._elapsed_ms is not None
+            self._elapsed_ms += ms
+
+    def on_interrupted(self) -> None:
+        """Called by the model when the audio playback has been interrupted."""
+        self._current_item = None
+        self._elapsed_ms = None
+
+    def set_audio_format(self, format: RealtimeAudioFormat) -> None:
+        """Will be called by the model to set the audio format.
+
+        Args:
+            format: The audio format to use.
+        """
+        self._format = format
+
+    def get_state(self) -> RealtimePlaybackState:
+        """Will be called by the model to get the current playback state."""
+        if self._current_item is None:
+            return {
+                "current_item_id": None,
+                "current_item_content_index": None,
+                "elapsed_ms": None,
+            }
+        assert self._elapsed_ms is not None
+
+        item_id, item_content_index = self._current_item
+        return {
+            "current_item_id": item_id,
+            "current_item_content_index": item_content_index,
+            "elapsed_ms": self._elapsed_ms,
+        }
+
+
 class RealtimeModelListener(abc.ABC):
     """A listener for realtime transport events."""
 
@@ -39,6 +121,18 @@ class RealtimeModelConfig(TypedDict):
     initial_model_settings: NotRequired[RealtimeSessionModelSettings]
     """The initial model settings to use when connecting."""
 
+    playback_tracker: NotRequired[RealtimePlaybackTracker]
+    """The playback tracker to use when tracking audio playback progress. If not set, the model will
+    use a default implementation that assumes audio is played immediately, at realtime speed.
+
+    A playback tracker is useful for interruptions. The model generates audio much faster than
+    realtime playback speed. So if there's an interruption, its useful for the model to know how
+    much of the audio has been played by the user. In low-latency scenarios, it's fine to assume
+    that audio is played back immediately at realtime speed. But in scenarios like phone calls or
+    other remote interactions, you can set a playback tracker that lets the model know when audio
+    is played to the user.
+    """
+
 
 class RealtimeModel(abc.ABC):
     """Interface for connecting to a realtime model and sending/receiving events."""

agents/realtime/model_events.py

@@ -40,6 +40,12 @@ class RealtimeModelAudioEvent:
     data: bytes
     response_id: str
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio"] = "audio"
 
 
@@ -47,6 +53,12 @@ class RealtimeModelAudioEvent:
 class RealtimeModelAudioInterruptedEvent:
     """Audio interrupted."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_interrupted"] = "audio_interrupted"
 
 
@@ -54,6 +66,12 @@ class RealtimeModelAudioInterruptedEvent:
 class RealtimeModelAudioDoneEvent:
     """Audio done."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_done"] = "audio_done"
 
 
@@ -138,6 +156,15 @@ class RealtimeModelExceptionEvent:
     type: Literal["exception"] = "exception"
 
 
+@dataclass
+class RealtimeModelRawServerEvent:
+    """Raw events forwarded from the server."""
+
+    data: Any
+
+    type: Literal["raw_server_event"] = "raw_server_event"
+
+
 # TODO (rm) Add usage events
 
 
@@ -156,4 +183,5 @@ RealtimeModelEvent: TypeAlias = Union[
     RealtimeModelTurnEndedEvent,
     RealtimeModelOtherEvent,
     RealtimeModelExceptionEvent,
+    RealtimeModelRawServerEvent,
 ]

agents/realtime/openai_realtime.py

@@ -57,6 +57,7 @@ from typing_extensions import assert_never
 from websockets.asyncio.client import ClientConnection
 
 from agents.handoffs import Handoff
+from agents.realtime._default_tracker import ModelAudioTracker
 from agents.tool import FunctionTool, Tool
 from agents.util._types import MaybeAwaitable
 
@@ -72,6 +73,8 @@ from .model import (
     RealtimeModel,
     RealtimeModelConfig,
     RealtimeModelListener,
+    RealtimePlaybackState,
+    RealtimePlaybackTracker,
 )
 from .model_events import (
     RealtimeModelAudioDoneEvent,
@@ -83,6 +86,7 @@ from .model_events import (
     RealtimeModelInputAudioTranscriptionCompletedEvent,
     RealtimeModelItemDeletedEvent,
     RealtimeModelItemUpdatedEvent,
+    RealtimeModelRawServerEvent,
     RealtimeModelToolCallEvent,
     RealtimeModelTranscriptDeltaEvent,
     RealtimeModelTurnEndedEvent,
@@ -133,11 +137,11 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         self._websocket_task: asyncio.Task[None] | None = None
         self._listeners: list[RealtimeModelListener] = []
         self._current_item_id: str | None = None
-        self._audio_start_time: datetime | None = None
-        self._audio_length_ms: float = 0.0
+        self._audio_state_tracker: ModelAudioTracker = ModelAudioTracker()
         self._ongoing_response: bool = False
-        self._current_audio_content_index: int | None = None
         self._tracing_config: RealtimeModelTracingConfig | Literal["auto"] | None = None
+        self._playback_tracker: RealtimePlaybackTracker | None = None
+        self._created_session: OpenAISessionObject | None = None
 
     async def connect(self, options: RealtimeModelConfig) -> None:
         """Establish a connection to the model and keep it alive."""
@@ -146,6 +150,8 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
         model_settings: RealtimeSessionModelSettings = options.get("initial_model_settings", {})
 
+        self._playback_tracker = options.get("playback_tracker", RealtimePlaybackTracker())
+
         self.model = model_settings.get("model_name", self.model)
         api_key = await get_api_key(options.get("api_key"))
 
@@ -294,26 +300,69 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         if event.start_response:
             await self._send_raw_message(OpenAIResponseCreateEvent(type="response.create"))
 
+    def _get_playback_state(self) -> RealtimePlaybackState:
+        if self._playback_tracker:
+            return self._playback_tracker.get_state()
+
+        if last_audio_item_id := self._audio_state_tracker.get_last_audio_item():
+            item_id, item_content_index = last_audio_item_id
+            audio_state = self._audio_state_tracker.get_state(item_id, item_content_index)
+            if audio_state:
+                elapsed_ms = (
+                    datetime.now() - audio_state.initial_received_time
+                ).total_seconds() * 1000
+                return {
+                    "current_item_id": item_id,
+                    "current_item_content_index": item_content_index,
+                    "elapsed_ms": elapsed_ms,
+                }
+
+        return {
+            "current_item_id": None,
+            "current_item_content_index": None,
+            "elapsed_ms": None,
+        }
+
     async def _send_interrupt(self, event: RealtimeModelSendInterrupt) -> None:
-        if not self._current_item_id or not self._audio_start_time:
+        playback_state = self._get_playback_state()
+        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.info(
+                "Skipping interrupt. "
+                f"Item id: {current_item_id}, "
+                f"elapsed ms: {elapsed_ms}, "
+                f"content index: {current_item_content_index}"
+            )
             return
 
-        await self._cancel_response()
-
-        elapsed_time_ms = (datetime.now() - self._audio_start_time).total_seconds() * 1000
-        if elapsed_time_ms > 0 and elapsed_time_ms < self._audio_length_ms:
-            await self._emit_event(RealtimeModelAudioInterruptedEvent())
+        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(
-                self._current_item_id,
-                self._current_audio_content_index or 0,
-                int(elapsed_time_ms),
+                current_item_id,
+                current_item_content_index,
+                int(elapsed_ms),
             )
             await self._send_raw_message(converted)
 
-        self._current_item_id = None
-        self._audio_start_time = None
-        self._audio_length_ms = 0.0
-        self._current_audio_content_index = None
+        automatic_response_cancellation_enabled = (
+            self._created_session
+            and self._created_session.turn_detection
+            and self._created_session.turn_detection.interrupt_response
+        )
+        if not automatic_response_cancellation_enabled:
+            await self._cancel_response()
+
+        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."""
@@ -321,23 +370,21 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
     async def _handle_audio_delta(self, parsed: ResponseAudioDeltaEvent) -> None:
         """Handle audio delta events and update audio tracking state."""
-        self._current_audio_content_index = parsed.content_index
         self._current_item_id = parsed.item_id
-        if self._audio_start_time is None:
-            self._audio_start_time = datetime.now()
-            self._audio_length_ms = 0.0
 
         audio_bytes = base64.b64decode(parsed.delta)
-        # Calculate audio length in ms using 24KHz pcm16le
-        self._audio_length_ms += self._calculate_audio_length_ms(audio_bytes)
+
+        self._audio_state_tracker.on_audio_delta(parsed.item_id, parsed.content_index, audio_bytes)
+
         await self._emit_event(
-            RealtimeModelAudioEvent(data=audio_bytes, response_id=parsed.response_id)
+            RealtimeModelAudioEvent(
+                data=audio_bytes,
+                response_id=parsed.response_id,
+                item_id=parsed.item_id,
+                content_index=parsed.content_index,
+            )
         )
 
-    def _calculate_audio_length_ms(self, audio_bytes: bytes) -> float:
-        """Calculate audio length in milliseconds for 24KHz PCM16LE format."""
-        return len(audio_bytes) / 24 / 2
-
     async def _handle_output_item(self, item: ConversationItem) -> None:
         """Handle response output item events (function calls and messages)."""
         if item.type == "function_call" and item.status == "completed":
@@ -401,6 +448,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             self._ongoing_response = False
 
     async def _handle_ws_event(self, event: dict[str, Any]):
+        await self._emit_event(RealtimeModelRawServerEvent(data=event))
         try:
             if "previous_item_id" in event and event["previous_item_id"] is None:
                 event["previous_item_id"] = ""  # TODO (rm) remove
@@ -429,7 +477,12 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         if parsed.type == "response.audio.delta":
             await self._handle_audio_delta(parsed)
         elif parsed.type == "response.audio.done":
-            await self._emit_event(RealtimeModelAudioDoneEvent())
+            await self._emit_event(
+                RealtimeModelAudioDoneEvent(
+                    item_id=parsed.item_id,
+                    content_index=parsed.content_index,
+                )
+            )
         elif parsed.type == "input_audio_buffer.speech_started":
             await self._send_interrupt(RealtimeModelSendInterrupt())
         elif parsed.type == "response.created":
@@ -440,6 +493,9 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             await self._emit_event(RealtimeModelTurnEndedEvent())
         elif parsed.type == "session.created":
             await self._send_tracing_config(self._tracing_config)
+            self._update_created_session(parsed.session)  # type: ignore
+        elif parsed.type == "session.updated":
+            self._update_created_session(parsed.session)  # type: ignore
         elif parsed.type == "error":
             await self._emit_event(RealtimeModelErrorEvent(error=parsed.error))
         elif parsed.type == "conversation.item.deleted":
@@ -489,6 +545,13 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         ):
             await self._handle_output_item(parsed.item)
 
+    def _update_created_session(self, session: OpenAISessionObject) -> None:
+        self._created_session = session
+        if session.output_audio_format:
+            self._audio_state_tracker.set_audio_format(session.output_audio_format)
+            if self._playback_tracker:
+                self._playback_tracker.set_audio_format(session.output_audio_format)
+
     async def _update_session_config(self, model_settings: RealtimeSessionModelSettings) -> None:
         session_config = self._get_session_config(model_settings)
         await self._send_raw_message(

agents/realtime/session.py

@@ -188,11 +188,26 @@ class RealtimeSession(RealtimeModelListener):
         elif event.type == "function_call":
             await self._handle_tool_call(event)
         elif event.type == "audio":
-            await self._put_event(RealtimeAudio(info=self._event_info, audio=event))
+            await self._put_event(
+                RealtimeAudio(
+                    info=self._event_info,
+                    audio=event,
+                    item_id=event.item_id,
+                    content_index=event.content_index,
+                )
+            )
         elif event.type == "audio_interrupted":
-            await self._put_event(RealtimeAudioInterrupted(info=self._event_info))
+            await self._put_event(
+                RealtimeAudioInterrupted(
+                    info=self._event_info, item_id=event.item_id, content_index=event.content_index
+                )
+            )
         elif event.type == "audio_done":
-            await self._put_event(RealtimeAudioEnd(info=self._event_info))
+            await self._put_event(
+                RealtimeAudioEnd(
+                    info=self._event_info, item_id=event.item_id, content_index=event.content_index
+                )
+            )
         elif event.type == "input_audio_transcription_completed":
             self._history = RealtimeSession._get_new_history(self._history, event)
             await self._put_event(
@@ -259,6 +274,8 @@ class RealtimeSession(RealtimeModelListener):
             self._stored_exception = event.exception
         elif event.type == "other":
             pass
+        elif event.type == "raw_server_event":
+            pass
         else:
             assert_never(event)
 

agents/tracing/create.py

@@ -50,8 +50,7 @@ def trace(
         group_id: Optional grouping identifier to link multiple traces from the same conversation
             or process. For instance, you might use a chat thread ID.
         metadata: Optional dictionary of additional metadata to attach to the trace.
-        disabled: If True, we will return a Trace but the Trace will not be recorded. This will
-            not be checked if there's an existing trace and `even_if_trace_running` is True.
+        disabled: If True, we will return a Trace but the Trace will not be recorded.
 
     Returns:
         The newly created trace object.

agents/tracing/processors.py

@@ -22,7 +22,7 @@ class ConsoleSpanExporter(TracingExporter):
     def export(self, items: list[Trace | Span[Any]]) -> None:
         for item in items:
             if isinstance(item, Trace):
-                print(f"[Exporter] Export trace_id={item.trace_id}, name={item.name}, ")
+                print(f"[Exporter] Export trace_id={item.trace_id}, name={item.name}")
             else:
                 print(f"[Exporter] Export span: {item.export()}")
 
@@ -121,7 +121,7 @@ class BackendSpanExporter(TracingExporter):
                     logger.debug(f"Exported {len(items)} items")
                     return
 
-                # If the response is a client error (4xx), we wont retry
+                # If the response is a client error (4xx), we won't retry
                 if 400 <= response.status_code < 500:
                     logger.error(
                         f"[non-fatal] Tracing client error {response.status_code}: {response.text}"
@@ -183,7 +183,7 @@ class BatchTraceProcessor(TracingProcessor):
         self._shutdown_event = threading.Event()
 
         # The queue size threshold at which we export immediately.
-        self._export_trigger_size = int(max_queue_size * export_trigger_ratio)
+        self._export_trigger_size = max(1, int(max_queue_size * export_trigger_ratio))
 
         # Track when we next *must* perform a scheduled export
         self._next_export_time = time.time() + self._schedule_delay
@@ -269,8 +269,7 @@ class BatchTraceProcessor(TracingProcessor):
 
     def _export_batches(self, force: bool = False):
         """Drains the queue and exports in batches. If force=True, export everything.
-        Otherwise, export up to `max_batch_size` repeatedly until the queue is empty or below a
-        certain threshold.
+        Otherwise, export up to `max_batch_size` repeatedly until the queue is completely empty.
         """
         while True:
             items_to_export: list[Span[Any] | Trace] = []

agents/tracing/traces.py

@@ -10,7 +10,7 @@ from .processor_interface import TracingProcessor
 from .scope import Scope
 
 
-class Trace:
+class Trace(abc.ABC):
     """
     A trace is the root level object that tracing creates. It represents a logical "workflow".
     """

{openai_agents-0.2.3.dist-info → openai_agents-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.2.3
+Version: 0.2.4
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -21,7 +21,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
 Requires-Dist: mcp<2,>=1.11.0; python_version >= '3.10'
-Requires-Dist: openai<2,>=1.96.1
+Requires-Dist: openai<2,>=1.97.1
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0
@@ -338,6 +338,7 @@ make format-check # run style checker
 We'd like to acknowledge the excellent work of the open-source community, especially:
 
 -   [Pydantic](https://docs.pydantic.dev/latest/) (data validation) and [PydanticAI](https://ai.pydantic.dev/) (advanced agent framework)
+-   [LiteLLM](https://github.com/BerriAI/litellm) (unified interface for 100+ LLMs)
 -   [MkDocs](https://github.com/squidfunk/mkdocs-material)
 -   [Griffe](https://github.com/mkdocstrings/griffe)
 -   [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff)

{openai_agents-0.2.3.dist-info → openai_agents-0.2.4.dist-info}/RECORD

@@ -2,12 +2,12 @@ agents/__init__.py,sha256=KO_SBzwwg7cXPvMNDD1_lRhFIVR6E2RmyU624sAEEVo,7781
 agents/_config.py,sha256=ANrM7GP2VSQehDkMc9qocxkUlPwqU-i5sieMJyEwxpM,796
 agents/_debug.py,sha256=7OKys2lDjeCtGggTkM53m_8vw0WIr3yt-_JPBDAnsw0,608
 agents/_run_impl.py,sha256=LlUM0YqZWmqz4WoWu0YK1Du6k09TX-ot94sikM16Y4U,44507
-agents/agent.py,sha256=eWtYqVJHz3ol3SoLZm132_sJ46dF5DEKQ8aV8KgDv2E,13381
-agents/agent_output.py,sha256=bHItis02dw-issbxjB4VnjUFdSByM9OR26rzxsFOSnQ,7154
+agents/agent.py,sha256=Hn6O16BQ4jWG_qBx2PiIBvBr0BlwEf4AivK76fe61Gw,12184
+agents/agent_output.py,sha256=teTFK8unUN3esXhmEBO0bQGYQm1Axd5rYleDt9TFDgw,7153
 agents/computer.py,sha256=XD44UgiUWSfniv-xKwwDP6wFKVwBiZkpaL1hO-0-7ZA,2516
 agents/exceptions.py,sha256=NHMdHE0cZ6AdA6UgUylTzVHAX05Ol1CkO814a0FdZcs,2862
-agents/function_schema.py,sha256=JvMh356N60_c3hj7BXySuM7eqVwP00jealR7rdPnl60,13590
-agents/guardrail.py,sha256=kanNTh1OqSpzFH6QyNfucLDYHbBnvq3u-kWnFJw4lD8,9571
+agents/function_schema.py,sha256=yZ3PEOmfy836Me_W4QlItMeFq2j4BtpuI2FmQswbIcQ,13590
+agents/guardrail.py,sha256=7P-kd9rKPhgB8rtI31MCV5ho4ZrEaNCQxHvE8IK3EOk,9582
 agents/handoffs.py,sha256=L-b2eMNKyi-uF5Isz7UfpKc2Amvqies3i5tVjDnM3M4,10793
 agents/items.py,sha256=ZKc4aOBearYF4ItT9qtmehUUt9aS-3D0kVA3reoV1mU,9732
 agents/lifecycle.py,sha256=C1LSoCa_0zf0nt7yI3SKL5bAAG4Cso6--Gmk8S8zpJg,3111
@@ -30,7 +30,7 @@ agents/extensions/handoff_filters.py,sha256=2cXxu1JROez96CpTiGuT9PIuaIrIE8ksP01f
 agents/extensions/handoff_prompt.py,sha256=oGWN0uNh3Z1L7E-Ev2up8W084fFrDNOsLDy7P6bcmic,1006
 agents/extensions/visualization.py,sha256=g2eEwW22qe3A4WtH37LwaHhK3QZE9FYHVw9IcOVpwbk,4699
 agents/extensions/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-agents/extensions/models/litellm_model.py,sha256=Gmk7M4KGZ-Mfk2LUCzHL-FMm5C6_n41QzwSMVxYcfE8,15014
+agents/extensions/models/litellm_model.py,sha256=TWd57pzGJGpyvrBstqiFsPHlUFnExw1muchGGBA2jJc,15437
 agents/extensions/models/litellm_provider.py,sha256=wTm00Anq8YoNb9AnyT0JOunDG-HCDm_98ORNy7aNJdw,928
 agents/mcp/__init__.py,sha256=yHmmYlrmEHzUas1inRLKL2iPqbb_-107G3gKe_tyg4I,750
 agents/mcp/server.py,sha256=mTXQL4om5oA2fYevk63SUlwDri-RcUleUH_4hFrA0QM,24266
@@ -39,9 +39,9 @@ agents/memory/__init__.py,sha256=bo2Rb3PqwSCo9PhBVVJOjvjMM1TfytuDPAFEDADYwwA,84
 agents/memory/session.py,sha256=9RQ1I7qGh_9DzsyUd9srSPrxRBlw7jks-67NxYqKvvs,13060
 agents/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agents/models/_openai_shared.py,sha256=4Ngwo2Fv2RXY61Pqck1cYPkSln2tDnb8Ai-ao4QG-iE,836
-agents/models/chatcmpl_converter.py,sha256=lHVmWOxULJd_Q9WnWdh_ZYYRq07-4UNfpl7KDZEGZdg,19420
+agents/models/chatcmpl_converter.py,sha256=m05aOXzO9y23qO3u2-7pHWZ7rdIWQZfckI2KACdIOUY,19829
 agents/models/chatcmpl_helpers.py,sha256=eIWySobaH7I0AQijAz5i-_rtsXrSvmEHD567s_8Zw1o,1318
-agents/models/chatcmpl_stream_handler.py,sha256=3tbGS-mCOVUz9lLbm35rFxC8piYDsWqIJ8DCPE1DjuQ,23999
+agents/models/chatcmpl_stream_handler.py,sha256=XUoMnNEcSqK6IRMI6GPH8CwMCXi6NhbfHfpCY3SXJOM,24124
 agents/models/fake_id.py,sha256=lbXjUUSMeAQ8eFx4V5QLUnBClHE6adJlYYav55RlG5w,268
 agents/models/interface.py,sha256=TpY_GEk3LLMozCcYAEcC-Y_VRpI3pwE7A7ZM317mk7M,3839
 agents/models/multi_provider.py,sha256=aiDbls5G4YomPfN6qH1pGlj41WS5jlDp2T82zm6qcnM,5578
@@ -49,29 +49,31 @@ agents/models/openai_chatcompletions.py,sha256=Br7nWsibVvMr0jff6H6adpe_AjYTgLgoA
 agents/models/openai_provider.py,sha256=NMxTNaoTa329GrA7jj51LC02pb_e2eFh-PCvWADJrkY,3478
 agents/models/openai_responses.py,sha256=IaZ419gGkx8cWDZxi_2djvAor3RoUUiAdid782WOyv0,16720
 agents/realtime/README.md,sha256=5YCYXH5ULmlWoWo1PE9TlbHjeYgjnp-xY8ZssSFY2Vk,126
-agents/realtime/__init__.py,sha256=MPdn2EXsjP1WX-iGaQm94Yw_j8xNm-KcO-vdHhm0sCw,4807
+agents/realtime/__init__.py,sha256=7qvzK8QJuHRnPHxDgDj21v8-lnSN4Uurg9znwJv_Tqg,4923
+agents/realtime/_default_tracker.py,sha256=4OMxBvD1MnZmMn6JZYKL42uWhVzvK6NdDLDfPP54d78,1765
+agents/realtime/_util.py,sha256=uawurhWKi3_twNFcZ5Yn1mVvv0RKl4IoyCSag8hGxrE,313
 agents/realtime/agent.py,sha256=xVQYVJjsbi4FpJZ8jwogfKUsguOzpWXWih6rqLZ8AgE,3745
 agents/realtime/config.py,sha256=O7EGQgHrv2p0gtvZfODwSb4g1RJXkJ2ySH1YdNLt_K8,5751
-agents/realtime/events.py,sha256=bOyO7Yv0g_6StXKqAzapNTOq8GdaOuQqj3BbtXNfHU4,5090
+agents/realtime/events.py,sha256=YnyXmkc2rkIAcCDoW5yxylMYeXeaq_QTlyRR5u5VsaM,5534
 agents/realtime/handoffs.py,sha256=avLFix5kEutel57IRcddssGiVHzGptOzWL9OqPaLVh8,6702
 agents/realtime/items.py,sha256=psT6AH65qmngmPsgwk6CXacVo5tEDYq0Za3EitHFpTA,5052
-agents/realtime/model.py,sha256=YwMBwtj33Z6uADnz1AoYg4wSfmpfYdZNq7ZaK8hlekw,2188
-agents/realtime/model_events.py,sha256=JDh70uDctVuwex5EiYUdWhqQvBarN3ge7eREd1aUznU,3386
+agents/realtime/model.py,sha256=RJBA8-Dkd2JTqGzbKacoX4dN_qTWn_p7npL73To3ymw,6143
+agents/realtime/model_events.py,sha256=X7UrUU_g4u5gWaf2mUesJJ-Ik1Z1QE0Z-ZP7kDmX1t0,4034
 agents/realtime/model_inputs.py,sha256=OW2bn3wD5_pXLunDUf35jhG2q_bTKbC_D7Qu-83aOEA,2243
-agents/realtime/openai_realtime.py,sha256=dvy07idciGl8E0swuvmgtHYf7DUSitHrwImAiG_VFq0,27323
+agents/realtime/openai_realtime.py,sha256=wuZ4AFWpgpX76pCgxmt87-Oz738IgxbdF3wqMODaZUI,29817
 agents/realtime/runner.py,sha256=KfU7utmc9QFH2htIKN2IN9H-5EnB0qN9ezmvlRTnOm4,2511
-agents/realtime/session.py,sha256=jMOYmv3KcszBLLPcYkW_ChNiOblyoiGiYZ9jE6WUNEU,21908
+agents/realtime/session.py,sha256=WokpD9EfYacdVpiufWGdtNTDxPUZJxtPjbDfmWlJ40M,22411
 agents/tracing/__init__.py,sha256=5HO_6na5S6EwICgwl50OMtxiIIosUrqalhvldlYvSVc,2991
-agents/tracing/create.py,sha256=Gm9N5O2DeBy6UU86tRN0wnmzWyXb-qAUBbTj9oxIHao,18106
+agents/tracing/create.py,sha256=xpJ4ZRnGyUDPKoVVkA_8hmdhtwOKGhSkwRco2AQIhAo,18003
 agents/tracing/logger.py,sha256=J4KUDRSGa7x5UVfUwWe-gbKwoaq8AeETRqkPt3QvtGg,68
 agents/tracing/processor_interface.py,sha256=e1mWcIAoQFHID1BapcrAZ6MxZg98bPVYgbOPclVoCXc,1660
-agents/tracing/processors.py,sha256=lOdZHwo0rQAflVkKWOZinnWyLtS0stALyydiFOC0gss,11389
+agents/tracing/processors.py,sha256=hgFMnN9QP03UcIx6rkeaWa7rfPeVQ0K1rvUc7m84NVY,11370
 agents/tracing/provider.py,sha256=hiMTAiVnmnZ2RW6HYvL1hckXE-GQEqTSRvZCVcBY7pI,9212
 agents/tracing/scope.py,sha256=u17_m8RPpGvbHrTkaO_kDi5ROBWhfOAIgBe7suiaRD4,1445
 agents/tracing/setup.py,sha256=2h9TH1GAKcXKM1U99dOKKR3XlHp8JKzh2JG3DQPKyhY,612
 agents/tracing/span_data.py,sha256=nI2Fbu1ORE8ybE6m6RuddTJF5E5xFmEj8Mq5bSFv4bE,9017
 agents/tracing/spans.py,sha256=6vVzocGMsdgIma1ksqkBZmhar91xj4RpgcpUC3iibqg,6606
-agents/tracing/traces.py,sha256=G5LlECSK-DBRFP-bjT8maZjBQulz6SaHILYauUVlfq8,4775
+agents/tracing/traces.py,sha256=EU5KNlNOTC9GFBls5ONDA0FkaUdLrM6y-cLK5953kqE,4784
 agents/tracing/util.py,sha256=J7IZgVDmeW0aZDw8LBSjBKrlQbcOmaqZE7XQjolPwi8,490
 agents/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agents/util/_coro.py,sha256=S38XUYFC7bqTELSgMUBsAX1GoRlIrV7coupcUAWH__4,45
@@ -95,7 +97,7 @@ agents/voice/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 agents/voice/models/openai_model_provider.py,sha256=Khn0uT-VhsEbe7_OhBMGFQzXNwL80gcWZyTHl3CaBII,3587
 agents/voice/models/openai_stt.py,sha256=LcVDS7f1pmbm--PWX-IaV9uLg9uv5_L3vSCbVnTJeGs,16864
 agents/voice/models/openai_tts.py,sha256=4KoLQuFDHKu5a1VTJlu9Nj3MHwMlrn9wfT_liJDJ2dw,1477
-openai_agents-0.2.3.dist-info/METADATA,sha256=XtY_daBoaLEGJdzn0ZX53F2vL78SYYTQTsTfZLgzOIM,11567
-openai_agents-0.2.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-openai_agents-0.2.3.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
-openai_agents-0.2.3.dist-info/RECORD,,
+openai_agents-0.2.4.dist-info/METADATA,sha256=EE1UoLLCNOh6Moihq8sUzWj0ACABNZiDOqYhdF8EcH4,11651
+openai_agents-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openai_agents-0.2.4.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
+openai_agents-0.2.4.dist-info/RECORD,,