Metadata-Version: 2.4
Name: serpapi-search-tools
Version: 1.0.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 :: 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: mistune>=3.1.0,<4
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.

The package creates native [SerpApi](https://serpapi.com) tools for popular Python agent SDKs:

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

## 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 below.

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.

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

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

`images_search` returns images and their source pages. `videos_search` searches YouTube videos, Shorts, channels, playlists, movies, and categories.

### Shopping

```python
from serpapi_search_tools import ShoppingSearchEngine, shopping_search

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

Use the same `query` input for every marketplace. The package translates it to the selected engine's request format.

### 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. Read the [Hotels](https://serpapi.github.io/serpapi-search-tools-python/user-guide/hotels_search.html), [Flights](https://serpapi.github.io/serpapi-search-tools-python/user-guide/flights_search.html), and [Travel Explore](https://serpapi.github.io/serpapi-search-tools-python/user-guide/travel_explore_search.html) guides for their date, occupancy, location ID, and trip rules.

## Configure tools

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 mode is the default, while full mode keeps supporting sections and all fields on retained results |
| `response_format`  | Output serialization; Markdown is the default, while `SearchResultFormat.JSON` returns compact or full JSON text |
| `result_limit`     | Maximum items kept in each result list in either mode; defaults vary by tool; use `None` for all results |

`web_search` and `shopping_search` also accept `allowed_engines` and `default_engine`. The tool offers only the engine values you configure.

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

Tools return Markdown by default. Markdown keeps links and tables readable without JSON syntax overhead. Application code that needs structured fields can opt into JSON:

```python
import json

from serpapi_search_tools import SearchResultFormat, web_search

search = web_search(
    provider="function",
    response_format=SearchResultFormat.JSON,
)
result = json.loads(search(query="Python packaging"))
```

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

Typed tool inputs override matching values in `default_params`, and the constructor always controls `engine`. The package rejects known incompatible combinations, such as a Google News query with a topic token, an Amazon keyword search with `node`, or flight airline include and exclude filters. A multi-engine tool sends the same defaults to every allowed engine, so use parameters shared by those engines or create separate tool instances. Reserved keys (`api_key`, `async`, `engine`, and `output`) are rejected in `default_params`; use the constructor options above instead.

Read [Manage LLM context](https://serpapi.github.io/serpapi-search-tools-python/user-guide/managing_llm_context.html) for compact and full response behavior, default result limits, and unlimited responses.

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

## Engine API references

<details>
<summary>Show supported SerpApi engines</summary>

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

</details>

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

- [Full documentation](https://serpapi.github.io/serpapi-search-tools-python/)
- [SDK examples](https://serpapi.github.io/serpapi-search-tools-python/docs/sdk-examples/)
- [Agent cookbook](https://serpapi.github.io/serpapi-search-tools-python/docs/cookbook/)
