openai-agents 0.2.7__py3-none-any.whl → 0.2.9__py3-none-any.whl

agents/mcp/server.py

@@ -3,10 +3,11 @@ from __future__ import annotations
 import abc
 import asyncio
 import inspect
+from collections.abc import Awaitable
 from contextlib import AbstractAsyncContextManager, AsyncExitStack
 from datetime import timedelta
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, cast
+from typing import TYPE_CHECKING, Any, Callable, Literal, TypeVar
 
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp import ClientSession, StdioServerParameters, Tool as MCPTool, stdio_client
@@ -19,7 +20,9 @@ from typing_extensions import NotRequired, TypedDict
 from ..exceptions import UserError
 from ..logger import logger
 from ..run_context import RunContextWrapper
-from .util import ToolFilter, ToolFilterCallable, ToolFilterContext, ToolFilterStatic
+from .util import ToolFilter, ToolFilterContext, ToolFilterStatic
+
+T = TypeVar("T")
 
 if TYPE_CHECKING:
     from ..agent import AgentBase
@@ -98,6 +101,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         client_session_timeout_seconds: float | None,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """
         Args:
@@ -115,6 +120,10 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, used for exponential
+                backoff between retries.
         """
         super().__init__(use_structured_content=use_structured_content)
         self.session: ClientSession | None = None
@@ -124,6 +133,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         self.server_initialize_result: InitializeResult | None = None
 
         self.client_session_timeout_seconds = client_session_timeout_seconds
+        self.max_retry_attempts = max_retry_attempts
+        self.retry_backoff_seconds_base = retry_backoff_seconds_base
 
         # The cache is always dirty at startup, so that we fetch tools at least once
         self._cache_dirty = True
@@ -175,10 +186,10 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
     ) -> list[MCPTool]:
         """Apply dynamic tool filtering using a callable filter function."""
 
-        # Ensure we have a callable filter and cast to help mypy
+        # Ensure we have a callable filter
         if not callable(self.tool_filter):
             raise ValueError("Tool filter must be callable for dynamic filtering")
