Repository Public
1# Web search23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Use web search when your agent needs to look up information to answer a question or complete a task.67## Example: Explain why Mars looks red89Send this JSON body to `POST /v1/agents/sessions` to create a session and stream the answer. It enables web search in `live` mode:1011```json12{13 "agent": {14 "model": "gpt-6-astra",15 "reasoning": { "effort": "low" },16 "tools": [{ "type": "web_search", "mode": "live" }]17 },18 "environment": { "type": "none" },19 "input": "Search NASA's website for why Mars looks red. Explain it in two sentences and include a source link.",20 "stream": true21}22```2324### Result2526In a test run on September 10, 2026, the agent searched NASA's website and streamed this answer:2728> Mars looks red because iron minerals in its soil oxidize, or rust, giving the surface a reddish color. This rusty appearance is why it’s called the “Red Planet,” according to [NASA’s Mars Facts](https://science.nasa.gov/mars/facts/).2930This is a recorded example. Your answer may vary.3132If you leave `web_search` out of `agent.tools`, built-in web search is off. Asking for a search in the prompt does not turn it on.3334## Search mode3536- **`live` (default)**: Allow search to access the live internet. Used when you include `web_search` but leave out `mode`.37- **`cached`**: Search saved web content without accessing the live internet.38- **`disabled`**: Turn off built-in web search, just like leaving the tool out.3940## Optional settings4142Add these fields to the same `web_search` entry:4344| Setting | What it does | If omitted |45| ----------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |46| `context_size` | How much information from search the model receives: `low`, `medium`, or `high`. | Uses `medium`. |47| `allowed_domains` | Which websites search may include. Provide up to **100 domain names**, such as `["python.org", "docs.python.org"]`. | No domain filter is applied. |48| `location` | Helps tailor results to a place. Accepts `country`, `region`, `city`, and `timezone`. | No location is supplied to search. Missing location details may lead to less relevant results or no useful matches for local searches. |