Merge branch 'main' into fix/issue-879-mcp-http-error-handling

gn00295120 · web-flow · commit 46b4624719b5 · 2025-10-23T19:04:43.000+08:00
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -22,6 +22,8 @@ jobs:
           enable-cache: true
       - name: Install dependencies
         run: make sync
+      - name: Verify formatting
+        run: make format-check
       - name: Run lint
         run: make lint
 
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# OpenAI Agents SDK
+# OpenAI Agents SDK [![PyPI](https://img.shields.io/pypi/v/openai-agents?label=pypi%20package)](https://pypi.org/project/openai-agents/)
 
 The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "openai-agents"
-version = "0.4.0"
+version = "0.4.1"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"
diff --git a/src/agents/extensions/memory/sqlalchemy_session.py b/src/agents/extensions/memory/sqlalchemy_session.py
@@ -319,3 +319,16 @@ async def clear_session(self) -> None:
                 await sess.execute(
                     delete(self._sessions).where(self._sessions.c.session_id == self.session_id)
                 )
+
+    @property
+    def engine(self) -> AsyncEngine:
+        """Access the underlying SQLAlchemy AsyncEngine.
+
+        This property provides direct access to the engine for advanced use cases,
+        such as checking connection pool status, configuring engine settings,
+        or manually disposing the engine when needed.
+
+        Returns:
+            AsyncEngine: The SQLAlchemy async engine instance.
+        """
+        return self._engine
diff --git a/src/agents/extensions/models/litellm_model.py b/src/agents/extensions/models/litellm_model.py
@@ -44,6 +44,7 @@
 from ...models.chatcmpl_stream_handler import ChatCmplStreamHandler
 from ...models.fake_id import FAKE_RESPONSES_ID
 from ...models.interface import Model, ModelTracing
+from ...models.openai_responses import Converter as OpenAIResponsesConverter
 from ...tool import Tool
 from ...tracing import generation_span
 from ...tracing.span_data import GenerationSpanData
@@ -325,6 +326,23 @@ async def _fetch_response(
             )
 
         reasoning_effort = model_settings.reasoning.effort if model_settings.reasoning else None
+        # Enable developers to pass non-OpenAI compatible reasoning_effort data like "none"
+        # Priority order:
+        #  1. model_settings.reasoning.effort
+        #  2. model_settings.extra_body["reasoning_effort"]
+        #  3. model_settings.extra_args["reasoning_effort"]
+        if (
+            reasoning_effort is None  # Unset in model_settings
+            and isinstance(model_settings.extra_body, dict)
+            and "reasoning_effort" in model_settings.extra_body
+        ):
+            reasoning_effort = model_settings.extra_body["reasoning_effort"]
+        if (
+            reasoning_effort is None  # Unset in both model_settings and model_settings.extra_body
+            and model_settings.extra_args
+            and "reasoning_effort" in model_settings.extra_args
+        ):
+            reasoning_effort = model_settings.extra_args["reasoning_effort"]
 
         stream_options = None
         if stream and model_settings.include_usage is not None:
@@ -342,6 +360,9 @@ async def _fetch_response(
         if model_settings.extra_args:
             extra_kwargs.update(model_settings.extra_args)
 
+        # Prevent duplicate reasoning_effort kwargs when it was promoted to a top-level argument.
+        extra_kwargs.pop("reasoning_effort", None)
+
         ret = await litellm.acompletion(
             model=self.model,
             messages=converted_messages,
@@ -367,15 +388,19 @@ async def _fetch_response(
         if isinstance(ret, litellm.types.utils.ModelResponse):
             return ret
 
+        responses_tool_choice = OpenAIResponsesConverter.convert_tool_choice(
+            model_settings.tool_choice
+        )
+        if responses_tool_choice is None or responses_tool_choice is omit:
+            responses_tool_choice = "auto"
+
         response = Response(
             id=FAKE_RESPONSES_ID,
             created_at=time.time(),
             model=self.model,
             object="response",
             output=[],
-            tool_choice=cast(Literal["auto", "required", "none"], tool_choice)
-            if tool_choice is not omit
-            else "auto",
+            tool_choice=responses_tool_choice,  # type: ignore[arg-type]
             top_p=model_settings.top_p,
             temperature=model_settings.temperature,
             tools=[],
diff --git a/src/agents/items.py b/src/agents/items.py
@@ -361,6 +361,9 @@ def _maybe_get_output_as_structured_function_output(
         if isinstance(output, (ToolOutputText, ToolOutputImage, ToolOutputFileContent)):
             return output
         elif isinstance(output, dict):
+            # Require explicit 'type' field in dict to be considered a structured output
+            if "type" not in output:
+                return None
             try:
                 return ValidToolOutputPydanticModelsTypeAdapter.validate_python(output)
             except pydantic.ValidationError:
diff --git a/src/agents/realtime/model_inputs.py b/src/agents/realtime/model_inputs.py
@@ -95,6 +95,9 @@ class RealtimeModelSendToolOutput:
 class RealtimeModelSendInterrupt:
     """Send an interrupt to the model."""
 
+    force_response_cancel: bool = False
+    """Force sending a response.cancel event even if automatic cancellation is enabled."""
+
 
 @dataclass
 class RealtimeModelSendSessionUpdate:
diff --git a/src/agents/realtime/openai_realtime.py b/src/agents/realtime/openai_realtime.py
@@ -395,36 +395,36 @@ async def _send_interrupt(self, event: RealtimeModelSendInterrupt) -> None:
         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
-
-        current_item_content_index = current_item_content_index or 0
-        if elapsed_ms > 0:
-            await self._emit_event(
-                RealtimeModelAudioInterruptedEvent(
-                    item_id=current_item_id,
-                    content_index=current_item_content_index,
-                )
-            )
-            converted = _ConversionHelper.convert_interrupt(
-                current_item_id,
-                current_item_content_index,
-                int(elapsed_ms),
-            )
-            await self._send_raw_message(converted)
         else:
-            logger.debug(
-                "Didn't interrupt bc elapsed ms is < 0. "
-                f"Item id: {current_item_id}, "
-                f"elapsed ms: {elapsed_ms}, "
-                f"content index: {current_item_content_index}"
-            )
+            current_item_content_index = current_item_content_index or 0
+            if elapsed_ms > 0:
+                await self._emit_event(
+                    RealtimeModelAudioInterruptedEvent(
+                        item_id=current_item_id,
+                        content_index=current_item_content_index,
+                    )
+                )
+                converted = _ConversionHelper.convert_interrupt(
+                    current_item_id,
+                    current_item_content_index,
+                    int(elapsed_ms),
+                )
+                await self._send_raw_message(converted)
+            else:
+                logger.debug(
+                    "Didn't interrupt bc elapsed ms is < 0. "
+                    f"Item id: {current_item_id}, "
+                    f"elapsed ms: {elapsed_ms}, "
+                    f"content index: {current_item_content_index}"
+                )
 
         session = self._created_session
         automatic_response_cancellation_enabled = (
@@ -434,12 +434,16 @@ async def _send_interrupt(self, event: RealtimeModelSendInterrupt) -> None:
             and session.audio.input.turn_detection is not None
             and session.audio.input.turn_detection.interrupt_response is True
         )
-        if not automatic_response_cancellation_enabled:
+        should_cancel_response = event.force_response_cancel or (
+            not automatic_response_cancellation_enabled
+        )
+        if should_cancel_response:
             await self._cancel_response()
 
-        self._audio_state_tracker.on_interrupted()
-        if self._playback_tracker:
-            self._playback_tracker.on_interrupted()
+        if current_item_id is not None and elapsed_ms is not None:
+            self._audio_state_tracker.on_interrupted()
+            if self._playback_tracker:
+                self._playback_tracker.on_interrupted()
 
     async def _send_session_update(self, event: RealtimeModelSendSessionUpdate) -> None:
         """Send a session update to the model."""
diff --git a/src/agents/realtime/session.py b/src/agents/realtime/session.py
@@ -704,7 +704,7 @@ async def _run_output_guardrails(self, text: str, response_id: str) -> bool:
             )
 
             # Interrupt the model
-            await self._model.send_event(RealtimeModelSendInterrupt())
+            await self._model.send_event(RealtimeModelSendInterrupt(force_response_cancel=True))
 
             # Send guardrail triggered message
             guardrail_names = [result.guardrail.get_name() for result in triggered_results]
diff --git a/src/agents/run.py b/src/agents/run.py
@@ -1138,6 +1138,15 @@ async def _start_streaming(
 
             streamed_result.is_complete = True
         finally:
+            if streamed_result._input_guardrails_task:
+                try:
+                    await AgentRunner._input_guardrail_tripwire_triggered_for_stream(
+                        streamed_result
+                    )
+                except Exception as e:
+                    logger.debug(
+                        f"Error in streamed_result finalize for agent {current_agent.name} - {e}"
+                    )
             if current_span:
                 current_span.finish(reset_current=True)
             if streamed_result.trace:
diff --git a/src/agents/tool.py b/src/agents/tool.py
@@ -15,7 +15,7 @@
 from openai.types.responses.tool_param import CodeInterpreter, ImageGeneration, Mcp
 from openai.types.responses.web_search_tool import Filters as WebSearchToolFilters
 from openai.types.responses.web_search_tool_param import UserLocation
-from pydantic import BaseModel, TypeAdapter, ValidationError
+from pydantic import BaseModel, TypeAdapter, ValidationError, model_validator
 from typing_extensions import Concatenate, NotRequired, ParamSpec, TypedDict
 
 from . import _debug
@@ -75,6 +75,13 @@ class ToolOutputImage(BaseModel):
     file_id: str | None = None
     detail: Literal["low", "high", "auto"] | None = None
 
+    @model_validator(mode="after")
+    def check_at_least_one_required_field(self) -> ToolOutputImage:
+        """Validate that at least one of image_url or file_id is provided."""
+        if self.image_url is None and self.file_id is None:
+            raise ValueError("At least one of image_url or file_id must be provided")
+        return self
+
 
 class ToolOutputImageDict(TypedDict, total=False):
     """TypedDict variant for image tool outputs."""
@@ -98,6 +105,13 @@ class ToolOutputFileContent(BaseModel):
     file_id: str | None = None
     filename: str | None = None
 
+    @model_validator(mode="after")
+    def check_at_least_one_required_field(self) -> ToolOutputFileContent:
+        """Validate that at least one of file_data, file_url, or file_id is provided."""
+        if self.file_data is None and self.file_url is None and self.file_id is None:
+            raise ValueError("At least one of file_data, file_url, or file_id must be provided")
+        return self
+
 
 class ToolOutputFileContentDict(TypedDict, total=False):
     """TypedDict variant for file content tool outputs."""
diff --git a/tests/extensions/memory/test_sqlalchemy_session.py b/tests/extensions/memory/test_sqlalchemy_session.py
@@ -14,6 +14,7 @@
     Summary,
 )
 from sqlalchemy import select, text, update
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 from sqlalchemy.sql import Select
 
 pytest.importorskip("sqlalchemy")  # Skip tests if SQLAlchemy is not installed
@@ -390,3 +391,56 @@ async def recording_execute(statement: Any, *args: Any, **kwargs: Any) -> Any:
 
     assert _item_ids(retrieved_full) == ["rs_first", "msg_second"]
     assert _item_ids(retrieved_limited) == ["rs_first", "msg_second"]
+
+
+async def test_engine_property_from_url():
+    """Test that the engine property returns the AsyncEngine from from_url."""
+    session_id = "engine_property_test"
+    session = SQLAlchemySession.from_url(session_id, url=DB_URL, create_tables=True)
+
+    # Verify engine property returns an AsyncEngine instance
+    assert isinstance(session.engine, AsyncEngine)
+
+    # Verify we can use the engine for advanced operations
+    # For example, check pool status
+    assert session.engine.pool is not None
+
+    # Verify we can manually dispose the engine
+    await session.engine.dispose()
+
+
+async def test_engine_property_from_external_engine():
+    """Test that the engine property returns the external engine."""
+    session_id = "external_engine_test"
+
+    # Create engine externally
+    external_engine = create_async_engine(DB_URL)
+
+    # Create session with external engine
+    session = SQLAlchemySession(session_id, engine=external_engine, create_tables=True)
+
+    # Verify engine property returns the same engine instance
+    assert session.engine is external_engine
+
+    # Verify we can use the engine
+    assert isinstance(session.engine, AsyncEngine)
+
+    # Clean up - user is responsible for disposing external engine
+    await external_engine.dispose()
+
+
+async def test_engine_property_is_read_only():
+    """Test that the engine property cannot be modified."""
+    session_id = "readonly_engine_test"
+    session = SQLAlchemySession.from_url(session_id, url=DB_URL, create_tables=True)
+
+    # Verify engine property exists
+    assert hasattr(session, "engine")
+
+    # Verify it's a property (read-only, cannot be set)
+    # Type ignore needed because mypy correctly detects this is read-only
+    with pytest.raises(AttributeError):
+        session.engine = create_async_engine(DB_URL)  # type: ignore[misc]
+
+    # Clean up
+    await session.engine.dispose()
diff --git a/tests/models/test_kwargs_functionality.py b/tests/models/test_kwargs_functionality.py
@@ -176,3 +176,41 @@ async def fake_acompletion(model, messages=None, **kwargs):
 
     # Should work without error and include regular parameters
     assert captured["temperature"] == 0.3
+
+
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_reasoning_effort_falls_back_to_extra_args(monkeypatch):
+    """
+    Ensure reasoning_effort from extra_args is promoted when reasoning settings are missing.
+    """
+    captured: dict[str, object] = {}
+
+    async def fake_acompletion(model, messages=None, **kwargs):
+        captured.update(kwargs)
+        msg = Message(role="assistant", content="test response")
+        choice = Choices(index=0, message=msg)
+        return ModelResponse(choices=[choice], usage=Usage(0, 0, 0))
+
+    monkeypatch.setattr(litellm, "acompletion", fake_acompletion)
+
+    # GitHub issue context: https://github.com/openai/openai-agents-python/issues/1764.
+    settings = ModelSettings(
+        extra_args={"reasoning_effort": "none", "custom_param": "custom_value"}
+    )
+    model = LitellmModel(model="test-model")
+
+    await model.get_response(
+        system_instructions=None,
+        input="test input",
+        model_settings=settings,
+        tools=[],
+        output_schema=None,
+        handoffs=[],
+        tracing=ModelTracing.DISABLED,
+        previous_response_id=None,
+    )
+
+    assert captured["reasoning_effort"] == "none"
+    assert captured["custom_param"] == "custom_value"
+    assert settings.extra_args == {"reasoning_effort": "none", "custom_param": "custom_value"}
diff --git a/tests/models/test_litellm_extra_body.py b/tests/models/test_litellm_extra_body.py
diff --git a/tests/realtime/test_openai_realtime.py b/tests/realtime/test_openai_realtime.py
diff --git a/tests/test_stream_input_guardrail_timing.py b/tests/test_stream_input_guardrail_timing.py
diff --git a/tests/test_tool_output_conversion.py b/tests/test_tool_output_conversion.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# OpenAI Agents SDK`
	`1`	`+# OpenAI Agents SDK [![PyPI](https://img.shields.io/pypi/v/openai-agents?label=pypi%20package)](https://pypi.org/project/openai-agents/)`
`2`	`2`
`3`	`3`	`The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -704,7 +704,7 @@ async def _run_output_guardrails(self, text: str, response_id: str) -> bool:`
`704`	`704`	`)`
`705`	`705`
`706`	`706`	`# Interrupt the model`
`707`		`- await self._model.send_event(RealtimeModelSendInterrupt())`
	`707`	`+ await self._model.send_event(RealtimeModelSendInterrupt(force_response_cancel=True))`
`708`	`708`
`709`	`709`	`# Send guardrail triggered message`
`710`	`710`	`guardrail_names = [result.guardrail.get_name() for result in triggered_results]`