-        tool_filter_func = cast(ToolFilterCallable, self.tool_filter)
+        tool_filter_func = self.tool_filter
 
         # Create filter context
         filter_context = ToolFilterContext(
@@ -233,6 +244,18 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         """Invalidate the tools cache."""
         self._cache_dirty = True
 
+    async def _run_with_retries(self, func: Callable[[], Awaitable[T]]) -> T:
+        attempts = 0
+        while True:
+            try:
+                return await func()
+            except Exception:
+                attempts += 1
+                if self.max_retry_attempts != -1 and attempts > self.max_retry_attempts:
+                    raise
+                backoff = self.retry_backoff_seconds_base * (2 ** (attempts - 1))
+                await asyncio.sleep(backoff)
+
     async def connect(self):
         """Connect to the server."""
         try:
@@ -267,15 +290,17 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         """List the tools available on the server."""
         if not self.session:
             raise UserError("Server not initialized. Make sure you call `connect()` first.")
+        session = self.session
+        assert session is not None
 
         # Return from cache if caching is enabled, we have tools, and the cache is not dirty
         if self.cache_tools_list and not self._cache_dirty and self._tools_list:
             tools = self._tools_list
         else:
-            # Reset the cache dirty to False
-            self._cache_dirty = False
             # Fetch the tools from the server
-            self._tools_list = (await self.session.list_tools()).tools
+            result = await self._run_with_retries(lambda: session.list_tools())
+            self._tools_list = result.tools
+            self._cache_dirty = False
             tools = self._tools_list
 
         # Filter tools based on tool_filter
@@ -290,8 +315,10 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         """Invoke a tool on the server."""
         if not self.session:
             raise UserError("Server not initialized. Make sure you call `connect()` first.")
+        session = self.session
+        assert session is not None
 
-        return await self.session.call_tool(tool_name, arguments)
+        return await self._run_with_retries(lambda: session.call_tool(tool_name, arguments))
 
     async def list_prompts(
         self,
@@ -365,6 +392,8 @@ class MCPServerStdio(_MCPServerWithClientSession):
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """Create a new MCP server based on the stdio transport.
 
@@ -388,12 +417,18 @@ class MCPServerStdio(_MCPServerWithClientSession):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, for exponential
+                backoff between retries.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
             use_structured_content,
+            max_retry_attempts,
+            retry_backoff_seconds_base,
         )
 
         self.params = StdioServerParameters(
@@ -455,6 +490,8 @@ class MCPServerSse(_MCPServerWithClientSession):
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """Create a new MCP server based on the HTTP with SSE transport.
 
@@ -480,12 +517,18 @@ class MCPServerSse(_MCPServerWithClientSession):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, for exponential
+                backoff between retries.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
             use_structured_content,
+            max_retry_attempts,
+            retry_backoff_seconds_base,
         )
 
         self.params = params
@@ -547,6 +590,8 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """Create a new MCP server based on the Streamable HTTP transport.
 
@@ -573,12 +618,18 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, for exponential
+                backoff between retries.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
             use_structured_content,
+            max_retry_attempts,
+            retry_backoff_seconds_base,
         )
 
         self.params = params

agents/model_settings.py

@@ -92,7 +92,10 @@ class ModelSettings:
     """
 
     truncation: Literal["auto", "disabled"] | None = None
-    """The truncation strategy to use when calling the model."""
+    """The truncation strategy to use when calling the model.
+    See [Responses API documentation](https://platform.openai.com/docs/api-reference/responses/create#responses_create-truncation)
+    for more details.
+    """
 
     max_tokens: int | None = None
     """The maximum number of output tokens to generate."""

agents/models/__init__.py

@@ -0,0 +1,13 @@
+from .default_models import (
+    get_default_model,
+    get_default_model_settings,
+    gpt_5_reasoning_settings_required,
+    is_gpt_5_default,
+)
+
+__all__ = [
+    "get_default_model",
+    "get_default_model_settings",
+    "gpt_5_reasoning_settings_required",
+    "is_gpt_5_default",
+]

agents/models/chatcmpl_converter.py

@@ -271,11 +271,16 @@ class Converter:
                     raise UserError(
                         f"Only file_data is supported for input_file {casted_file_param}"
                     )
+                if "filename" not in casted_file_param or not casted_file_param["filename"]:
+                    raise UserError(
+                        f"filename must be provided for input_file {casted_file_param}"
+                    )
                 out.append(
                     File(
                         type="file",
                         file=FileFile(
                             file_data=casted_file_param["file_data"],
+                            filename=casted_file_param["filename"],
                         ),
                     )
                 )

agents/models/default_models.py

@@ -0,0 +1,58 @@
+import copy
+import os
+from typing import Optional
+
+from openai.types.shared.reasoning import Reasoning
+
+from agents.model_settings import ModelSettings
+
+OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME = "OPENAI_DEFAULT_MODEL"
+
+# discourage directly accessing this constant
+# use the get_default_model and get_default_model_settings() functions instead
+_GPT_5_DEFAULT_MODEL_SETTINGS: ModelSettings = ModelSettings(
+    # We chose "low" instead of "minimal" because some of the built-in tools
+    # (e.g., file search, image generation, etc.) do not support "minimal"
+    # If you want to use "minimal" reasoning effort, you can pass your own model settings
+    reasoning=Reasoning(effort="low"),
+    verbosity="low",
+)
+
+
+def gpt_5_reasoning_settings_required(model_name: str) -> bool:
+    """
+    Returns True if the model name is a GPT-5 model and reasoning settings are required.
+    """
+    if model_name.startswith("gpt-5-chat"):
+        # gpt-5-chat-latest does not require reasoning settings
+        return False
+    # matches any of gpt-5 models
+    return model_name.startswith("gpt-5")
+
+
+def is_gpt_5_default() -> bool:
+    """
+    Returns True if the default model is a GPT-5 model.
+    This is used to determine if the default model settings are compatible with GPT-5 models.
+    If the default model is not a GPT-5 model, the model settings are compatible with other models.
+    """
+    return gpt_5_reasoning_settings_required(get_default_model())
+
+
+def get_default_model() -> str:
+    """
+    Returns the default model name.
+    """
+    return os.getenv(OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME, "gpt-4.1").lower()
+
+
+def get_default_model_settings(model: Optional[str] = None) -> ModelSettings:
+    """
+    Returns the default model settings.
+    If the default model is a GPT-5 model, returns the GPT-5 default model settings.
+    Otherwise, returns the legacy default model settings.
+    """
+    _model = model if model is not None else get_default_model()
+    if gpt_5_reasoning_settings_required(_model):
+        return copy.deepcopy(_GPT_5_DEFAULT_MODEL_SETTINGS)
+    return ModelSettings()

agents/models/openai_provider.py

@@ -4,10 +4,12 @@ import httpx
 from openai import AsyncOpenAI, DefaultAsyncHttpxClient
 
 from . import _openai_shared
+from .default_models import get_default_model
 from .interface import Model, ModelProvider
 from .openai_chatcompletions import OpenAIChatCompletionsModel
 from .openai_responses import OpenAIResponsesModel
 
+# This is kept for backward compatiblity but using get_default_model() method is recommended.
 DEFAULT_MODEL: str = "gpt-4o"
 
 
@@ -80,7 +82,7 @@ class OpenAIProvider(ModelProvider):
 
     def get_model(self, model_name: str | None) -> Model:
         if model_name is None:
-            model_name = DEFAULT_MODEL
+            model_name = get_default_model()
 
         client = self._get_client()
 

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,22 @@ 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"),
+]
+
+
 class OpenAIRealtimeWebSocketModel(RealtimeModel):
     """A model that uses OpenAI's WebSocket API."""
 
