name: brave-search description: 当用户要求搜索网络、在线查找信息、寻找当前/最新信息或需要引用答案时使用。触发词包括"搜索"、“查找”、“了解关于”、“当前/最新是什么”，图像搜索，新闻查询。不适用于搜索代码/文件——仅用于网络/互联网搜索。

Brave搜索API

概述

使用Brave的隐私优先搜索API搜索网络、图像和新闻。还支持通过OpenAI SDK兼容的AI Grounding获取引用答案。

前提条件

需要API密钥。 在 https://api-dashboard.search.brave.com 获取。

export BRAVE_API_KEY="您的API密钥"

免费层级：每月2,000次查询。专业计划解锁本地POI搜索和AI Grounding。

何时使用

搜索网络获取当前信息
查找主题相关的图像
获取最新新闻文章
带引用的AI答案
自动完成建议
位置/POI搜索（专业计划）

高吞吐量使用

广泛且快速。 此API支持高并发——每秒最多50个请求。不要犹豫：

并行发起搜索。 需要研究10个不同主题？同时发起10个搜索。在单条消息中使用多个Bash工具调用。
使用子代理处理大量结果。 当期望大量上下文（许多结果、额外摘要、研究模式）时，派遣子代理运行搜索并综合发现。这可以保护您的主要上下文窗口。
批处理相关查询。 搜索竞争对手、替代品或主题的多个方面？同时运行它们。

digraph parallel_search {
    rankdir=LR;
    node [shape=box];

    task [label="研究任务"];
    q1 [label="查询1"];
    q2 [label="查询2"];
    q3 [label="查询3"];
    subagent [label="子代理
(保护上下文)"];
    synthesize [label="综合
发现"];

    task -> q1;
    task -> q2;
    task -> q3;
    q1 -> subagent [style=dashed];
    q2 -> subagent [style=dashed];
    q3 -> subagent [style=dashed];
    subagent -> synthesize;
}

何时使用子代理：

搜索主题的许多来源（启动搜索子代理，返回摘要）
带AI Grounding的深度研究（高令牌使用，让子代理处理）
比较多个选项（运行并行搜索，子代理综合）

何时直接搜索：

需要原始URL/摘要的快速单次查询
结果数量少，上下文不成问题时

快速参考

任务	命令
网络搜索	`brave-search web "查询"`
图像搜索	`brave-search images "查询"`
新闻搜索	`brave-search news "查询"`
AI答案	`brave-search ai "问题"`
建议	`brave-search suggest "部分查询"`
检查密钥	`brave-search check-key`

API端点

API	端点	计划
网络搜索	`/res/v1/web/search`	免费
图像搜索	`/res/v1/images/search`	免费
新闻搜索	`/res/v1/news/search`	免费
建议	`/res/v1/suggest/search`	免费
AI Grounding	`/res/v1/chat/completions`	AI Grounding
本地POI	`/res/v1/local/pois`	专业
摘要器	`/res/v1/summarizer/search`	专业

常用参数

网络搜索

# 基本搜索
brave-search web "python异步教程" --count 10

# 按新鲜度过滤（pd=24小时, pw=7天, pm=31天, py=365天）
brave-search web "最新新闻" --freshness pd

# 按国家和语言过滤
brave-search web "本地餐厅" --country US --lang en

# 安全搜索（off, moderate, strict）
brave-search web "查询" --safesearch strict

# 获取额外摘要
brave-search web "查询" --extra-snippets

# 过滤结果类型（web, news, videos, images, discussions）
brave-search web "查询" --filter web,news

图像搜索

# 基本图像搜索
brave-search images "山景日落"

# 带安全搜索
brave-search images "风景" --safesearch strict --count 20

新闻搜索

# 最新新闻
brave-search news "AI发展" --count 10

# 带新鲜度过滤的新闻
brave-search news "选举结果" --freshness pd

AI Grounding（引用答案）

# 获取带引用的AI答案
brave-search ai "世界上最高的建筑是什么？"

# 启用深度研究（多次搜索，较慢）
brave-search ai "2024年比较React和Vue" --research

工作流程

digraph brave_search {
    rankdir=TB;
    node [shape=box];

    need [label="您需要什么？" shape=diamond];
    web [label="网络搜索
brave.py web"];
    images [label="图像搜索
brave.py images"];
    news [label="新闻搜索
brave.py news"];
    ai [label="AI答案
brave.py ai"];

    results [label="解析JSON结果"];
    cite [label="包含引用
用于AI答案"];

    need -> web [label="网页"];
    need -> images [label="图像"];
    need -> news [label="最新新闻"];
    need -> ai [label="引用答案"];

    web -> results;
    images -> results;
    news -> results;
    ai -> cite;
}

响应结构

网络搜索结果

{
  "web": {
    "results": [
      {
        "title": "页面标题",
        "url": "https://example.com",
        "description": "页面摘要...",
        "extra_snippets": ["额外上下文..."]
      }
    ]
  },
  "query": {
    "original": "搜索查询",
    "altered": "拼写检查后修改的查询"
  }
}

AI Grounding响应

返回OpenAI兼容格式，带内联引用：

最高的建筑是Burj Khalifa[1]，高828米...

[1] https://source-url.com

常用选项

选项	值	描述
`--count`	1-20（网络）, 1-200（图像）	结果数量
`--country`	US, GB, DE, FR等	搜索区域
`--lang`	en, de, fr, es等	搜索语言
`--safesearch`	off, moderate, strict	成人内容过滤器
`--freshness`	pd, pw, pm, py	时间过滤器
`--json`	标志	输出原始JSON

错误处理

错误	原因	修复
401 未授权	无效/缺少API密钥	检查 `BRAVE_API_KEY`
429 速率限制	请求过多	等待或升级计划
422 验证	无效参数	检查参数值

速率限制

免费：每秒1个请求，每月2,000次
专业：更高限制，查看仪表板
响应头显示剩余配额：X-RateLimit-Remaining

常见错误

错误	修复
API密钥未设置	`export BRAVE_API_KEY="..."`
计划端点错误	在仪表板检查订阅
结果过多	网络最多20个，使用偏移进行分页
无AI grounding	需要AI Grounding订阅