> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brave Search Tools

> A suite of tools for querying the Brave Search API — covering web, news, image, and video search.

# Brave Search Tools

## Description

CrewAI offers a family of Brave Search tools, each targeting a specific [Brave Search API](https://brave.com/search/api/) endpoint.
Rather than a single catch-all tool, you can pick exactly the tool that matches the kind of results your agent needs:

| Tool                            | Endpoint     | Use case                                                                             |
| ------------------------------- | ------------ | ------------------------------------------------------------------------------------ |
| `BraveWebSearchTool`            | Web Search   | General web results, snippets, and URLs                                              |
| `BraveNewsSearchTool`           | News Search  | Recent news articles and headlines                                                   |
| `BraveImageSearchTool`          | Image Search | Image results with dimensions and source URLs                                        |
| `BraveVideoSearchTool`          | Video Search | Video results from across the web                                                    |
| `BraveLocalPOIsTool`            | Local POIs   | Find points of interest (e.g., restaurants)                                          |
| `BraveLocalPOIsDescriptionTool` | Local POIs   | Retrieve AI-generated location descriptions                                          |
| `BraveLLMContextTool`           | LLM Context  | Pre-extracted web content optimized for AI agents, LLM grounding, and RAG pipelines. |

All tools share a common base class (`BraveSearchToolBase`) that provides consistent behavior — rate limiting, automatic retries on `429` responses, header and parameter validation, and optional file saving.

<Note>
  The older `BraveSearchTool` class is still available for backwards compatibility, but it is considered **legacy** and will not receive the same level of attention going forward. We recommend migrating to the specific tools listed above, which offer richer configuration and a more focused interface.
</Note>

<Note>
  While many tools (e.g., *BraveWebSearchTool*, *BraveNewsSearchTool*, *BraveImageSearchTool*, and *BraveVideoSearchTool*) can be used with a free Brave Search API subscription/plan, some parameters (e.g., `enable_snippets`) and tools (e.g., *BraveLocalPOIsTool* and *BraveLocalPOIsDescriptionTool*) require a paid plan. Consult your subscription plan's capabilities for clarification.
</Note>

## Installation

```shell theme={null}
pip install 'crewai[tools]'
```

## Getting Started

1. **Install the package** — confirm that `crewai[tools]` is installed in your Python environment.
2. **Get an API key** — sign up at [api-dashboard.search.brave.com/login](https://api-dashboard.search.brave.com/login) to generate a key.
3. **Set the environment variable** — store your key as `BRAVE_API_KEY`, or pass it directly via the `api_key` parameter.

## Quick Examples

### Web Search

```python Code theme={null}
from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool()
results = tool.run(q="CrewAI agent framework")
print(results)
```

### News Search

```python Code theme={null}
from crewai_tools import BraveNewsSearchTool

tool = BraveNewsSearchTool()
results = tool.run(q="latest AI breakthroughs")
print(results)
```

### Image Search

```python Code theme={null}
from crewai_tools import BraveImageSearchTool

tool = BraveImageSearchTool()
results = tool.run(q="northern lights photography")
print(results)
```

### Video Search

```python Code theme={null}
from crewai_tools import BraveVideoSearchTool

tool = BraveVideoSearchTool()
results = tool.run(q="how to build AI agents")
print(results)
```

### Location POI Descriptions

```python Code theme={null}
from crewai_tools import (
    BraveWebSearchTool,
    BraveLocalPOIsDescriptionTool,
)

web_search = BraveWebSearchTool(raw=True)
poi_details = BraveLocalPOIsDescriptionTool()

results = web_search.run(q="italian restaurants in pensacola, florida")

if "locations" in results:
    location_ids = [ loc["id"] for loc in results["locations"]["results"] ]
    if location_ids:
        descriptions = poi_details.run(ids=location_ids)
        print(descriptions)
```

## Common Constructor Parameters

Every Brave Search tool accepts the following parameters at initialization:

| Parameter             | Type           | Default | Description                                                                                             |
| --------------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Brave API key. Falls back to the `BRAVE_API_KEY` environment variable.                                  |
| `headers`             | `dict \| None` | `None`  | Additional HTTP headers to send with every request (e.g., `api-version`, geolocation headers).          |
| `requests_per_second` | `float`        | `1.0`   | Maximum request rate. The tool will sleep between calls to stay within this limit.                      |
| `save_file`           | `bool`         | `False` | When `True`, each response is written to a timestamped `.txt` file.                                     |
| `raw`                 | `bool`         | `False` | When `True`, the full API JSON response is returned without any refinement.                             |
| `timeout`             | `int`          | `30`    | HTTP request timeout in seconds.                                                                        |
| `country`             | `str \| None`  | `None`  | Legacy shorthand for geo-targeting (e.g., `"US"`). Prefer using the `country` query parameter directly. |
| `n_results`           | `int`          | `10`    | Legacy shorthand for result count. Prefer using the `count` query parameter directly.                   |

<Warning>
  The `country` and `n_results` constructor parameters exist for backwards compatibility. They are applied as defaults when the corresponding query parameters (`country`, `count`) are not provided at call time. For new code, we recommend passing `country` and `count` directly as query parameters instead.
</Warning>

## Query Parameters

Each tool validates its query parameters against a Pydantic schema before sending the request.
The parameters vary slightly per endpoint — here is a summary of the most commonly used ones:

### BraveWebSearchTool

| Parameter        | Description                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `q`              | **(required)** Search query string (max 400 chars).                                                                                              |
| `country`        | Two-letter country code for geo-targeting (e.g., `"US"`).                                                                                        |
| `search_lang`    | Two-letter language code for results (e.g., `"en"`).                                                                                             |
| `count`          | Max number of results to return (1–20).                                                                                                          |
| `offset`         | Skip the first N pages of results (0–9).                                                                                                         |
| `safesearch`     | Content filter: `"off"`, `"moderate"`, or `"strict"`.                                                                                            |
| `freshness`      | Recency filter: `"pd"` (past day), `"pw"` (past week), `"pm"` (past month), `"py"` (past year), or a date range like `"2025-01-01to2025-06-01"`. |
| `extra_snippets` | Include up to 5 additional text snippets per result.                                                                                             |
| `goggles`        | Brave Goggles URL(s) and/or source for custom re-ranking.                                                                                        |

For the complete parameter and header reference, see the [Brave Web Search API documentation](https://api-dashboard.search.brave.com/api-reference/web/search/get).

### BraveNewsSearchTool

| Parameter     | Description                                               |
| ------------- | --------------------------------------------------------- |
| `q`           | **(required)** Search query string (max 400 chars).       |
| `country`     | Two-letter country code for geo-targeting.                |
| `search_lang` | Two-letter language code for results.                     |
| `count`       | Max number of results to return (1–50).                   |
| `offset`      | Skip the first N pages of results (0–9).                  |
| `safesearch`  | Content filter: `"off"`, `"moderate"`, or `"strict"`.     |
| `freshness`   | Recency filter (same options as Web Search).              |
| `goggles`     | Brave Goggles URL(s) and/or source for custom re-ranking. |

For the complete parameter and header reference, see the [Brave News Search API documentation](https://api-dashboard.search.brave.com/api-reference/news/news_search/get).

### BraveImageSearchTool

| Parameter     | Description                                         |
| ------------- | --------------------------------------------------- |
| `q`           | **(required)** Search query string (max 400 chars). |
| `country`     | Two-letter country code for geo-targeting.          |
| `search_lang` | Two-letter language code for results.               |
| `count`       | Max number of results to return (1–200).            |
| `safesearch`  | Content filter: `"off"` or `"strict"`.              |
| `spellcheck`  | Attempt to correct spelling errors in the query.    |

For the complete parameter and header reference, see the [Brave Image Search API documentation](https://api-dashboard.search.brave.com/api-reference/images/image_search).

### BraveVideoSearchTool

| Parameter     | Description                                           |
| ------------- | ----------------------------------------------------- |
| `q`           | **(required)** Search query string (max 400 chars).   |
| `country`     | Two-letter country code for geo-targeting.            |
| `search_lang` | Two-letter language code for results.                 |
| `count`       | Max number of results to return (1–50).               |
| `offset`      | Skip the first N pages of results (0–9).              |
| `safesearch`  | Content filter: `"off"`, `"moderate"`, or `"strict"`. |
| `freshness`   | Recency filter (same options as Web Search).          |

For the complete parameter and header reference, see the [Brave Video Search API documentation](https://api-dashboard.search.brave.com/api-reference/videos/video_search/get).

### BraveLocalPOIsTool

| Parameter     | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `ids`         | **(required)** A list of unique identifiers for the desired locations. |
| `search_lang` | Two-letter language code for results.                                  |

For the complete parameter and header reference, see [Brave Local POIs API documentation](https://api-dashboard.search.brave.com/api-reference/web/local_pois).

### BraveLocalPOIsDescriptionTool

| Parameter | Description                                                            |
| --------- | ---------------------------------------------------------------------- |
| `ids`     | **(required)** A list of unique identifiers for the desired locations. |

For the complete parameter and header reference, see [Brave POI Descriptions API documentation](https://api-dashboard.search.brave.com/api-reference/web/poi_descriptions).

## Custom Headers

All tools support custom HTTP request headers. The Web Search tool, for example, accepts geolocation headers for location-aware results:

```python Code theme={null}
from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(
    headers={
        "x-loc-lat": "37.7749",
        "x-loc-long": "-122.4194",
        "x-loc-city": "San Francisco",
        "x-loc-state": "CA",
        "x-loc-country": "US",
    }
)

results = tool.run(q="best coffee shops nearby")
```

You can also update headers after initialization using the `set_headers()` method:

```python Code theme={null}
tool.set_headers({"api-version": "2025-01-01"})
```

## Raw Mode

By default, each tool refines the API response into a concise list of results. If you need the full, unprocessed API response, enable raw mode:

```python Code theme={null}
from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(raw=True)
full_response = tool.run(q="Brave Search API")
```

## Agent Integration Example

Here's how to equip a CrewAI agent with multiple Brave Search tools:

```python Code theme={null}
from crewai import Agent
from crewai.project import agent
from crewai_tools import BraveWebSearchTool, BraveNewsSearchTool

web_search = BraveWebSearchTool()
news_search = BraveNewsSearchTool()

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        tools=[web_search, news_search],
    )
```

## Advanced Example

Combining multiple parameters for a targeted search:

```python Code theme={null}
from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(
    requests_per_second=0.5,  # conservative rate limit
    save_file=True,
)

results = tool.run(
    q="artificial intelligence news",
    country="US",
    search_lang="en",
    count=5,
    freshness="pm",           # past month only
    extra_snippets=True,
)
print(results)
```

## Migrating from `BraveSearchTool` (Legacy)

If you are currently using `BraveSearchTool`, switching to the new tools is straightforward:

```python Code theme={null}
# Before (legacy)
from crewai_tools import BraveSearchTool

tool = BraveSearchTool(country="US", n_results=5, save_file=True)
results = tool.run(search_query="AI agents")

# After (recommended)
from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(save_file=True)
results = tool.run(q="AI agents", country="US", count=5)
```

Key differences:

* **Import**: Use `BraveWebSearchTool` (or the news/image/video variant) instead of `BraveSearchTool`.
* **Query parameter**: Use `q` instead of `search_query`. (Both `search_query` and `query` are still accepted for convenience, but `q` is the preferred parameter.)
* **Result count**: Pass `count` as a query parameter instead of `n_results` at init time.
* **Country**: Pass `country` as a query parameter instead of at init time.
* **API key**: Can now be passed directly via `api_key=` in addition to the `BRAVE_API_KEY` environment variable.
* **Rate limiting**: Configurable via `requests_per_second` with automatic retry on `429` responses.

## Conclusion

The Brave Search tool suite gives your CrewAI agents flexible, endpoint-specific access to the Brave Search API. Whether you need web pages, breaking news, images, or videos, there is a dedicated tool with validated parameters and built-in resilience. Pick the tool that fits your use case, and refer to the [Brave Search API documentation](https://brave.com/search/api/) for the full details on available parameters and response formats.