Metadata-Version: 2.4
Name: serpapi-search-tools
Version: 0.1.0
Summary: Add live SerpApi search to Python agents and agent SDKs.
Keywords: agents,ai,search,serpapi,tools
Author: SerpApi
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: serpapi>=1.0.0,<2
Requires-Dist: agno>=2.6.19,<3 ; extra == 'agno'
Requires-Dist: openai>=1.0.0,<3 ; extra == 'agno'
Requires-Dist: autogen-agentchat>=0.7.5,<0.8 ; extra == 'autogen'
Requires-Dist: autogen-core>=0.7.5,<0.8 ; extra == 'autogen'
Requires-Dist: autogen-ext[openai]>=0.7.5,<0.8 ; extra == 'autogen'
Requires-Dist: claude-agent-sdk>=0.2.108,<1 ; extra == 'claude-agent-sdk'
Requires-Dist: crewai>=1.6.1,<2 ; python_full_version < '3.14' and extra == 'crewai'
Requires-Dist: agno>=2.6.19,<3 ; extra == 'frameworks'
Requires-Dist: autogen-core>=0.7.5,<0.8 ; extra == 'frameworks'
Requires-Dist: autogen-agentchat>=0.7.5,<0.8 ; extra == 'frameworks'
Requires-Dist: autogen-ext[openai]>=0.7.5,<0.8 ; extra == 'frameworks'
Requires-Dist: claude-agent-sdk>=0.2.108,<1 ; extra == 'frameworks'
Requires-Dist: crewai>=1.6.1,<2 ; python_full_version < '3.14' and extra == 'frameworks'
Requires-Dist: haystack-ai>=2.30.2,<4 ; extra == 'frameworks'
Requires-Dist: langchain>=1.3.11,<2 ; extra == 'frameworks'
Requires-Dist: langchain-core>=1.4.8,<2 ; extra == 'frameworks'
Requires-Dist: langgraph>=1.2.6,<2 ; extra == 'frameworks'
Requires-Dist: llama-index-core>=0.14.22,<0.15 ; extra == 'frameworks'
Requires-Dist: openai>=1.0.0,<3 ; extra == 'frameworks'
Requires-Dist: pydantic-ai>=1.30.1,<3 ; extra == 'frameworks'
Requires-Dist: semantic-kernel>=1.36.0,<2 ; extra == 'frameworks'
Requires-Dist: smolagents>=1.26.0,<2 ; extra == 'frameworks'
Requires-Dist: google-adk>=2.3.0,<3 ; extra == 'google-adk'
Requires-Dist: haystack-ai>=2.30.2,<4 ; extra == 'haystack'
Requires-Dist: langchain>=1.3.11,<2 ; extra == 'langchain'
Requires-Dist: langchain-core>=1.4.8,<2 ; extra == 'langchain'
Requires-Dist: langchain>=1.3.11,<2 ; extra == 'langgraph'
Requires-Dist: langchain-core>=1.4.8,<2 ; extra == 'langgraph'
Requires-Dist: langgraph>=1.2.6,<2 ; extra == 'langgraph'
Requires-Dist: llama-index-core>=0.14.22,<0.15 ; extra == 'llamaindex'
Requires-Dist: agent-framework-openai>=1.10.1,<2 ; extra == 'microsoft-agent-framework'
Requires-Dist: openai-agents>=0.18.3,<1 ; extra == 'openai-agents'
Requires-Dist: pydantic-ai>=1.30.1,<3 ; extra == 'pydantic-ai'
Requires-Dist: openai>=1.0.0,<3 ; extra == 'semantic-kernel'
Requires-Dist: semantic-kernel>=1.36.0,<2 ; extra == 'semantic-kernel'
Requires-Dist: openai>=1.0.0,<3 ; extra == 'smolagents'
Requires-Dist: smolagents>=1.26.0,<2 ; extra == 'smolagents'
Requires-Python: >=3.10
Project-URL: Documentation, https://serpapi.github.io/serpapi-search-tools-python/
Project-URL: Repository, https://github.com/serpapi/serpapi-search-tools-python
Project-URL: Issues, https://github.com/serpapi/serpapi-search-tools-python/issues
Provides-Extra: agno
Provides-Extra: autogen
Provides-Extra: claude-agent-sdk
Provides-Extra: crewai
Provides-Extra: frameworks
Provides-Extra: google-adk
Provides-Extra: haystack
Provides-Extra: langchain
Provides-Extra: langgraph
Provides-Extra: llamaindex
Provides-Extra: microsoft-agent-framework
Provides-Extra: openai-agents
Provides-Extra: pydantic-ai
Provides-Extra: semantic-kernel
Provides-Extra: smolagents
Description-Content-Type: text/markdown

