Skip to content

docs(ai-gateway): recommend GA web_search tool; correct annotations note #159

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

Merged
anukiransolur merged 1 commit into from
Jul 9, 2026
Merged

docs(ai-gateway): recommend GA web_search tool; correct annotations note #159

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 5 additions & 5 deletions docs/guides/ai-gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand All @@ -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" }]
}'
```

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading