Brave Search 工具

Brave Search 工具

描述

CrewAI 提供了一组 Brave Search 工具，每个工具都针对 Brave Search API 的特定端点。
与单一的通用工具不同，你可以精确选择最适合智能体所需结果类型的工具：

工具	端点	使用场景
BraveWebSearchTool	Web Search	通用网页结果、摘要和 URL
BraveNewsSearchTool	News Search	最新新闻文章和标题
BraveImageSearchTool	Image Search	带有尺寸和来源 URL 的图片结果
BraveVideoSearchTool	Video Search	来自全网的视频结果
BraveLocalPOIsTool	Local POIs	查找兴趣点，例如餐厅
BraveLocalPOIsDescriptionTool	Local POIs	获取 AI 生成的位置描述
BraveLLMContextTool	LLM Context	为 AI 智能体、LLM grounding 和 RAG 流水线优化的预提取网页内容。

所有工具都共享一个通用基类 (BraveSearchToolBase)，提供一致的行为，例如速率限制、对 429 响应的自动重试、头部和参数校验，以及可选的文件保存。

Note

旧的 BraveSearchTool 类仍可用于向后兼容，但它被视为 旧版，以后不会得到同等程度的维护。我们建议迁移到上面列出的具体工具，它们提供了更丰富的配置和更聚焦的接口。

Note

虽然许多工具（例如 BraveWebSearchTool、BraveNewsSearchTool、BraveImageSearchTool 和 BraveVideoSearchTool）都可以搭配免费的 Brave Search API 订阅/计划使用，但某些参数（例如 enable_snippets）以及某些工具（例如 BraveLocalPOIsTool 和 BraveLocalPOIsDescriptionTool）需要付费计划。请查看你的订阅计划能力以确认。

安装

pip install 'crewai[tools]'

入门

1. 安装包 - 确认你的 Python 环境中已安装 crewai[tools]。
2. 获取 API key - 前往 api-dashboard.search.brave.com/login 注册并生成密钥。
3. 设置环境变量 - 将密钥存储为 BRAVE_API_KEY，或者通过 api_key 参数直接传入。

快速示例

网页搜索

from crewai_tools import BraveWebSearchTool

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

新闻搜索

from crewai_tools import BraveNewsSearchTool

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

图片搜索

from crewai_tools import BraveImageSearchTool

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

视频搜索

from crewai_tools import BraveVideoSearchTool

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

位置信息描述

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)

通用构造参数

每个 Brave Search 工具在初始化时都接受以下参数：

参数	类型	默认值	描述
api_key	str | None	None	Brave API key。若未提供，则回退到 BRAVE_API_KEY 环境变量。
headers	dict | None	None	每次请求附加发送的 HTTP 头部（例如 api-version、地理位置头部）。
requests_per_second	float	1.0	最大请求速率。工具会在调用之间休眠以保持在此限制内。
save_file	bool	False	当为 True 时，每个响应都会写入带时间戳的 .txt 文件。
raw	bool	False	当为 True 时，返回完整的 API JSON 响应，不做任何精炼。
timeout	int	30	HTTP 请求超时时间（秒）。
country	str | None	None	旧式地理定位简写（例如 "US"）。优先直接使用 country 查询参数。
n_results	int	10	旧式结果数量简写。优先直接使用 count 查询参数。

Warning

country 和 n_results 这两个构造参数是为了向后兼容而保留的。当调用时没有提供相应查询参数（country、count）时，它们会作为默认值生效。对于新代码，我们建议直接把 country 和 count 作为查询参数传入。

查询参数

每个工具都会在发送请求前使用 Pydantic schema 验证其查询参数。
不同端点的参数略有差异，下面是最常用参数的摘要：

BraveWebSearchTool

参数	描述
q	（必需） 搜索查询字符串（最长 400 个字符）。
country	用于地理定位的两字母国家代码（例如 "US"）。
search_lang	结果所使用的两字母语言代码（例如 "en"）。
count	要返回的最大结果数（1–20）。
offset	跳过前 N 页结果（0–9）。
safesearch	内容过滤：“off”、“moderate” 或 “strict”。
freshness	时效过滤：“pd”（过去一天）、“pw”（过去一周）、“pm”（过去一月）、“py”（过去一年），或类似 "2025-01-01to2025-06-01" 的日期范围。
extra_snippets	每条结果额外包含最多 5 个文本片段。
goggles	Brave Goggles URL（可多个）和/或用于自定义重排序的来源。

