Skip to content
BranchesTags

Repository files navigation

SerpApi Search Tools

PyPI version CI Python versions License: MIT

Give Python AI agents live web, news, maps, image, shopping, video, hotel, and flight search with easy-to-use, customizable tools.

Read the full documentation for guides, SDK examples, recipes, and the API reference.

serpapi-search-tools connects SerpApi to popular Python agent SDKs. Enhance your AI agent with real-time search data across the capabilities it needs:

from serpapi_search_tools import maps_search, news_search, web_search

tools = [
    web_search(),
    news_search(),
    maps_search(),
]

When one supported agent SDK is installed, the package detects it and creates tools ready for that SDK.

Supported agent SDKs

SDK Install extra Returned tool
OpenAI Agents SDK openai-agents OpenAI Agents FunctionTool
Pydantic AI pydantic-ai Pydantic AI Tool
LangChain langchain LangChain StructuredTool
LangGraph langgraph LangChain-compatible structured tool
CrewAI crewai CrewAI BaseTool
LlamaIndex llamaindex LlamaIndex FunctionTool
Claude Agent SDK claude-agent-sdk Claude SDK MCP tool
Microsoft Agent Framework microsoft-agent-framework Microsoft Agent Framework FunctionTool
AutoGen autogen AutoGen FunctionTool
Haystack haystack Haystack Tool
Semantic Kernel semantic-kernel Semantic Kernel function
Agno agno Agno Function
smolagents smolagents smolagents Tool
Google ADK google-adk Google ADK FunctionTool

Install

If your agent SDK is already installed, add only the base package:

pip install serpapi-search-tools

If you want this package to install a compatible agent SDK too, choose its extra. For example:

pip install "serpapi-search-tools[openai-agents]"

Extras are available for all supported SDKs listed above.

Set a SerpApi key:

export SERPAPI_API_KEY="your-key"

SERPAPI_KEY is also supported. A directly supplied api_key= takes precedence over environment variables.

Quickstart: automatic SDK detection

This quickstart uses OpenAI Agents SDK to demonstrate automatic detection. It assumes the SDK is already installed in your environment (install it with pip install openai-agents if needed). Then add the base package:

pip install serpapi-search-tools

With one supported SDK installed, create the tool without any configuration. The package detects OpenAI Agents SDK and returns its native FunctionTool. This example also expects the OPENAI_API_KEY used by your agent.

from agents import Agent, Runner

from serpapi_search_tools import web_search

agent = Agent(
    name="research-agent",
    instructions="Use web search when the answer needs current information.",
    tools=[web_search()],
)

result = Runner.run_sync(
    agent,
    "Find three recent Python packaging changes and explain why they matter.",
)
print(result.final_output)

Quickstart: LangChain

Install the LangChain extra and the model backend used by this example:

pip install "serpapi-search-tools[langchain]" langchain-openai

The langchain extra installs a compatible LangChain version. langchain-openai provides this example's model integration; replace it with the backend your LangChain application uses. With langchain-openai, set OPENAI_API_KEY before running the agent.

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

from serpapi_search_tools import maps_search, news_search, web_search

agent = create_agent(
    model=ChatOpenAI(model="gpt-5.4-mini", temperature=0),
    tools=[
        web_search(),
        news_search(),
        maps_search(),
    ],
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Research coffee culture in Austin using current reporting, "
                    "local places, and general web sources."
                ),
            }
        ]
    }
)
print(result["messages"][-1].content)

The constructors use automatic SDK detection, just as in the first quickstart. For multi-SDK environments and explicit selection, see Agent SDKs.

For a step-by-step explanation, keys, customization, and troubleshooting, read the detailed quickstart.

Browse the runnable examples for focused integrations or the agent cookbook for complete, task-oriented agents built with every supported SDK.

Choose the right tool

Constructor SerpApi engine(s) Required search inputs
web_search google, google_light, bing, yahoo, duckduckgo query
news_search google_news query
maps_search google_maps query
images_search google_images query
shopping_search google_shopping, amazon, walmart, ebay query
videos_search youtube query
hotels_search google_hotels query, check_in_date, check_out_date
flights_search google_flights departure_id, arrival_id, outbound_date
travel_explore_search google_travel_explore departure_id

General web

from serpapi_search_tools import WebSearchEngine, web_search

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

SerpApi supports multiple general web search engines, including Google Light, Google, Bing, Yahoo, and DuckDuckGo. Google Light is the default because it provides fast, general-purpose web results. Use allowed_engines to choose which engines are available and default_engine to select the initial one.

