From f48f2438f2d68d6e0021abe039f98b76991d26b6 Mon Sep 17 00:00:00 2001 From: Ryuzo Yamamoto Date: Wed, 8 Jul 2026 08:29:48 +0900 Subject: [PATCH] docs(ai-gateway): recommend GA web_search tool; correct annotations note The previous note told users to prefer web_search_preview because GA web_search "returns empty annotations." That was a test artifact: under the default tool_choice:auto the model only searches when it judges a query needs it, so a well-known fact returns no citations regardless of which tool. When a search actually runs, GA web_search returns web_search_call items and url_citation annotations. - Switch the example to the GA `web_search` tool. - Replace the incorrect warning with a tip about tool_choice auto vs required. - Align the privacy callout to reference `web_search`. --- docs/guides/ai-gateway.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/ai-gateway.md b/docs/guides/ai-gateway.md index 8322471..9fecd6e 100644 --- a/docs/guides/ai-gateway.md +++ b/docs/guides/ai-gateway.md @@ -132,7 +132,7 @@ Both OpenAI and Gemini models can answer with live, web-grounded information and ### OpenAI -Use the Responses API (`/v1/responses`) with the `web_search_preview` tool: +Use the Responses API (`/v1/responses`) with the `web_search` tool: ```bash {{ title: "OpenAI web search" }} curl https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev/v1/responses \ @@ -141,7 +141,7 @@ curl https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev/v1/responses \ -d '{ "model": "gpt-5", "input": "Who won the most recent FIFA World Cup? Include sources.", - "tools": [{ "type": "web_search_preview" }] + "tools": [{ "type": "web_search" }] }' ``` @@ -167,8 +167,8 @@ The `output` array holds one or more `web_search_call` items (the searches perfo } ``` -:::warning -Use `web_search_preview`, not the GA `web_search` tool. Through the gateway, `web_search` currently routes successfully but returns **empty `annotations`** (no citations). Until that is resolved upstream, `web_search_preview` is the tool that returns usable citations. +:::tip +Under the default `tool_choice: "auto"`, the model only searches when it judges a query needs it — for a fact it already knows it may answer directly, leaving `annotations` empty. To force a search (and citations), set `tool_choice: "required"`. The older `web_search_preview` tool behaves the same way; prefer the GA `web_search` tool. ::: ### Gemini @@ -207,7 +207,7 @@ Grounding appears on `choices[].message.grounding_metadata` — the search queri ``` :::warning Web search sends data outside your region and compliance boundary -When you enable web search (`web_search_preview` or `google_search`), your query and relevant request context are sent to an external web search provider — Bing for OpenAI, Google Search for Gemini — to fetch results. That data leaves your workspace's home region and falls outside its data-residency and compliance boundary (see [Model location and region restriction](#model-location-and-region-restriction)). Only enable web search for workspaces where that is acceptable. +When you enable web search (`web_search` or `google_search`), your query and relevant request context are sent to an external web search provider — Bing for OpenAI, Google Search for Gemini — to fetch results. That data leaves your workspace's home region and falls outside its data-residency and compliance boundary (see [Model location and region restriction](#model-location-and-region-restriction)). Only enable web search for workspaces where that is acceptable. ::: ## Calling from a Function