Web search

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Use web search when your agent needs to look up information to answer a question or complete a task.

Example: Explain why Mars looks red

Send this JSON body to POST /v1/agents/sessions to create a session and stream the answer. It enables web search in live mode:

{
  "agent": {
    "model": "gpt-6-astra",
    "reasoning": { "effort": "low" },
    "tools": [{ "type": "web_search", "mode": "live" }]
  },
  "environment": { "type": "none" },
  "input": "Search NASA's website for why Mars looks red. Explain it in two sentences and include a source link.",
  "stream": true
}

Result

In a test run on September 10, 2026, the agent searched NASA's website and streamed this answer:

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.

This is a recorded example. Your answer may vary.

If 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.

Search mode

• live (default): Allow search to access the live internet. Used when you include web_search but leave out mode.
• cached: Search saved web content without accessing the live internet.
• disabled: Turn off built-in web search, just like leaving the tool out.

Optional settings

Add these fields to the same web_search entry: