Run an example

The repository contains direct Python examples and runnable agent examples for every supported SDK.

Start without an LLM

Use the direct examples to verify credentials and request construction:

uv run --isolated --no-project --with serpapi-search-tools --with python-dotenv examples/direct_search.py
uv run --isolated --no-project --with serpapi-search-tools --with python-dotenv examples/direct_travel.py

They demonstrate general web, news, hotels, flights, and travel exploration without installing an agent framework.

Pick a scenario

Scenario	Script	Credentials	What to look for
Multi-vertical research	direct_multi_search.py	SerpApi	Four result families reduced to short title lists
Marketplace comparison	direct_marketplace_comparison.py	SerpApi	Product payloads normalized into title, price, and link
Regional configuration	direct_regioned_search.py	SerpApi	Two named tools with separate US and German defaults
Cached requests	direct_cached_search.py	SerpApi	First call is a cache miss; the identical second call is a cache hit
Agent travel planning	openai_agents_travel_planner.py	SerpApi and OpenAI	Explore, round-trip flights, and hotel occupancy in one prompt

Run the direct scenarios from the project root:

uv run --isolated --no-project --with serpapi-search-tools --with python-dotenv examples/direct_multi_search.py
uv run --isolated --no-project --with serpapi-search-tools --with python-dotenv examples/direct_marketplace_comparison.py
uv run --isolated --no-project --with serpapi-search-tools --with python-dotenv examples/direct_regioned_search.py
uv run --isolated --no-project --with serpapi-search-tools --with python-dotenv examples/direct_cached_search.py

The direct scripts parse the compact JSON response and print bounded summaries.

Structured travel defaults

Applications can configure localization and currency when each tool is created:

from serpapi_search_tools import flights_search, hotels_search, travel_explore_search

hotels = hotels_search(
    provider="function",
    default_params={"currency": "USD", "gl": "us"},
)
flights = flights_search(
    provider="function",
    default_params={"currency": "USD", "hl": "en"},
)
explore = travel_explore_search(
    provider="function",
    default_params={"currency": "USD", "gl": "us"},
)

Run an agent example

Set SERPAPI_API_KEY plus the model provider key used by the script, then run the published package with the matching optional extra from the project root:

uv run --isolated --no-project --with 'serpapi-search-tools[openai-agents]' --with python-dotenv examples/openai_agents_openai.py
uv run --isolated --no-project --with 'serpapi-search-tools[openai-agents]' --with python-dotenv examples/openai_agents_travel_planner.py

The examples/ directory includes OpenAI Agents, Pydantic AI, LangChain, LangGraph, CrewAI, LlamaIndex, Claude Agent SDK, Microsoft Agent Framework, AutoGen, Haystack, Agno, smolagents, Google ADK, and Semantic Kernel examples.

In an application with one supported SDK installed, pass a list of capability-specific tools and rely on automatic detection:

from serpapi_search_tools import maps_search, news_search, web_search

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

Open SDK examples for installation and complete copy-friendly code for each framework. See Choose a search tool to choose the right constructors before assembling the list, or start from a recipe.

Useful first prompts

• “Search current news for three Python packaging releases and summarize why they matter.”
• “Find well-reviewed coffee shops near the Seattle Convention Center.”
• “Compare one-way flights from LAX to AUS on 2030-08-01.”
• “Find hotels in Kyoto from 2030-08-01 to 2030-08-04 for two adults.”

Structured prompts are especially useful for a first travel run because they provide the dates and identifiers required by the tool schema.