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:

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

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:

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

For the complete parameter and header reference, see the Brave Web Search API documentation.

BraveNewsSearchTool

For the complete parameter and header reference, see the Brave News Search API documentation.

BraveImageSearchTool

For the complete parameter and header reference, see the Brave Image Search API documentation.

BraveVideoSearchTool

For the complete parameter and header reference, see the Brave Video Search API documentation.

BraveLocalPOIsTool

For the complete parameter and header reference, see Brave Local POIs API documentation.

BraveLocalPOIsDescriptionTool

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.