# Web search

Let the agent query the live web through OpenAI's hosted web search tool.

## Overview

`web_search` is a **hosted tool**: the search runs inside OpenAI's Responses API, not on our backend. The LLM decides on each turn whether to issue a query, reads the returned snippets, and folds them into its answer (usually with inline citations).

Use it when the agent needs information that is recent, public, and not already in its training data — pricing pages, news, documentation, regulations, sports scores. Skip it for anything private (use `file_search`) or transactional (use `function`).

**Requires an OpenAI model.** The hosted web search tool is only available when the agent's model is set to an OpenAI model (e.g. `gpt-4.1`, `gpt-4o`, `o4-mini`). When Web Search is attached, DeepSeek models (`deepseek-v4-flash`, `deepseek-v4-pro`) are greyed out in the model dropdown — and a DeepSeek selection switches back to an OpenAI model automatically.

## Configuration

| Field | Values | Notes |
| --- | --- | --- |
| Search context size | `low`, `medium`, `high` | How much retrieved web content the model is allowed to read. Higher = better answers, more tokens, slower. Default `medium`. |
| Allowed domains | List of hostnames | Restricts results to these domains only. Leave empty to search the whole web. |
| User location | country, region, city, timezone | Hints location so local queries ("restaurants near me") work. Sent as an *approximate* hint, never as a precise coordinate. |

Only **one** `web_search` tool may be attached to an agent — adding a second is a no-op.

## Example

Agent system prompt:

```
You are a research assistant. When the user asks about current events,
search the web and cite your sources.
```

User turn: *"What did the European Central Bank decide at its last meeting?"*

The model issues a web_search call:

```json
{ "query": "ECB last monetary policy meeting decision" }
```

The hosted tool returns ranked snippets + URLs. The model then replies with a paragraph that cites `ecb.europa.eu` and `reuters.com` inline.

## Best practices

- **Tell the agent when to search.** Without a hint in the system prompt the model may answer from its training data and skip the tool. A line like *"For anything dated, search the web first"* fixes this.
- **Set `searchContextSize` deliberately.** `high` can multiply the response cost by 5–10x; reserve it for research workflows. `low` is fine for fact lookups.
- **Use allowed-domains for trust.** A support agent that should only quote your own docs becomes much safer with `allowedDomains: ["docs.acme.com"]`.
- **Watch the token bill.** Web search responses count toward input tokens. A noisy chat loop with web_search at `high` is the #1 source of surprise OpenAI bills.

## Gotchas

- The editor blocks the DeepSeek + Web Search combination (options greyed out, automatic fallback to an OpenAI model). Configs built outside the editor still fail at runtime with an explicit error.
- The hosted tool occasionally returns no results for very recent events (indexing lag). Retry with a more specific query.
- Citations come from OpenAI's renderer; we surface them as-is in the execution log.

---

*Source: https://agentbuilder.systalink.sn/docs/tool-web-search — human documentation.*
*Other language: [/docs-md/fr/tool-web-search.md](/docs-md/fr/tool-web-search.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*