完整的参数和头部参考请查看 Brave Web Search API 文档。

BraveNewsSearchTool

参数	描述
q	（必需） 搜索查询字符串（最长 400 个字符）。
country	用于地理定位的两字母国家代码。
search_lang	结果所使用的两字母语言代码。
count	要返回的最大结果数（1–50）。
offset	跳过前 N 页结果（0–9）。
safesearch	内容过滤：“off”、“moderate” 或 “strict”。
freshness	时效过滤（与 Web Search 相同）。
goggles	Brave Goggles URL（可多个）和/或用于自定义重排序的来源。

完整的参数和头部参考请查看 Brave News Search API 文档。

BraveImageSearchTool

参数	描述
q	（必需） 搜索查询字符串（最长 400 个字符）。
country	用于地理定位的两字母国家代码。
search_lang	结果所使用的两字母语言代码。
count	要返回的最大结果数（1–200）。
safesearch	内容过滤：“off” 或 “strict”。
spellcheck	尝试纠正查询中的拼写错误。

完整的参数和头部参考请查看 Brave Image Search API 文档。

BraveVideoSearchTool

参数	描述
q	（必需） 搜索查询字符串（最长 400 个字符）。
country	用于地理定位的两字母国家代码。
search_lang	结果所使用的两字母语言代码。
count	要返回的最大结果数（1–50）。
offset	跳过前 N 页结果（0–9）。
safesearch	内容过滤：“off”、“moderate” 或 “strict”。
freshness	时效过滤（与 Web Search 相同）。

完整的参数和头部参考请查看 Brave Video Search API 文档。

BraveLocalPOIsTool

参数	描述
ids	（必需） 目标位置的唯一标识符列表。
search_lang	结果所使用的两字母语言代码。

完整的参数和头部参考请查看 Brave Local POIs API 文档。

BraveLocalPOIsDescriptionTool

参数	描述
ids	（必需） 目标位置的唯一标识符列表。

完整的参数和头部参考请查看 Brave POI Descriptions API 文档。

自定义头部

所有工具都支持自定义 HTTP 请求头。比如 Web Search 工具就支持地理位置头部，用于获取基于位置的结果：

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

你也可以在初始化后使用 set_headers() 方法更新头部：

tool.set_headers({"api-version": "2025-01-01"})

原始模式

默认情况下，每个工具都会将 API 响应精炼为简洁的结果列表。如果你需要完整、未经处理的 API 响应，可以启用原始模式：

from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(raw=True)
results = tool.run(q="CrewAI")
print(results)

高级示例

将多个参数组合起来进行定向搜索：

from crewai_tools import BraveWebSearchTool

tool = BraveWebSearchTool(
    requests_per_second=0.5,  # 保守的速率限制
    save_file=True,
)

results = tool.run(
    q="artificial intelligence news",
    country="US",
    search_lang="en",
    count=5,
    freshness="pm",           # 仅限过去一个月
    extra_snippets=True,
)
print(results)

从 BraveSearchTool（旧版）迁移

如果你目前正在使用 BraveSearchTool，迁移到新工具非常直接：

# 之前（旧版）
from crewai_tools import BraveSearchTool

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

# 之后（推荐）
from crewai_tools import BraveWebSearchTool

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

主要差异：

• 导入：使用 BraveWebSearchTool（或新闻/图片/视频变体），而不是 BraveSearchTool。
• 查询参数：使用 q 代替 search_query。（为了方便，search_query 和 query 仍然可以接受，但 q 是首选参数。）
• 结果数量：在查询参数中传入 count，而不是在初始化时传入 n_results。
• 国家/地区：在查询参数中传入 country，而不是在初始化时传入。
• API key：除了 BRAVE_API_KEY 环境变量外，现在也可以直接通过 api_key= 传入。
• 速率限制：通过 requests_per_second 配置，并对 429 响应自动重试。

结论

Brave Search 工具套件为你的 CrewAI 智能体提供了灵活、按端点划分的 Brave Search API 访问能力。无论你需要网页、突发新闻、图片还是视频，都有相应的专用工具，带有已验证的参数和内置的稳健性。根据你的使用场景选择合适的工具，并参考 Brave Search API 文档 获取可用参数和响应格式的完整细节。