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

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", None)
+
         self.model = model_settings.get("model_name", self.model)
         api_key = await get_api_key(options.get("api_key"))
 
@@ -220,7 +226,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
         except websockets.exceptions.ConnectionClosedOK:
             # Normal connection closure - no exception event needed
-            logger.info("WebSocket connection closed normally")
+            logger.debug("WebSocket connection closed normally")
         except websockets.exceptions.ConnectionClosed as e:
             await self._emit_event(
                 RealtimeModelExceptionEvent(
@@ -294,26 +300,76 @@ 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.debug(
+                "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)
+        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}"
+            )
+
+        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._current_item_id = None
-        self._audio_start_time = None
-        self._audio_length_ms = 0.0
-        self._current_audio_content_index = 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."""
@@ -321,23 +377,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 +455,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 +484,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 +500,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 +552,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(
@@ -506,6 +576,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                 or DEFAULT_MODEL_SETTINGS.get("model_name")
             ),
             voice=model_settings.get("voice", DEFAULT_MODEL_SETTINGS.get("voice")),
+            speed=model_settings.get("speed", None),
             modalities=model_settings.get("modalities", DEFAULT_MODEL_SETTINGS.get("modalities")),
             input_audio_format=model_settings.get(
                 "input_audio_format",

agents/realtime/session.py

@@ -180,6 +180,19 @@ class RealtimeSession(RealtimeModelListener):
         """Interrupt the model."""
         await self._model.send_event(RealtimeModelSendInterrupt())
 
+    async def update_agent(self, agent: RealtimeAgent) -> None:
+        """Update the active agent for this session and apply its settings to the model."""
+        self._current_agent = agent
+
+        updated_settings = await self._get_updated_model_settings_from_agent(
+            starting_settings=None,
+            agent=self._current_agent,
+        )
+
+        await self._model.send_event(
+            RealtimeModelSendSessionUpdate(session_settings=updated_settings)
+        )
+
     async def on_event(self, event: RealtimeModelEvent) -> None:
         await self._put_event(RealtimeRawModelEvent(data=event, info=self._event_info))
 
@@ -188,11 +201,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 +287,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)
 
@@ -344,19 +374,20 @@ class RealtimeSession(RealtimeModelListener):
                 )
             )
 
-            # Send tool output to complete the handoff
+            # First, send the session update so the model receives the new instructions
+            await self._model.send_event(
+                RealtimeModelSendSessionUpdate(session_settings=updated_settings)
+            )
+
+            # Then send tool output to complete the handoff (this triggers a new response)
+            transfer_message = handoff.get_transfer_message(result)
             await self._model.send_event(
                 RealtimeModelSendToolOutput(
                     tool_call=event,
-                    output=f"Handed off to {self._current_agent.name}",
+                    output=transfer_message,
                     start_response=True,
                 )
             )
-
-            # Send session update to model
-            await self._model.send_event(
-                RealtimeModelSendSessionUpdate(session_settings=updated_settings)
-            )
         else:
             raise ModelBehaviorError(f"Tool {event.name} not found")
 

agents/run.py

@@ -904,10 +904,9 @@ class AgentRunner:
             raise ModelBehaviorError("Model did not produce a final response!")
 
         # 3. Now, we can process the turn as we do in the non-streaming case
-        single_step_result = await cls._get_single_step_result_from_response(
+        return await cls._get_single_step_result_from_streamed_response(
             agent=agent,
-            original_input=streamed_result.input,
-            pre_step_items=streamed_result.new_items,
+            streamed_result=streamed_result,
             new_response=final_response,
             output_schema=output_schema,
             all_tools=all_tools,
@@ -918,9 +917,6 @@ class AgentRunner:
             tool_use_tracker=tool_use_tracker,
         )
 
-        RunImpl.stream_step_result_to_queue(single_step_result, streamed_result._event_queue)
-        return single_step_result
-
     @classmethod
     async def _run_single_turn(
         cls,
@@ -1023,6 +1019,57 @@ class AgentRunner:
             run_config=run_config,
         )
 
+    @classmethod
+    async def _get_single_step_result_from_streamed_response(
+        cls,
+        *,
+        agent: Agent[TContext],
+        all_tools: list[Tool],
+        streamed_result: RunResultStreaming,
+        new_response: ModelResponse,
+        output_schema: AgentOutputSchemaBase | None,
+        handoffs: list[Handoff],
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        run_config: RunConfig,
+        tool_use_tracker: AgentToolUseTracker,
+    ) -> SingleStepResult:
+
+        original_input = streamed_result.input
+        pre_step_items = streamed_result.new_items
+        event_queue = streamed_result._event_queue
+
+        processed_response = RunImpl.process_model_response(
+            agent=agent,
+            all_tools=all_tools,
+            response=new_response,
+            output_schema=output_schema,
+            handoffs=handoffs,
+        )
+        new_items_processed_response = processed_response.new_items
+        tool_use_tracker.add_tool_use(agent, processed_response.tools_used)
+        RunImpl.stream_step_items_to_queue(new_items_processed_response, event_queue)
+
+        single_step_result = await RunImpl.execute_tools_and_side_effects(
+            agent=agent,
+            original_input=original_input,
+            pre_step_items=pre_step_items,
+            new_response=new_response,
+            processed_response=processed_response,
+            output_schema=output_schema,
+            hooks=hooks,
+            context_wrapper=context_wrapper,
+            run_config=run_config,
+        )
+        new_step_items = [
+            item
+            for item in single_step_result.new_step_items
+            if item not in new_items_processed_response
+        ]
+        RunImpl.stream_step_items_to_queue(new_step_items, event_queue)
+
+        return single_step_result
+
     @classmethod
     async def _run_input_guardrails(
         cls,

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()}")
 
@@ -69,9 +69,12 @@ class BackendSpanExporter(TracingExporter):
             api_key: The OpenAI API key to use. This is the same key used by the OpenAI Python
                 client.
         """
-        # We're specifically setting the underlying cached property as well
+        # Clear the cached property if it exists
+        if 'api_key' in self.__dict__:
+            del self.__dict__['api_key']
+
+        # Update the private attribute
         self._api_key = api_key
-        self.api_key = api_key
 
     @cached_property
     def api_key(self):
@@ -121,7 +124,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 +186,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 +272,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] = []