feat(tools): add search_content_types and image_settings to WebSearchTool

[fuchengwarrenzhu]

Summary

I encountered this issue when I'm trying to reconcile differences I'm observing with agentic workloads I'm running on top of the openai agent sdk vs. the ones ran on the Codex sdk.

In this PR, I'm adding two optional fields to WebSearchTool so image search is reachable through the SDK:

• search_content_types: list[Literal["text", "image"]] | None
• image_settings: WebSearchToolImageSettings | None — a TypedDict with max_results: int and caption: bool

Both are omitted from the web_search tool payload when unset, the same way external_web_access is handled, so existing behaviour is unchanged.

These map to the Responses API web_search tool fields documented in the web search guide (image results, currently with gpt-5.6). openai-python does not yet type them on WebSearchToolParam, so the converter keeps building the payload as an untyped dict via _require_responses_tool_param, as it already does for external_web_access.

WebSearchTool(
    search_content_types=["text", "image"],
    image_settings={"max_results": 3, "caption": True},
)

Test plan

• tests/models/test_openai_responses_converter.py: new test asserting both fields pass through; existing test extended to assert they are absent when unset.
• make format lint mypy pyright clean; make tests: 9232 passed, 3 unrelated parallel-run flakes (realtime handshake timeout, unix-local pause/resume, cancelled-sibling cleanup) that pass serially on both this branch and main.
• docs/tools.md updated (English only; translations left for the docs pipeline).

[chatgpt-codex-connector]

💡 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".

[fuchengwarrenzhu]

Checked past PRs before opening this: #3474 (by @yuning-oai) proposed the same search_content_types support in May and was approved in principle — "We can merge at the timing of either public beta or GA" — then went stale while the feature was pre-release. Image search is now documented as available in the web search guide, so that timing condition is met.

This PR carries the same converter shape as #3474, including the web_search_call.results include when "image" is requested, and adds image_settings (max_results, caption), which the guide documents alongside it.

[seratch]

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.