# serpapi-search-tools

[![PyPI version](https://img.shields.io/pypi/v/serpapi-search-tools.svg)](https://pypi.org/project/serpapi-search-tools/)
[![CI](https://github.com/serpapi/serpapi-search-tools-python/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-search-tools-python/actions/workflows/ci.yml)
[![Python versions](https://img.shields.io/pypi/pyversions/serpapi-search-tools.svg)](https://pypi.org/project/serpapi-search-tools/)
[![License: MIT](https://img.shields.io/pypi/l/serpapi-search-tools.svg)](https://github.com/serpapi/serpapi-search-tools-python/blob/main/LICENSE)

[Read the full documentation](https://serpapi.github.io/serpapi-search-tools-python/)
for guides, SDK examples, recipes, and the API reference.

Give Python agents live web, news, maps, image, shopping, video, hotel, and
flight search through small typed tools.

`serpapi-search-tools` connects [SerpApi](https://serpapi.com) to popular Python
agent SDKs. It provides a separate constructor for each kind of search, so you
can give an agent only the capabilities it needs:

```python
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. Each search tool asks for the information it needs:
web search uses a query, hotel search requires stay dates, and flight search
uses airports and travel dates. Inputs are validated before a request is sent
to SerpApi, helping prevent failed searches and unnecessary API usage.

## Supported agent SDKs

| SDK | Install extra / provider | 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:

```bash
pip install serpapi-search-tools
```

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

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

Extras are available for all supported SDKs listed above.

Set a SerpApi key:

```bash
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:

```bash
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.

```python
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: explicit LangChain provider

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

```bash
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.

```python
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(provider="langchain"),
        news_search(provider="langchain"),
        maps_search(provider="langchain"),
    ],
)

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)
```

When LangChain is the only supported SDK installed, these constructors are
also auto-detected, so `web_search()` is enough. Supplying
`provider="langchain"` explicitly is useful when several supported SDKs share
an environment or when you want the integration choice to be visible in code.

For a step-by-step explanation, keys, customization, and troubleshooting, read
the [detailed quickstart](https://serpapi.github.io/serpapi-search-tools-python/user-guide/quickstart.html).

Browse the [runnable examples](https://github.com/serpapi/serpapi-search-tools-python/tree/main/examples)
for focused integrations or the [agent cookbook](https://serpapi.github.io/serpapi-search-tools-python/docs/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` |

Only `web_search` and `shopping_search` expose an `engine` choice to the model.
Every other constructor fixes the engine and presents a schema tailored to that
search intent.

### General web

```python
from serpapi_search_tools import WebSearchEngine, web_search

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

`google_light` is the default because it is a fast general-purpose web search.
Yahoo is routed through its native `p` query parameter; the other supported web
engines use `q`.

### News, maps, images, and videos

```python
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. Place details, reviews, and directions use different SerpApi
APIs and are not part of this search tool.

### Shopping

```python
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`.

### Hotels

```python
from serpapi_search_tools import hotels_search

hotels = hotels_search(provider="function")
result = hotels(
    query="hotels in Kyoto",
    check_in_date="2026-08-01",
    check_out_date="2026-08-04",
    adults=2,
    children=1,
    children_ages=[8],
)
```

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.

### Flights

```python
from serpapi_search_tools import TravelClass, flights_search

flights = flights_search(provider="function")
result = flights(
    departure_id="LAX",
    arrival_id="AUS",
    outbound_date="2026-08-01",
    return_date="2026-08-04",
    travel_class=TravelClass.BUSINESS,
    adults=1,
)
```

`flights_search` requires an origin, destination, and outbound date. Omitting
`return_date` creates a one-way request; including it creates a round trip.
Multi-city searches are not currently supported.

### Explore destinations

```python
from serpapi_search_tools import travel_explore_search

explore = travel_explore_search(provider="function")
result = explore(
    departure_id="JFK",
    arrival_area_id="/m/02j9z",
)
```

Travel Explore requires only a departure identifier. It can also accept an
arrival identifier or area, fixed outbound/return dates, cabin class, and
passenger counts. 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:

```python
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 built-in client raises `SerpApiSearchError` when SerpApi rejects or cannot
complete a request. Its message is sanitized so an API key embedded in an
upstream request URL is replaced with `[REDACTED]`:

```python
from serpapi_search_tools import SerpApiSearchError, web_search

search = web_search(provider="function")
try:
    result = search(query="Python packaging")
except SerpApiSearchError as exc:
    print(f"Search failed: {exc}")
```

Local input errors such as invalid dates or incompatible parameters remain
`ValueError`, so applications can distinguish validation from provider and
transport failures.

## Common factory options

Every constructor accepts:

| Option | Purpose |
| --- | --- |
| `provider` | Defaults to `"auto"`; select an SDK explicitly in multi-SDK environments or use `"function"` for a plain callable |
| `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

- [Google Search](https://serpapi.com/search-api)
- [Google Light](https://serpapi.com/google-light-api)
- [Bing](https://serpapi.com/bing-search-api)
- [Yahoo](https://serpapi.com/yahoo-search-api)
- [DuckDuckGo](https://serpapi.com/duckduckgo-search-api)
- [Google News](https://serpapi.com/google-news-api)
- [Google Maps](https://serpapi.com/google-maps-api)
- [Google Images](https://serpapi.com/google-images-api)
- [Google Shopping](https://serpapi.com/google-shopping-api)
- [Amazon](https://serpapi.com/amazon-search-api)
- [Walmart](https://serpapi.com/walmart-search-api)
- [eBay](https://serpapi.com/ebay-search-api)
- [YouTube](https://serpapi.com/youtube-search-api)
- [Google Hotels](https://serpapi.com/google-hotels-api)
- [Google Flights](https://serpapi.com/google-flights-api)
- [Google Travel Explore](https://serpapi.com/google-travel-explore-api)

SerpApi's complete documentation index is available in
[`llms.txt`](https://serpapi.com/llms.txt).

## More guides

- [Introduction](https://serpapi.github.io/serpapi-search-tools-python/user-guide/introduction.html)
- [Quickstart](https://serpapi.github.io/serpapi-search-tools-python/user-guide/quickstart.html)
- [Choose a search tool](https://serpapi.github.io/serpapi-search-tools-python/user-guide/search_tools.html)
- [Usage and composition](https://serpapi.github.io/serpapi-search-tools-python/user-guide/usage.html)
- [Configuration](https://serpapi.github.io/serpapi-search-tools-python/user-guide/configuration.html)
- [Recipes](https://serpapi.github.io/serpapi-search-tools-python/user-guide/recipes.html)
- [Agent SDKs](https://serpapi.github.io/serpapi-search-tools-python/user-guide/frameworks.html)
- [Agent cookbook](https://serpapi.github.io/serpapi-search-tools-python/docs/cookbook/)
- [Runnable examples](https://serpapi.github.io/serpapi-search-tools-python/docs/sdk-examples/)
