fix: #2636 make Computer preview metadata optional on GA requests (#2639)

Author: seratch

src/agents/computer.py

@@ -10,14 +10,14 @@ class Computer(abc.ABC):
     operations needed to control a computer or browser."""
 
     @property
-    @abc.abstractmethod
-    def environment(self) -> Environment:
-        pass
+    def environment(self) -> Environment | None:
+        """Return preview tool metadata when the preview computer payload is required."""
+        return None
 
     @property
-    @abc.abstractmethod
-    def dimensions(self) -> tuple[int, int]:
-        pass
+    def dimensions(self) -> tuple[int, int] | None:
+        """Return preview display dimensions when the preview computer payload is required."""
+        return None
 
     @abc.abstractmethod
     def screenshot(self) -> str:
@@ -61,14 +61,14 @@ class AsyncComputer(abc.ABC):
     operations needed to control a computer or browser."""
 
     @property
-    @abc.abstractmethod
-    def environment(self) -> Environment:
-        pass
+    def environment(self) -> Environment | None:
+        """Return preview tool metadata when the preview computer payload is required."""
+        return None
 
     @property
-    @abc.abstractmethod
-    def dimensions(self) -> tuple[int, int]:
-        pass
+    def dimensions(self) -> tuple[int, int] | None:
+        """Return preview display dimensions when the preview computer payload is required."""
+        return None
 
     @abc.abstractmethod
     async def screenshot(self) -> str:

src/agents/models/openai_responses.py

@@ -1768,12 +1768,19 @@ def _convert_preview_computer_tool(cls, tool: ComputerTool[Any]) -> ResponsesToo
                 "resolve_computer({ tool, run_context }) with a run context first "
                 "when building payloads manually."
             )
+        environment = computer.environment
+        dimensions = computer.dimensions
+        if environment is None or dimensions is None:
+            raise UserError(
+                "Preview computer tool payloads require `environment` and `dimensions` on the "
+                "Computer/AsyncComputer implementation."
+            )
         return _require_responses_tool_param(
             {
                 "type": "computer_use_preview",
-                "environment": computer.environment,
-                "display_width": computer.dimensions[0],
-                "display_height": computer.dimensions[1],
+                "environment": environment,
+                "display_width": dimensions[0],
+                "display_height": dimensions[1],
             }
         )
 

tests/test_openai_responses.py

@@ -11,7 +11,15 @@
 from openai.types.responses import ResponseCompletedEvent
 from openai.types.shared.reasoning import Reasoning
 
-from agents import Computer, ComputerTool, ModelSettings, ModelTracing, ToolSearchTool, __version__
+from agents import (
+    AsyncComputer,
+    Computer,
+    ComputerTool,
+    ModelSettings,
+    ModelTracing,
+    ToolSearchTool,
+    __version__,
+)
 from agents.exceptions import UserError
 from agents.models.openai_responses import (
     _HEADERS_OVERRIDE as RESP_HEADERS,
@@ -932,6 +940,69 @@ def __init__(self):
     assert called_kwargs["tools"] == [{"type": "tool_search"}]
 
 
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_ga_computer_tool_does_not_require_preview_metadata() -> None:
+    called_kwargs: dict[str, Any] = {}
+
+    class DummyComputer(AsyncComputer):
+        async def screenshot(self) -> str:
+            return "screenshot"
+
+        async def click(self, x: int, y: int, button: str) -> None:
+            pass
+
+        async def double_click(self, x: int, y: int) -> None:
+            pass
+
+        async def drag(self, path: list[tuple[int, int]]) -> None:
+            pass
+
+        async def keypress(self, keys: list[str]) -> None:
+            pass
+
+        async def move(self, x: int, y: int) -> None:
+            pass
+
+        async def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None:
+            pass
+
+        async def type(self, text: str) -> None:
+            pass
+
+        async def wait(self) -> None:
+            pass
+
+    class DummyResponses:
+        async def create(self, **kwargs):
+            nonlocal called_kwargs
+            called_kwargs = kwargs
+            return get_response_obj([])
+
+    class DummyResponsesClient:
+        def __init__(self):
+            self.responses = DummyResponses()
+
+    model = OpenAIResponsesModel(
+        model="gpt-5.4",
+        openai_client=DummyResponsesClient(),  # type: ignore[arg-type]
+        model_is_explicit=True,
+    )
+
+    await model.get_response(
+        system_instructions=None,
+        input="hi",
+        model_settings=ModelSettings(),
+        tools=[ComputerTool(computer=DummyComputer())],
+        output_schema=None,
+        handoffs=[],
+        tracing=ModelTracing.DISABLED,
+        prompt=None,
+    )
+
+    assert called_kwargs["tools"] == [{"type": "computer"}]
+
+
 @pytest.mark.allow_call_model_methods
 @pytest.mark.asyncio
 async def test_prompt_id_uses_preview_computer_payload_when_prompt_owns_model() -> None:
@@ -1012,6 +1083,73 @@ def __init__(self):
     ]
 
 
+@pytest.mark.allow_call_model_methods
+@pytest.mark.asyncio
+async def test_prompt_id_computer_without_preview_metadata_raises_clear_error() -> None:
+    called_kwargs: dict[str, Any] = {}
+
+    class DummyComputer(Computer):
+        def screenshot(self) -> str:
+            return "screenshot"
+
+        def click(self, x: int, y: int, button: str) -> None:
+            pass
+
+        def double_click(self, x: int, y: int) -> None:
+            pass
+
+        def drag(self, path: list[tuple[int, int]]) -> None:
+            pass
+
+        def keypress(self, keys: list[str]) -> None:
+            pass
+
+        def move(self, x: int, y: int) -> None:
+            pass
+
+        def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None:
+            pass
+
+        def type(self, text: str) -> None:
+            pass
+
+        def wait(self) -> None:
+            pass
+
+    class DummyResponses:
+        async def create(self, **kwargs):
+            nonlocal called_kwargs
+            called_kwargs = kwargs
+            return get_response_obj([])
+
+    class DummyResponsesClient:
+        def __init__(self):
+            self.responses = DummyResponses()
+
+    model = OpenAIResponsesModel(
+        model="gpt-5.4",
+        openai_client=DummyResponsesClient(),  # type: ignore[arg-type]
+        model_is_explicit=False,
+    )
+
+    with pytest.raises(
+        UserError,
+        match="Preview computer tool payloads require `environment` and `dimensions`",
+    ):
+        await model.get_response(
+            system_instructions=None,
+            input="hi",
+            model_settings=ModelSettings(),
+            tools=[ComputerTool(computer=DummyComputer())],
+            output_schema=None,
+            handoffs=[],
+            tracing=ModelTracing.DISABLED,
+            prompt={"id": "pmpt_123"},
+        )
+
+    assert called_kwargs == {}
+
+
 @pytest.mark.allow_call_model_methods
 @pytest.mark.asyncio
 async def test_prompt_id_unresolved_computer_uses_preview_payload_shape() -> None: