--- source_url: "https://docs.crewai.com/en/tools/search-research/bravesearchtool?utm_source=openai" title: Brave Search Tools - CrewAI mirrored_at: 2026-08-09T13:02:24.893Z host: docs.crewai.com cited_in_42a: true mirror_canonical: "https://index.42a.ai/docs.crewai.com/en/tools/search-research/bravesearchtool__q__utm_source_openai" --- > **Original source:** https://docs.crewai.com/en/tools/search-research/bravesearchtool?utm_source=openai ## 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. ## Installation ## 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 Code ### News Search Code ### Image Search Code ### Video Search Code ### Location POI Descriptions Code ## 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. ## 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). All tools support custom HTTP request headers. The Web Search tool, for example, accepts geolocation headers for location-aware results: Code You can also update headers after initialization using the `set_headers()` method: Code ## 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: Code ## Agent Integration Example Here’s how to equip a CrewAI agent with multiple Brave Search tools: Code ## Advanced Example Combining multiple parameters for a targeted search: Code ## Migrating from `BraveSearchTool` (Legacy) If you are currently using `BraveSearchTool`, switching to the new tools is straightforward: Code 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.