Anthropic messages
Add a web_search tool to thetools array:
server_tool_use and web_search_tool_result blocks alongside the usual text blocks:
OpenAI chat completions
Use theweb_search_options field at the top level of the request body — not the tools array:
web_search_options and tools are mutually exclusive. Requests with both return 400.
OpenAI Responses API
Add a web_search entry to thetools array:
web_search, web_search_preview, web_search_2025_08_26, web_search_preview_2025_03_11.
When combined with tool_choice={"type": "required"}, the search fires before the model starts, and the stream emits five lifecycle events up front:
Domain allow/block
Projects configured through Policy Gateway can restrict which domains web search may reach. See Policy Gateway onboarding →web_tools.
Known limitations
Replaying a previous assistant message that containsserver_tool_use or web_search_tool_result blocks back into a new request can trigger a 422 upstream. Strip those blocks before replaying. Tracked in the compatibility matrix.