feat: Add external_web_access option to WebSearchTool

examples/tools/web_search_filters.py

@@ -36,6 +36,8 @@ async def main():
                     ],
                 ),
                 search_context_size="medium",
+                # https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#live-internet-access
+                # external_web_access=False,
             )
         ],
         model_settings=ModelSettings(

src/agents/models/openai_responses.py

@@ -469,13 +469,15 @@ def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, ResponseIncludable | None
             }
             includes: ResponseIncludable | None = None
         elif isinstance(tool, WebSearchTool):
-            # TODO: revist the type: ignore comment when ToolParam is updated in the future
-            converted_tool = {
+            converted_tool_dict: dict[str, Any] = {
                 "type": "web_search",
-                "filters": tool.filters.model_dump() if tool.filters is not None else None,  # type: ignore [typeddict-item]
+                "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:
+                converted_tool_dict["external_web_access"] = tool.external_web_access
+            converted_tool = cast(ToolParam, converted_tool_dict)
             includes = None
         elif isinstance(tool, FileSearchTool):
             converted_tool = {

src/agents/tool.py

@@ -232,6 +232,12 @@ 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
+    """Control whether the web search tool fetches live content or uses only cached/indexed
+    results in the Responses API. Set external_web_access: false on the web_search tool to run
+    in offline or cache-only mode. Default is true (live access) if you do not set it.
+    """
+
     @property
     def name(self):
         return "web_search"