Repository navigation
feat(tools): add search_content_types and image_settings to WebSearchTool - #4704
fuchengwarrenzhu wants to merge 4 commits into
Conversation
…Tool
The Responses API web_search tool accepts search_content_types
(["text", "image"]) and image_settings ({max_results, caption}) to
return image results alongside text. WebSearchTool had no way to set
them, so image search was unreachable through the SDK.
Both fields are optional and omitted from the tool payload when unset,
matching how external_web_access is passed through.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_0118QL4rZytJhQHVCdYmkSRS
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4f086a0b00
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Match the reviewed shape of openai#3474: when search_content_types includes "image", add the web_search_call.results include so image results are returned. Text-only configurations add no include. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_0118QL4rZytJhQHVCdYmkSRS
|
Checked past PRs before opening this: #3474 (by @yuning-oai) proposed the same This PR carries the same converter shape as #3474, including the |
seratch
left a comment
seratch
left a comment
There was a problem hiding this comment.
The platform need is valid: the current OpenAI documentation defines search_content_types, image_settings, and web_search_call.results for image search.
Two repository-readiness changes are still required:
- WebSearchToolImageSettings is part of the public WebSearchTool constructor annotation, so it must be exported from agents, included in the public export surface, and covered by an import regression test.
- Please remove the new docs/tools.md claim from this feature PR. Repository policy requires documentation for behavior unavailable in the latest published SDK release to land in a separately timed docs-only PR (I will handle this doc PR).
The provider conversion and automatic web_search_call.results include otherwise look appropriately scoped.
Export the image settings type from the public package, preserve its release contract, and defer unreleased documentation to the follow-up PR.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
From codex: Addressed in
The updated fork workflow is awaiting maintainer approval. Ready for re-review once it runs. |
sylvesterkaczmarek
left a comment
sylvesterkaczmarek
left a comment
There was a problem hiding this comment.
image_settings is accepted even when search_content_types is omitted or text-only. The converter still forwards image_settings, but it only requests web_search_call.results when "image" is selected, so the public constructor can produce a contradictory request. Could we require "image" whenever image_settings is set and add a regression?
…s set image_settings configures results the request only asks for when search_content_types includes "image"; the constructor now refuses the pair without it, the same way ShellTool refuses an executor for a hosted environment.
|
Agreed, and fixed in 1a427db: |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1a427db1f6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if self.image_settings is not None and ( | ||
| self.search_content_types is None or "image" not in self.search_content_types | ||
| ): | ||
| raise UserError( | ||
| 'WebSearchTool image_settings requires search_content_types to include "image".' |
There was a problem hiding this comment.
When a caller supplies image_settings without selecting "image", this guard raises during WebSearchTool construction even though it only duplicates Responses request grammar that the upstream provider can reject authoritatively; no SDK-owned state, side effect, or resource is at risk before that rejection. Remove this guard and its rejection test so the owning adapter/provider remains the source of truth for this provider-specific constraint.
AGENTS.md reference: AGENTS.md:L140-L140
Useful? React with 👍 / 👎.
|
Thanks — this closes the contradictory request shape cleanly. Failing construction unless |
Allow WebSearchTool to request image-only or mixed text/image results and configure image settings through the existing Responses API tool payload. Request raw image results automatically and export the public settings type. Preserve existing constructor order and default behavior, with converter, public import, and streaming/non-streaming HTTP request regression coverage. Supersedes #4704. Co-authored-by: Warren <[email protected]>
|
Thanks for working on this. The issue was resolved by #4898 |
Summary
This pull request adds the Responses API image-search controls to
WebSearchTool:search_content_typesselects text and/or image results.image_settingsconfiguresmax_resultsandcaption.web_search_call.results.Both fields remain optional and are omitted when unset, preserving existing
WebSearchToolbehavior.WebSearchToolImageSettingsis exported fromagents, and the release contract now pins its import identity plus both optionalTypedDictfields.Per maintainer review and the repository's documentation release-timing policy, this feature PR does not update
docs/tools.md; that release-timed documentation belongs in a separate docs-only PR.Test plan
make format,make lint, andmake typecheckpass.make tests-serial: 77 passed, 4 skipped.make tests: 9,193 passed and 55 skipped. The Codex workspace sandbox blocks 16 unrelated tests that bind local TCP or multiprocessing Unix sockets. One unrelated 0.2-second cancellation test timed out under xdist and passes alone. GitHub checks provide the unrestricted full-suite result.Issue number
None.
Checks
.agents/skills/code-change-verification/scripts/run.sh/reviewbefore submitting this PR