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

Brave Search API

概述

使用Brave的隐私优先搜索API进行网络、图像和新闻搜索。还通过OpenAI SDK兼容性支持AI Grounding，以提供引用答案。

前提条件

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

export BRAVE_API_KEY="your-api-key"

免费层级：每月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兼容格式，带内联引用：

最高的建筑是哈利法塔[1]，高828米...

[1] https://来源-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`	flag	输出原始JSON

错误处理

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

速率限制

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

常见错误

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