Brave Search Tools

Brave Search Tools

Description

CrewAI offers a family of Brave Search tools, each targeting a specific Brave 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

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.

Installation

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

from crewai_tools import BraveWebSearchTool

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

News Search

from crewai_tools import BraveNewsSearchTool

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

Image Search

from crewai_tools import BraveImageSearchTool

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

Video Search

from crewai_tools import BraveVideoSearchTool

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

Location POI Descriptions

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.

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.

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.

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.

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.

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.

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.

Custom Headers

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

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:

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:

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:

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:

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:

# 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 for the full details on available parameters and response formats.