Skip to content

feat: Add external_web_access option to WebSearchTool #2143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
seratch wants to merge 4 commits into
base: main
Choose a base branch
from
+13 −3
Draft

feat: Add external_web_access option to WebSearchTool #2143

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
129104c
feat: Add external_web_access option to WebSearchTool
seratch Dec 3, 2025
0987153
fix
seratch Dec 3, 2025
5f6da08
fix review comment
seratch Dec 3, 2025
8cda74b
fix
seratch Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions examples/tools/web_search_filters.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
1 change: 1 addition & 0 deletions src/agents/models/openai_responses.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,7 @@ def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, ResponseIncludable | None
"filters": tool.filters.model_dump() if tool.filters is not None else None, # type: ignore [typeddict-item]
"user_location": tool.user_location,
"search_context_size": tool.search_context_size,
"external_web_access": tool.external_web_access,
}
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Stop sending null external_web_access flag

The new external_web_access option is always included in the payload, even when left at its default None, so every WebSearchTool() call now emits "external_web_access": null (openai_responses.py lines 475‑479). The Responses API expects a boolean and defaults to live access when the field is omitted; sending null will reject the request or bypass the documented default, breaking existing callers that don’t set the flag. The converter should skip the field when it is unset.

Useful? React with 👍 / 👎.

includes = None
elif isinstance(tool, FileSearchTool):
Expand Down
4 changes: 4 additions & 0 deletions src/agents/tool.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,10 @@ 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/cache-only mode. Default is true (live access) if you do not set it.
"""

@property
def name(self):
return "web_search"
Expand Down
Loading