News, maps, images, and videos

from serpapi_search_tools import images_search, maps_search, news_search, videos_search

tools = [
    news_search(),
    maps_search(),
    images_search(),
    videos_search(),
]

news_search supports keyword searches in Google News. maps_search searches Google Maps and accepts optional location, zoom (3 through 30), and nearby fields. Use nearby=True for “near me” intent with a separate location; leave it false when the query already names a city or area. Place details, reviews, and directions use different SerpApi APIs and are not part of this search tool.

Shopping

from serpapi_search_tools import ShoppingSearchEngine, shopping_search

tool = shopping_search(
    allowed_engines=[
        ShoppingSearchEngine.GOOGLE_SHOPPING,
        ShoppingSearchEngine.AMAZON,
        ShoppingSearchEngine.WALMART,
        ShoppingSearchEngine.EBAY,
    ],
)

The package routes one human query to each marketplace's native field: Google Shopping uses q, Amazon uses k, Walmart uses query, and eBay uses _nkw.

Travel

from serpapi_search_tools import flights_search, hotels_search, travel_explore_search

travel_tools = [
    hotels_search(),
    flights_search(),
    travel_explore_search(),
]

These constructors create hotel, flight, and destination-discovery tools for the detected agent SDK.

Hotels

hotels_search lets the agent provide a destination, dates, and guest details. Hotel dates use YYYY-MM-DD. Checkout must be after check-in. When children is nonzero, provide exactly one age from 1 through 17 per child; use 1 for a child under one year old.

Flights

flights_search lets the agent provide route, date, cabin, and passenger details. It requires an origin, destination, and outbound date. Omitting return_date creates a one-way request; including it creates a round trip. Use specific airport IATA codes such as LHR and CDG, not metropolitan codes such as LON and PAR. For a city-wide search, use a Google Knowledge Graph location ID (KGMID) beginning with /m/ or /g/, such as /m/04jpl for London or /m/05qtj for Paris. Multi-city searches are not currently supported.

Explore destinations

travel_explore_search lets the agent discover destinations and requires only a departure airport IATA code or city KGMID. It can also accept a specific arrival airport or city through arrival_id, or a region or country KGMID through arrival_area_id. Fixed outbound/return dates, cabin class, and passenger counts are optional. These travel tools send their route and date fields directly to the matching SerpApi endpoint.

Set advanced parameters in application code

Use default_params for documented SerpApi settings that should stay under your application's control, such as locale, currency, safe search, or result count. The agent continues to supply only the inputs described by its search tool.

Applications can supply documented advanced options at construction time:

tool = news_search(
    default_params={"hl": "en", "gl": "us"},
)

Typed fields and the constructor-controlled engine override colliding entries in default_params. Known incompatible combinations are rejected locally, such as Google News query plus topic tokens, Amazon keyword search plus node, or flight airline include plus exclude filters. For a multi-engine tool, the same defaults are sent to every allowed engine. Use only parameters shared by those engines, or create separate tool instances when each engine needs different defaults. Reserved keys (api_key, async, engine, and output) are rejected in default_params; use the constructor options documented below instead.

Handle search failures

The search runtime raises SerpApiSearchError for SerpApi and transport failures. Invalid tool inputs raise ValueError. Agent SDKs surface or handle tool errors differently, so use your SDK's normal tool-error mechanism. See Debugging for detailed examples.

Common factory options

Every constructor accepts:

Option Purpose
provider Defaults to "auto"; select an SDK explicitly only when multiple supported SDKs share an environment
include_examples Include or omit a short example in the model description
api_key Explicit SerpApi key
client Custom object with search(params) for caching, interception, or tests
default_params Application-controlled SerpApi options
timeout Timeout passed to the SerpApi SDK client
name Tool name presented to the model
mode Result detail level: "compact" (default) or "full"

web_search and shopping_search additionally accept allowed_engines and default_engine. The tool offers only the engine values you configured.

Supported engine documentation

For AI coding agents that need broader SerpApi API context, use SerpApi's agent-friendly documentation index (llms.txt). It links directly to Markdown API references, including APIs beyond those wrapped by this package.

More guides

About

Real-time web search tools for Python agents, powered by SerpApi with native support for popular agent SDKs.

serpapi.github.io/serpapi-search-tools-python/

Resources

Readme
MIT license

Contributing

Contributing
Activity
Custom properties

Stars

9 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages