feat: add external web access to WebSearchTool

Author: ymuichiro

src/agents/models/openai_responses.py

@@ -1935,15 +1935,16 @@ def _convert_tool(
         if isinstance(tool, FunctionTool):
             return cls._convert_function_tool(tool)
         elif isinstance(tool, WebSearchTool):
+            web_search_tool: dict[str, Any] = {
+                "type": "web_search",
+                "filters": tool.filters.model_dump() if tool.filters is not None else None,
+                "user_location": tool.user_location,
+                "search_context_size": tool.search_context_size,
+            }
+            if tool.external_web_access is not None:
+                web_search_tool["external_web_access"] = tool.external_web_access
             return (
-                _require_responses_tool_param(
-                    {
-                        "type": "web_search",
-                        "filters": tool.filters.model_dump() if tool.filters is not None else None,
-                        "user_location": tool.user_location,
-                        "search_context_size": tool.search_context_size,
-                    }
-                ),
+                _require_responses_tool_param(web_search_tool),
                 None,
             )
         elif isinstance(tool, FileSearchTool):

src/agents/tool.py

@@ -499,6 +499,13 @@ class WebSearchTool:
     search_context_size: Literal["low", "medium", "high"] = "medium"
     """The amount of context to use for the search."""
 
+    external_web_access: bool | None = None
+    """Whether the web search tool may fetch live internet content.
+
+    When omitted, the API default is used. Set to `False` to request cached or
+    indexed-only behavior where supported.
+    """
+
     @property
     def name(self):
         return "web_search"

tests/test_openai_responses_converter.py

@@ -437,6 +437,7 @@ def test_convert_tools_basic_types_and_includes():
     web_params = next(ct for ct in converted.tools if ct["type"] == "web_search")
     assert web_params.get("user_location") == web_tool.user_location
     assert web_params.get("search_context_size") == web_tool.search_context_size
+    assert "external_web_access" not in web_params
     # Verify computer tool uses the GA built-in tool payload.
     comp_params = next(ct for ct in converted.tools if ct["type"] == "computer")
     assert comp_params == {"type": "computer"}
@@ -450,6 +451,23 @@ def test_convert_tools_basic_types_and_includes():
         Converter.convert_tools(tools=[comp_tool, comp_tool], handoffs=[])
 
 
+def test_convert_tools_includes_explicit_false_external_web_access() -> None:
+    web_tool = WebSearchTool(external_web_access=False)
+
+    converted = Converter.convert_tools([web_tool], handoffs=[], model="gpt-5.4")
+
+    assert converted.includes == []
+    assert converted.tools == [
+        {
+            "type": "web_search",
+            "filters": None,
+            "user_location": None,
+            "search_context_size": "medium",
+            "external_web_access": False,
+        }
+    ]
+
+
 def test_convert_tools_uses_preview_computer_payload_for_preview_model() -> None:
     comp_tool = ComputerTool(computer=DummyComputer())