@@ -170,7 +187,10 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             "OpenAI-Beta": "realtime=v1",
         }
         self._websocket = await websockets.connect(
-            url, user_agent_header=_USER_AGENT, additional_headers=headers
+            url,
+            user_agent_header=_USER_AGENT,
+            additional_headers=headers,
+            max_size=None,  # Allow any size of message
         )
         self._websocket_task = asyncio.create_task(self._listen_for_messages())
         await self._update_session_config(model_settings)
@@ -459,8 +479,8 @@ 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
+            parsed: AllRealtimeServerEvents = TypeAdapter(
+                AllRealtimeServerEvents
             ).validate_python(event)
         except pydantic.ValidationError as e:
             logger.error(f"Failed to validate server event: {event}", exc_info=True)
@@ -551,6 +571,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

@@ -10,6 +10,7 @@ from typing_extensions import assert_never
 from ..agent import Agent
 from ..exceptions import ModelBehaviorError, UserError
 from ..handoffs import Handoff
+from ..logger import logger
 from ..run_context import RunContextWrapper, TContext
 from ..tool import FunctionTool
 from ..tool_context import ToolContext
@@ -27,13 +28,14 @@ from .events import (
     RealtimeHandoffEvent,
     RealtimeHistoryAdded,
     RealtimeHistoryUpdated,
+    RealtimeInputAudioTimeoutTriggered,
     RealtimeRawModelEvent,
     RealtimeSessionEvent,
     RealtimeToolEnd,
     RealtimeToolStart,
 )
 from .handoffs import realtime_handoff
-from .items import InputAudio, InputText, RealtimeItem
+from .items import AssistantAudio, InputAudio, InputText, RealtimeItem
 from .model import RealtimeModel, RealtimeModelConfig, RealtimeModelListener
 from .model_events import (
     RealtimeModelEvent,
@@ -226,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
@@ -246,7 +254,58 @@ class RealtimeSession(RealtimeModelListener):
                 self._enqueue_guardrail_task(self._item_transcripts[item_id], event.response_id)
         elif event.type == "item_updated":
             is_new = not any(item.item_id == event.item.item_id for item in self._history)
-            self._history = self._get_new_history(self._history, event.item)
+
+            # Preserve previously known transcripts when updating existing items.
+            # This prevents transcripts from disappearing when an item is later
+            # retrieved without transcript fields populated.
+            incoming_item = event.item
+            existing_item = next(
+                (i for i in self._history if i.item_id == incoming_item.item_id), None
+            )
+
+            if (
+                existing_item is not None
+                and existing_item.type == "message"
+                and incoming_item.type == "message"
+            ):
+                try:
+                    # Merge transcripts for matching content indices
+                    existing_content = existing_item.content
+                    new_content = []
+                    for idx, entry in enumerate(incoming_item.content):
+                        # Only attempt to preserve for audio-like content
+                        if entry.type in ("audio", "input_audio"):
+                            # Use tuple form for Python 3.9 compatibility
+                            assert isinstance(entry, (InputAudio, AssistantAudio))
+                            # Determine if transcript is missing/empty on the incoming entry
+                            entry_transcript = entry.transcript
+                            if not entry_transcript:
+                                preserved: str | None = None
+                                # First prefer any transcript from the existing history item
+                                if idx < len(existing_content):
+                                    this_content = existing_content[idx]
+                                    if isinstance(this_content, AssistantAudio) or isinstance(
+                                        this_content, InputAudio
+                                    ):
+                                        preserved = this_content.transcript
+
+                                # If still missing and this is an assistant item, fall back to
+                                # accumulated transcript deltas tracked during the turn.
+                                if not preserved and incoming_item.role == "assistant":
+                                    preserved = self._item_transcripts.get(incoming_item.item_id)
+
+                                if preserved:
+                                    entry = entry.model_copy(update={"transcript": preserved})
+
+                        new_content.append(entry)
+
+                    if new_content:
+                        incoming_item = incoming_item.model_copy(update={"content": new_content})
+                except Exception:
+                    logger.error("Error merging transcripts", exc_info=True)
+                    pass
+
+            self._history = self._get_new_history(self._history, incoming_item)
             if is_new:
                 new_item = next(
                     item for item in self._history if item.item_id == event.item.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)