Metadata-Version: 2.4
Name: serpapi-search-tools
Version: 0.1.1
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 :: 4 - Beta
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?v=1)](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?v=1)](https://pypi.org/project/serpapi-search-tools/)
[![License: MIT](https://img.shields.io/pypi/l/serpapi-search-tools.svg?v=1)](https://github.com/serpapi/serpapi-search-tools-python/blob/main/LICENSE)

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](https://serpapi.github.io/serpapi-search-tools-python/)
for guides, SDK examples, recipes, and the API reference.

`serpapi-search-tools` connects [SerpApi](https://serpapi.com) to popular Python agent SDKs. Enhance your AI agent with real-time search data across 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.

## 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:

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

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(),
        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](https://serpapi.github.io/serpapi-search-tools-python/user-guide/frameworks.html).

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

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

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

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

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

### Travel

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

```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 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](https://serpapi.github.io/serpapi-search-tools-python/user-guide/debugging.html) 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

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

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

## 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/)
