Configure a search tool

Every public constructor follows the same pattern: choose the search capability, let the package detect your agent SDK, and add only the application-controlled defaults you need.

from serpapi_search_tools import web_search

tool = web_search()

Start with no options. Add configuration only when you have a clear reason, such as restricting engines, fixing a locale, limiting results, setting a currency, or selecting one SDK from a multi-SDK environment.

Three kinds of settings

It helps to keep three layers separate:

Model inputs are fields the agent supplies at invocation time, such as query, hotel dates, or flight airports. Each dedicated tool page lists these fields.
Constructor options control how the Python tool is created, such as provider, name, timeout, and web-engine choices.
default_params are SerpApi engine parameters fixed by your application, such as language, country, currency, safe search, or result count.

This separation keeps the agent’s search inputs short while your application retains control of service-level settings.

Common constructor options

All nine constructors accept these options:

Option	Default	When to use it
`provider`	`"auto"`	Usually omit it. Select an SDK explicitly when multiple supported SDKs are installed, or use `"function"` for a callable.
`api_key`	`None`	Pass a SerpApi key from a secret manager instead of using an environment variable.
`client`	`None`	Replace the built-in client for tests, caching, logging, retries, or response reduction.
`default_params`	`None`	Set supported SerpApi options such as locale, currency, or result count in application code.
`timeout`	`None`	Set a request timeout on the built-in SerpApi client.
`mode`	SearchResultMode.COMPACT	Return focused, bounded result families for agents, or opt into the untouched response with SearchResultMode.FULL.
`include_examples`	`True`	Keep or remove the short invocation hint in the tool description.
`name`	constructor name	Give separately configured tools distinct names the model can understand.

from serpapi_search_tools import news_search

current_us_news = news_search(
    default_params={"hl": "en", "gl": "us", "num": 5},
    timeout=20.0,
    name="current_us_news",
)

Automatic SDK detection

When exactly one supported agent SDK is installed, omit provider:

from serpapi_search_tools import maps_search, web_search

tools = [web_search(), maps_search()]

If multiple supported SDK families share an environment, automatic detection raises an error instead of silently choosing one. Make the selection explicit:

from serpapi_search_tools import maps_search, web_search

tools = [
    web_search(provider="openai-agents"),
    maps_search(provider="openai-agents"),
]

LangGraph and LangChain count as one adapter family because both use the LangChain structured-tool adapter.

If no supported SDK is installed, automatic detection returns a normal Python callable. provider="function" requests that callable explicitly and is useful for scripts, tests, and custom integrations.

Options that differ by tool

The search inputs and useful SerpApi parameters depend on the capability:

Tool	Tool-specific configuration
`web_search`	`allowed_engines`, `default_engine`, plus per-engine web defaults
`news_search`	Google News query-mode locale and result settings
`maps_search`	Typed location/zoom/nearby inputs plus Maps defaults
`images_search`	Safe search and image filters
`shopping_search`	`allowed_engines`, `default_engine`, and marketplace-specific defaults
`videos_search`	YouTube locale and filter token settings
`hotels_search`	Typed stay/occupancy fields plus currency and property filters
`flights_search`	Typed route/passenger fields plus currency, airline, bag, stop, and time filters
`travel_explore_search`	Typed destination constraints plus discovery filters

Read the dedicated page before adding engine-specific default_params.

Choose compact or full results

All tools default to SearchResultMode.COMPACT. Compact mode normally removes response metadata, parameters, pagination, filters, and other auxiliary sections. It keeps errors and at most five entries from each primary result family. If a successful response contains no recognized result family, it returns no_results: true plus only safe status and search-information fields instead of an ambiguous empty object.

Tool	Compact result families
web_search except Google Light	`answer_box`, `knowledge_graph`, `ai_overview`, `organic_results`
web_search with Google Light	`answer_box`, `knowledge_graph`, `organic_results`, `related_questions`, `related_searches`, `top_stories`
news_search	`news_results`
maps_search	`local_results`
images_search	`images_results`
shopping_search	`shopping_results` for Google Shopping; `organic_results` for Amazon, Walmart, and eBay
videos_search	`video_results`
hotels_search	`properties`
flights_search	`best_flights`, `other_flights`
travel_explore_search	`destinations`

Use full mode in application code that needs an auxiliary response section:

from serpapi_search_tools import SearchResultMode, web_search

debug_search = web_search(
    provider="function",
    mode=SearchResultMode.FULL,
)

mode is a constructor option, not a model input. An agent cannot expand its own tool response and unexpectedly consume more context.

Restrict web and shopping engines

Only web_search and shopping_search expose an engine choice to the model. Their constructor options define the exact enum in the generated schema:

from serpapi_search_tools import WebSearchEngine, web_search

tool = web_search(
    allowed_engines=[WebSearchEngine.GOOGLE_LIGHT, WebSearchEngine.BING],
    default_engine=WebSearchEngine.GOOGLE_LIGHT,
)

web_search supports five general web engines and prefers google_light. shopping_search supports four commerce engines and prefers google_shopping. Fixed-engine tools do not show the model an engine field.

Use `default_params` safely

These values are controlled by your Python application:

from serpapi_search_tools import images_search

safe_us_images = images_search(
    default_params={"safe": "active", "hl": "en", "gl": "us"},
)

Typed tool fields, including their declared defaults, win over matching default_params, and the package always controls engine. The following transport parameters are reserved and rejected in default_params:

api_key
async
engine
output

A multi-engine tool sends the same defaults to every allowed engine. Parameter names and valid values often differ, so use only shared defaults or create separate tool instances with clear names:

from serpapi_search_tools import web_search

us_google = web_search(
    allowed_engines=["google_light"],
    default_params={"hl": "en", "gl": "us", "num": 5},
    name="us_google",
)
german_google = web_search(
    allowed_engines=["google_light"],
    default_params={"hl": "de", "gl": "de", "num": 5},
    name="german_google",
)

Official engine references are linked from every dedicated tool page.

API keys

Set the key in your local shell:

export SERPAPI_API_KEY="your-serpapi-key"

SERPAPI_KEY is also accepted. Generic variables such as API_KEY are ignored so a model-provider credential cannot be sent to SerpApi accidentally.

The key is resolved when a real search runs. Creating a tool or inspecting its schema does not contact SerpApi. In production, you can pass api_key= using a value read from your secret manager.

Custom clients

Pass client= for deterministic tests, caching, logging, retries, or a company HTTP wrapper. The object needs one synchronous search(params) method:

import json

from serpapi_search_tools import SearchResultMode, hotels_search


class RecordingClient:
    def __init__(self):
        self.requests = []

    def search(self, params):
        self.requests.append(params)
        return {"search_metadata": {"status": "Success"}, "params": params}


client = RecordingClient()
search = hotels_search(
    provider="function",
    client=client,
    mode=SearchResultMode.FULL,
)
result = json.loads(
    search(
        query="hotels in Kyoto",
        check_in_date="2030-08-01",
        check_out_date="2030-08-04",
    )
)
print(result["params"])

When a custom client is supplied, the package does not create the built-in client or read a SerpApi key.

Use another agent SDK

Request a normal callable and wrap it with the SDK’s documented custom-tool API:

from serpapi_search_tools import flights_search

search_flights = flights_search(provider="function")

tool = CustomTool(
    name=search_flights.__name__,
    description=search_flights.__doc__,
    function=search_flights,
)

The callable carries a typed Python signature. Follow your SDK’s custom-tool guide and use the inputs documented on the matching search-tool page. If the SDK asks for JSON Schema, define those same fields explicitly.

For complete combinations built from these options, continue with Recipes or Runnable examples.