openai-agents 0.2.8__py3-none-any.whl → 0.2.10__py3-none-any.whl

agents/models/openai_responses.py

@@ -14,7 +14,6 @@ from openai.types.responses import (
     ResponseStreamEvent,
     ResponseTextConfigParam,
     ToolParam,
-    WebSearchToolParam,
     response_create_params,
 )
 from openai.types.responses.response_prompt_param import ResponsePromptParam
@@ -75,7 +74,8 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         prompt: ResponsePromptParam | None = None,
     ) -> ModelResponse:
         with response_span(disabled=tracing.is_disabled()) as span_response:
@@ -87,7 +87,8 @@ class OpenAIResponsesModel(Model):
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=False,
                     prompt=prompt,
                 )
@@ -150,7 +151,8 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncIterator[ResponseStreamEvent]:
         """
@@ -165,7 +167,8 @@ class OpenAIResponsesModel(Model):
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=True,
                     prompt=prompt,
                 )
@@ -203,6 +206,7 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         previous_response_id: str | None,
+        conversation_id: str | None,
         stream: Literal[True],
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncStream[ResponseStreamEvent]: ...
@@ -217,6 +221,7 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         previous_response_id: str | None,
+        conversation_id: str | None,
         stream: Literal[False],
         prompt: ResponsePromptParam | None = None,
     ) -> Response: ...
@@ -229,7 +234,8 @@ class OpenAIResponsesModel(Model):
         tools: list[Tool],
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         stream: Literal[True] | Literal[False] = False,
         prompt: ResponsePromptParam | None = None,
     ) -> Response | AsyncStream[ResponseStreamEvent]:
@@ -265,6 +271,7 @@ class OpenAIResponsesModel(Model):
                 f"Tool choice: {tool_choice}\n"
                 f"Response format: {response_format}\n"
                 f"Previous response id: {previous_response_id}\n"
+                f"Conversation id: {conversation_id}\n"
             )
 
         extra_args = dict(model_settings.extra_args or {})
@@ -278,6 +285,7 @@ class OpenAIResponsesModel(Model):
 
         return await self._client.responses.create(
             previous_response_id=self._non_null_or_not_given(previous_response_id),
+            conversation=self._non_null_or_not_given(conversation_id),
             instructions=self._non_null_or_not_given(system_instructions),
             model=self.model,
             input=list_input,
@@ -336,6 +344,11 @@ class Converter:
             return {
                 "type": "file_search",
             }
+        elif tool_choice == "web_search":
+            return {
+                # TODO: revist the type: ignore comment when ToolChoice is updated in the future
+                "type": "web_search",  # type: ignore [typeddict-item]
+            }
         elif tool_choice == "web_search_preview":
             return {
                 "type": "web_search_preview",
@@ -416,12 +429,13 @@ class Converter:
             }
             includes: ResponseIncludable | None = None
         elif isinstance(tool, WebSearchTool):
-            ws: WebSearchToolParam = {
-                "type": "web_search_preview",
-                "user_location": tool.user_location,
+            # TODO: revist the type: ignore comment when ToolParam is updated in the future
+            converted_tool = {
+                "type": "web_search",
+                "filters": tool.filters.model_dump() if tool.filters is not None else None,  # type: ignore [typeddict-item]
+                "user_location": tool.user_location,  # type: ignore [typeddict-item]
                 "search_context_size": tool.search_context_size,
             }
-            converted_tool = ws
             includes = None
         elif isinstance(tool, FileSearchTool):
             converted_tool = {

agents/realtime/config.py

@@ -78,6 +78,9 @@ class RealtimeTurnDetectionConfig(TypedDict):
     threshold: NotRequired[float]
     """The threshold for voice activity detection."""
 
+    idle_timeout_ms: NotRequired[int]
+    """Threshold for server-vad to trigger a response if the user is idle for this duration."""
+
 
 class RealtimeSessionModelSettings(TypedDict):
     """Model settings for a realtime model session."""

agents/realtime/events.py

@@ -216,6 +216,16 @@ class RealtimeGuardrailTripped:
     type: Literal["guardrail_tripped"] = "guardrail_tripped"
 
 
+@dataclass
+class RealtimeInputAudioTimeoutTriggered:
+    """Called when the model detects a period of inactivity/silence from the user."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["input_audio_timeout_triggered"] = "input_audio_timeout_triggered"
+
+
 RealtimeSessionEvent: TypeAlias = Union[
     RealtimeAgentStartEvent,
     RealtimeAgentEndEvent,
@@ -230,5 +240,6 @@ RealtimeSessionEvent: TypeAlias = Union[
     RealtimeHistoryUpdated,
     RealtimeHistoryAdded,
     RealtimeGuardrailTripped,
+    RealtimeInputAudioTimeoutTriggered,
 ]
 """An event emitted by the realtime session."""

agents/realtime/model_events.py

@@ -84,6 +84,15 @@ class RealtimeModelInputAudioTranscriptionCompletedEvent:
 
     type: Literal["input_audio_transcription_completed"] = "input_audio_transcription_completed"
 
+@dataclass
+class RealtimeModelInputAudioTimeoutTriggeredEvent:
+    """Input audio timeout triggered."""
+
+    item_id: str
+    audio_start_ms: int
+    audio_end_ms: int
+
+    type: Literal["input_audio_timeout_triggered"] = "input_audio_timeout_triggered"
 
 @dataclass
 class RealtimeModelTranscriptDeltaEvent:
@@ -174,6 +183,7 @@ RealtimeModelEvent: TypeAlias = Union[
     RealtimeModelAudioEvent,
     RealtimeModelAudioInterruptedEvent,
     RealtimeModelAudioDoneEvent,
+    RealtimeModelInputAudioTimeoutTriggeredEvent,
     RealtimeModelInputAudioTranscriptionCompletedEvent,
     RealtimeModelTranscriptDeltaEvent,
     RealtimeModelItemUpdatedEvent,

agents/realtime/openai_realtime.py

@@ -6,7 +6,7 @@ import inspect
 import json
 import os
 from datetime import datetime
-from typing import Any, Callable, Literal
+from typing import Annotated, Any, Callable, Literal, Union
 
 import pydantic
 import websockets
@@ -52,7 +52,7 @@ from openai.types.beta.realtime.session_update_event import (
     SessionTracingTracingConfiguration as OpenAISessionTracingConfiguration,
     SessionUpdateEvent as OpenAISessionUpdateEvent,
 )
-from pydantic import TypeAdapter
+from pydantic import BaseModel, Field, TypeAdapter
 from typing_extensions import assert_never
 from websockets.asyncio.client import ClientConnection
 
@@ -83,6 +83,7 @@ from .model_events import (
     RealtimeModelErrorEvent,
     RealtimeModelEvent,
     RealtimeModelExceptionEvent,
+    RealtimeModelInputAudioTimeoutTriggeredEvent,
     RealtimeModelInputAudioTranscriptionCompletedEvent,
     RealtimeModelItemDeletedEvent,
     RealtimeModelItemUpdatedEvent,
@@ -128,6 +129,32 @@ async def get_api_key(key: str | Callable[[], MaybeAwaitable[str]] | None) -> st
     return os.getenv("OPENAI_API_KEY")
 
 
+class _InputAudioBufferTimeoutTriggeredEvent(BaseModel):
+    type: Literal["input_audio_buffer.timeout_triggered"]
+    event_id: str
+    audio_start_ms: int
+    audio_end_ms: int
+    item_id: str
+
+
+AllRealtimeServerEvents = Annotated[
+    Union[
+        OpenAIRealtimeServerEvent,
+        _InputAudioBufferTimeoutTriggeredEvent,
+    ],
+    Field(discriminator="type"),
+]
+
+ServerEventTypeAdapter: TypeAdapter[AllRealtimeServerEvents] | None = None
+
+
+def get_server_event_type_adapter() -> TypeAdapter[AllRealtimeServerEvents]:
+    global ServerEventTypeAdapter
+    if not ServerEventTypeAdapter:
+        ServerEventTypeAdapter = TypeAdapter(AllRealtimeServerEvents)
+    return ServerEventTypeAdapter
+
+
 class OpenAIRealtimeWebSocketModel(RealtimeModel):
     """A model that uses OpenAI's WebSocket API."""
 
@@ -142,6 +169,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         self._tracing_config: RealtimeModelTracingConfig | Literal["auto"] | None = None
         self._playback_tracker: RealtimePlaybackTracker | None = None
         self._created_session: OpenAISessionObject | None = None
+        self._server_event_type_adapter = get_server_event_type_adapter()
 
     async def connect(self, options: RealtimeModelConfig) -> None:
         """Establish a connection to the model and keep it alive."""
@@ -462,9 +490,9 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         try:
             if "previous_item_id" in event and event["previous_item_id"] is None:
                 event["previous_item_id"] = ""  # TODO (rm) remove
-            parsed: OpenAIRealtimeServerEvent = TypeAdapter(
-                OpenAIRealtimeServerEvent
-            ).validate_python(event)
+            parsed: AllRealtimeServerEvents = self._server_event_type_adapter.validate_python(
+                event
+            )
         except pydantic.ValidationError as e:
             logger.error(f"Failed to validate server event: {event}", exc_info=True)
             await self._emit_event(
@@ -554,6 +582,12 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             or parsed.type == "response.output_item.done"
         ):
             await self._handle_output_item(parsed.item)
+        elif parsed.type == "input_audio_buffer.timeout_triggered":
+            await self._emit_event(RealtimeModelInputAudioTimeoutTriggeredEvent(
+                item_id=parsed.item_id,
+                audio_start_ms=parsed.audio_start_ms,
+                audio_end_ms=parsed.audio_end_ms,
+            ))
 
     def _update_created_session(self, session: OpenAISessionObject) -> None:
         self._created_session = session

agents/realtime/session.py

@@ -28,6 +28,7 @@ from .events import (
     RealtimeHandoffEvent,
     RealtimeHistoryAdded,
     RealtimeHistoryUpdated,
+    RealtimeInputAudioTimeoutTriggered,
     RealtimeRawModelEvent,
     RealtimeSessionEvent,
     RealtimeToolEnd,
@@ -227,6 +228,12 @@ class RealtimeSession(RealtimeModelListener):
             await self._put_event(
                 RealtimeHistoryUpdated(info=self._event_info, history=self._history)
             )
+        elif event.type == "input_audio_timeout_triggered":
+            await self._put_event(
+                RealtimeInputAudioTimeoutTriggered(
+                    info=self._event_info,
+                )
+            )
         elif event.type == "transcript_delta":
             # Accumulate transcript text for guardrail debouncing per item_id
             item_id = event.item_id

agents/repl.py

@@ -8,10 +8,13 @@ from .agent import Agent
 from .items import TResponseInputItem
 from .result import RunResultBase
 from .run import Runner
+from .run_context import TContext
 from .stream_events import AgentUpdatedStreamEvent, RawResponsesStreamEvent, RunItemStreamEvent
 
 
-async def run_demo_loop(agent: Agent[Any], *, stream: bool = True) -> None:
+async def run_demo_loop(
+    agent: Agent[Any], *, stream: bool = True, context: TContext | None = None
+) -> None:
     """Run a simple REPL loop with the given agent.
 
     This utility allows quick manual testing and debugging of an agent from the
@@ -21,6 +24,7 @@ async def run_demo_loop(agent: Agent[Any], *, stream: bool = True) -> None:
     Args:
         agent: The starting agent to run.
         stream: Whether to stream the agent output.
+        context: Additional context information to pass to the runner.
     """
 
     current_agent = agent
@@ -40,7 +44,7 @@ async def run_demo_loop(agent: Agent[Any], *, stream: bool = True) -> None:
 
         result: RunResultBase
         if stream:
-            result = Runner.run_streamed(current_agent, input=input_items)
+            result = Runner.run_streamed(current_agent, input=input_items, context=context)
             async for event in result.stream_events():
                 if isinstance(event, RawResponsesStreamEvent):
                     if isinstance(event.data, ResponseTextDeltaEvent):
@@ -54,7 +58,7 @@ async def run_demo_loop(agent: Agent[Any], *, stream: bool = True) -> None:
                     print(f"\n[Agent updated: {event.new_agent.name}]", flush=True)
             print()
         else:
-            result = await Runner.run(current_agent, input_items)
+            result = await Runner.run(current_agent, input_items, context=context)
             if result.final_output is not None:
                 print(result.final_output)