Developer documentation/Tools and integrations

Web search

Give an agent a built-in tool for finding current information on the web.

Agents API3 min read

On this page

Enable web search Configure result size and domains Search filters the model can use Current limits Read results

Web search gives the Agent a built-in tool for finding current information. It does not require a managed environment and never allocates a Sandbox.

Enable web search

javascript

const agent = await client.beta.agents.create({
  model: 'gpt-6-luna',
  tools: [{ type: 'web_search' }],
});

Add it to a saved Agent or a Session the same way as any other tool. Omitting web_search from a Session's explicit tool override removes it, like any other tool.

Configure result size and domains

javascript

tools: [{
  type: 'web_search',
  context_size: 'high',
  allowed_domains: ['docs.example.com'],
}]

context_size bounds both result count and snippet length: low (3 results, up to 1,000 characters each), medium (6 results, up to 2,000 characters), or high (10 results, up to 4,000 characters). It defaults to medium.

allowed_domains accepts up to 100 bare hostnames, matches their subdomains, and is enforced on the returned URLs. Omit it, or pass an empty or null list, to leave search unrestricted.

Each search call can narrow results. The model chooses these per query:

Argument	Meaning
`time_range`	Recency: `d<n>`, `w<n>`, `m<n>` or `y<n>` for the last n days, weeks, months or years. For example, `d1` finds news from the last day.
`start_date`, `end_date`	Explicit publish-date range, `YYYY-MM-DD`, inclusive. Use both together, and not with `time_range`.
`vertical`	`finance` for markets, companies, earnings and filings; `code` for programming questions.
`include_sites`, `exclude_sites`	Up to 20 domains each. Subdomains match.

When allowed_domains is set, it stays a hard boundary. The model can narrow it with include_sites but cannot search outside it. Invalid filter combinations return an error to the model, so it can correct the call.

Each result has title, link, site_name, published_at (UTC, when known) and snippet. The snippet holds the parts of the page most relevant to the query.

Current limits

A non-null location is rejected with 400; the current search provider does not implement location targeting. mode: "cached" is accepted and runs as "live", since the current provider only performs live queries; reading the tool back reports mode: "live". mode: "disabled" exposes no search tool to the model. Web search does not open full pages and does not return image content.

Read results

Search activity appears as a web_search_call item with a stable ID and output index, its search action, and added/done lifecycle events. A failed search reports incomplete status with its error, which is also returned to the model. Results enter the Session's history together with their source URLs.

Continue with MCP connections for external, credentialed tools.

Protocol referenceOpenAI Agents API ↗