Web search with web_search

web_search gives an agent general webpages from Google, Google Light, Bing, Yahoo, or DuckDuckGo. It is the best default for research that does not require a specialized result type.

When to use it

Use it for background research, documentation, company websites, public facts, and cross-checking sources. Start with google_light when you want fast, compact organic results for an agent.

Choose news_search for current articles, maps_search for places, or shopping_search for products. Those tools return result structures designed for their verticals.

Quick example

from serpapi_search_tools import web_search

tool = web_search()
agent_tools = [tool]

With one supported SDK installed, tool is native to that SDK. For a direct Python callable, use web_search(provider="function").

Inputs the agent can provide

Field Type Required Meaning
query string yes The words or question to search for
engine enum no Search source; omit for the configured default. google_light is fast, google returns richer Google result types, and the other values select that named web source

The package maps the friendly query field to each engine’s native parameter: Google, Google Light, Bing, and DuckDuckGo use q; Yahoo uses p.

Configure the tool

Constructor option Default Use it for
provider "auto" Detect the installed SDK; use "function" for a callable or an explicit SDK name in multi-SDK environments
allowed_engines all five engines Restrict the enum visible to the model
default_engine google_light when allowed Choose the engine used when the model omits engine
default_params None Fix engine parameters such as locale, filters, or pagination in application code
mode compact Return the main web result sections; use SearchResultMode.FULL to keep supporting sections and all fields on retained results
response_format markdown Return Markdown by default, or use SearchResultFormat.JSON for structured fields
result_limit 10 Maximum items kept in each web result list in either mode
api_key None Override the environment-based SerpApi key
timeout None Set the built-in client’s request timeout
client None Supply a testing, caching, logging, or custom HTTP client
include_examples True Include a short invocation hint in the tool description
name "web_search" Give this configured tool a distinct name

For predictable results, expose only the engines your application actually needs:

from serpapi_search_tools import web_search

tool = web_search(
    allowed_engines=["google_light", "bing"],
    default_engine="google_light",
)

Useful SerpApi parameters

default_params is forwarded to the selected engine and is not editable by the model. This Google Light-only tool fixes country and language while result_limit bounds the returned result list:

from serpapi_search_tools import web_search

us_web = web_search(
    allowed_engines=["google_light"],
    default_params={"gl": "us", "hl": "en"},
    result_limit=5,
    name="us_web_search",
)

Common needs include locale, geographic targeting, pagination, safe search, and date filters. Parameter names and accepted values differ by engine. If you need engine-specific defaults, create separate tool instances instead of sending one default_params dictionary to several incompatible engines.

Use result_limit for a consistent limit across web engines. A DuckDuckGo-only tool can also use default_params={"m": 20} to control how many results DuckDuckGo retrieves. Pagination parameters differ by engine; see the linked API references for supported values.

What comes back

Both modes keep up to result_limit items in each web result list (10 by default). Compact mode returns organic_results and available answer sections. Google Light may also return related questions, related searches, and top stories. Metadata, parameters, pagination, and other supporting sections are omitted.

Result sections are optional. Use mode=SearchResultMode.FULL when application code needs supporting response sections or additional result fields. Add result_limit=None to keep every returned result.

Common mistakes

  • Adding a vertical engine such as google_news to allowed_engines. Use its dedicated constructor instead.
  • Applying Google-only default_params while Bing, Yahoo, or DuckDuckGo is still allowed.
  • Setting engine inside default_params. Choose available engines with allowed_engines and default_engine.
  • Combining incompatible location fields. The package catches common conflicts, but each engine’s official reference remains the source of truth.

Official SerpApi documentation

See regional tool instances and the general research recipe for larger examples.