Skip to main content
The Web Search tool allows LLMs to search the web and retrieve information from web pages. This tool is supported for OpenAI and Anthropic providers, enabling models to access real-time information from the internet.

Overview

The Web Search tool enables models to:
  • Search the web for information
  • Open and read specific web pages
  • Find specific content within web pages
When a model uses the web search tool, it can retrieve up-to-date information that wasn’t part of its training data, making it ideal for queries about current events, recent developments, or specific web content.

Defining the Web Search Tool

To enable web search capabilities, add the WebSearchTool to your request’s Tools array:

Tool Parameters

Domain Filtering

You can restrict web searches to specific domains using the Filters parameter:

User Location

Specify the user’s location to get localized search results:
Include the web search tool in your request:

Handling Web Search Calls

When the model decides to use web search, it will return a WebSearchCallMessage in the response output. You can detect and process these calls:

Web Search Action Types

The web search tool supports three types of actions:

1. Search Action

Performs a web search query:

2. Open Page Action

Opens and reads a specific web page:

3. Find Action

Searches for specific content within a web page:

Streaming Web Search Calls

When using streaming responses, web search calls are delivered through specific chunk types:

Complete Example

Here’s a complete example demonstrating web search usage:

Provider Support

The Web Search tool is supported by the following providers:

Best Practices

  1. Use appropriate search context size: Choose "low" for quick searches, "medium" for balanced results, or "high" for comprehensive information.
  2. Domain filtering: When you need information from specific sources, use domain filters to ensure the model only searches within trusted domains.
  3. User location: Specify user location when you need localized results (e.g., local news, regional information).
  4. Error handling: Always check the Status field of WebSearchCallMessage to handle cases where the search might have failed.
  5. Streaming: For better user experience, use streaming responses to show search progress in real-time.

Limitations

  • Web search results depend on the search engine’s capabilities and may vary by provider
  • Some websites may block automated access
  • Search results may not always be up-to-date or accurate
  • Rate limits may apply depending on your provider and plan