BytesRouter

主题

CrewAI 文档版本 跟随上游 源快照 6dc7105e 更新于 2026-10-18

Brave Search 工具

一套用于查询 Brave Search API 的工具——涵盖网页、新闻、图片和视频搜索。

Brave Search 工具

描述

CrewAI 提供一系列 Brave Search 工具，每个工具针对特定的 Brave Search API 端点。 你无需使用单个大而全的工具，而是可以精确选择与智能体所需结果类型相匹配的工具：

工具端点用例
BraveWebSearchToolWeb Search通用网页结果、摘要和 URL
BraveNewsSearchToolNews Search最新新闻文章和标题
BraveImageSearchToolImage Search带尺寸和源 URL 的图片结果
BraveVideoSearchToolVideo Search来自全网各处的视频结果
BraveLocalPOIsToolLocal POIs查找兴趣点（例如餐厅）
BraveLocalPOIsDescriptionToolLocal POIs检索 AI 生成的地点描述
BraveLLMContextToolLLM Context为 AI 智能体、LLM grounding 和 RAG 流水线优化的预提取网页内容。

所有工具共享一个公共基类（BraveSearchToolBase），它提供一致的行为——限流、对 429 响应自动重试、请求头和参数校验，以及可选的文件保存。

NOTE

较旧的 BraveSearchTool 类仍可用于向后兼容，但它被视为 legacy，未来不会获得同等程度的关注。我们建议迁移到上面列出的特定工具，它们提供更丰富的配置和更专注的接口。

NOTE

尽管许多工具（例如 BraveWebSearchTool、BraveNewsSearchTool、BraveImageSearchTool 和 BraveVideoSearchTool）可与免费的 Brave Search API 订阅/套餐一起使用，但某些参数（例如 enable_snippets）和工具（例如 BraveLocalPOIsTool 和 BraveLocalPOIsDescriptionTool）需要付费套餐。请查阅你的订阅套餐能力以了解详情。

安装

shell
pip install 'crewai[tools]'

开始使用

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

快速示例

网页搜索

python
from crewai_tools import BraveWebSearchTool

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

新闻搜索

python
from crewai_tools import BraveNewsSearchTool

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

图片搜索

python
from crewai_tools import BraveImageSearchTool

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

视频搜索

python
from crewai_tools import BraveVideoSearchTool

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

地点 POI 描述

python
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_keystr | NoneNoneBrave API 密钥。回退到 BRAVE_API_KEY 环境变量。
headersdict | NoneNone随每个请求发送的额外 HTTP 请求头（例如 api-version、地理位置请求头）。
requests_per_secondfloat1.0最大请求速率。工具将在调用之间休眠，以保持在此限制内。
save_fileboolFalse当为 True 时，每个响应都会写入带时间戳的 .txt 文件。
rawboolFalse当为 True 时，返回完整的 API JSON 响应，不做任何精简。
timeoutint30HTTP 请求超时时间（秒）。
countrystr | NoneNone用于地理定位的旧版简写（例如 "US"）。建议直接使用 country 查询参数。
n_resultsint10结果数量的旧版简写。建议直接使用 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时效过滤器（与网页搜索相同的选项）。
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时效过滤器（与网页搜索相同的选项）。

完整的参数和请求头参考，请参阅 Brave Video Search API 文档。

BraveLocalPOIsTool

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

完整的参数和请求头参考，请参阅 Brave Local POIs API 文档。

BraveLocalPOIsDescriptionTool

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

完整的参数和请求头参考，请参阅 Brave POI 描述 API 文档。

自定义请求头

所有工具都支持自定义 HTTP 请求头。例如，网页搜索工具接受地理位置请求头以提供位置感知结果：

python
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() 方法更新请求头：

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

原始模式

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

python
from crewai_tools import BraveWebSearchTool

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

智能体集成示例

以下是如何为 CrewAI 智能体配备多个 Brave Search 工具：

python
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],
    )

高级示例

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

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

从 BraveSearchTool 迁移（旧版）

如果你当前正在使用 BraveSearchTool，切换到新工具很简单：

python
# 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)

主要区别：

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

结论

Brave Search 工具套件为你的 CrewAI 智能体提供灵活、针对特定端点的 Brave Search API 访问能力。无论你需要网页、突发新闻、图片还是视频，都有一个经过参数校验并内置容错能力的专用工具。选择适合你用例的工具，并参阅 Brave Search API 文档 了解可用参数和响应格式的完整详情。

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可