Back to Details

web-search-brave

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Web Search (Brave Search API)

网页搜索（Brave Search API）

Search the web using Brave's Search API. Returns web results with descriptions, optional extra snippets, and support for country/language targeting.
Note: This skill requires a Brave Search API key. For basic web search using the agent's built-in capability, see 
web-search
. For AI-optimized results with relevance scores, see 
web-search-tavily
.
使用Brave的搜索API进行网页搜索。返回的网页结果包含描述、可选的额外摘要，支持按国家/语言定向搜索。
注意：本技能需要Brave Search API密钥。如果需要使用Agent内置能力进行基础网页搜索，请查看
web-search
。如果需要带相关性评分的AI优化结果，请查看
web-search-tavily
。

When to Use This Skill

何时使用本技能

Use this skill when:
  • You need to find current information not in your training data
  • The user asks about recent events, news, or updates
  • You need localized search results for a specific country or language
  • You want a privacy-respecting search alternative
  • Research requires real-time web data
  • Keywords mentioned: search, look up, find online, current, latest, news
Do NOT use this skill when:
  • Information is already in your knowledge base and doesn't need verification
  • The user asks about historical facts that don't change
  • You're working with local files or code (use other tools)
  • A more specific skill exists for the task (e.g., documentation lookup)
  • You need AI-generated answer summaries (use 
    web-search-tavily
    instead)
在以下场景使用本技能：
  • 你需要查找训练数据中没有的最新信息
  • 用户询问近期事件、新闻或更新
  • 你需要针对特定国家或语言的本地化搜索结果
  • 你想要尊重隐私的替代搜索方案
  • 研究需要实时网页数据
  • 提到的关键词：search、look up、find online、current、latest、news
请勿在以下场景使用本技能：
  • 信息已存在于你的知识库中，无需验证
  • 用户询问不会变化的历史事实
  • 你正在处理本地文件或代码（使用其他工具）
  • 该任务有更专门的技能可用（例如文档查询）
  • 你需要AI生成的答案摘要（改用
    web-search-tavily
    ）

Prerequisites

前置要求

Before using this skill, ensure:
  • BRAVE_API_KEY environment variable is set with a valid API key
  • Deno is installed (for running the search script)
  • Internet access is available
Get a Brave Search API key at: https://brave.com/search/api/
使用本技能前，请确保：
  • 已使用有效的API密钥设置BRAVE_API_KEY环境变量
  • 已安装Deno（用于运行搜索脚本）
  • 网络连接正常
可在此获取Brave Search API密钥：https://brave.com/search/api/

Quick Start

快速开始

Run a simple search:
bash
deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "your search query"
Example with freshness filter:
bash
deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "React 19 new features" --freshness pw
运行简单搜索：
bash
deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "your search query"
带新鲜度过滤的示例：
bash
deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "React 19 new features" --freshness pw

Script Usage

脚本用法

bash
deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts [options] "query"
bash
deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts [options] "query"

Options

选项

OptionDescriptionDefault
--results <n>
Number of results to return (max 20)5
--freshness <range>
Time filter: 
pd
, 
pw
, 
pm
, or 
py
none
--country <code>
Country code for localized results (e.g., US, GB, DE)none
--lang <code>
Search language (e.g., en, fr, de)none
--safesearch <level>
Safe search: 
off
, 
moderate
, or 
strict
moderate
--extra-snippets
Include additional content snippetsfalse
--offset <n>
Pagination offset0
--json
Output as JSON (for programmatic use)false
--help
Show help message-
选项描述默认值
--results <n>
返回的结果数量（最多20条）5
--freshness <range>
时间过滤：
pd
、
pw
、
pm
或
py
无
--country <code>
用于获取本地化结果的国家代码（例如US、GB、DE）无
--lang <code>
搜索语言（例如en、fr、de）无
--safesearch <level>
安全搜索：
off
、
moderate
或
strict
moderate
--extra-snippets
包含额外内容摘要false
--offset <n>
分页偏移量0
--json
以JSON格式输出（用于程序调用）false
--help
显示帮助信息-

Search Parameters

搜索参数

Freshness Values

新鲜度取值

Filter results by recency:
  • pd: Past day (last 24 hours)
  • pw: Past week (last 7 days)
  • pm: Past month (last 30 days)
  • py: Past year (last 365 days)
按时间新旧过滤结果：
  • pd：过去一天（24小时内）
  • pw：过去一周（7天内）
  • pm：过去一个月（30天内）
  • py：过去一年（365天内）

Country Codes

国家代码

Use standard 2-character country codes to get localized results:
  • US
    (United States), 
    GB
    (United Kingdom), 
    DE
    (Germany), 
    FR
    (France), 
    JP
    (Japan), etc.
使用标准的2位国家代码获取本地化结果：
  • US
    （美国）、
    GB
    （英国）、
    DE
    （德国）、
    FR
    （法国）、
    JP
    （日本）等

Safe Search Levels

安全搜索级别

  • off: No filtering
  • moderate (default): Filters explicit content
  • strict: Strictest filtering
  • off：无过滤
  • moderate（默认）：过滤露骨内容
  • strict：最严格的过滤

Output Format

输出格式

Human-Readable Output (default)

人类可读输出（默认）

Search: "React 19 new features"

Found 5 results in 189ms

1. React 19 Release Notes
   https://react.dev/blog/2024/04/25/react-19
   React 19 is now available on npm! This release includes...
   Age: 2 months ago

2. What's New in React 19
   https://example.com/react-19-features
   A comprehensive overview of React 19's new features...
Search: "React 19 new features"

Found 5 results in 189ms

1. React 19 Release Notes
   https://react.dev/blog/2024/04/25/react-19
   React 19 is now available on npm! This release includes...
   Age: 2 months ago

2. What's New in React 19
   https://example.com/react-19-features
   A comprehensive overview of React 19's new features...

JSON Output (--json)

JSON输出（--json）

json
{
  "query": "React 19 new features",
  "results": [
    {
      "title": "React 19 Release Notes",
      "url": "https://react.dev/blog/2024/04/25/react-19",
      "description": "React 19 is now available on npm...",
      "age": "2 months ago",
      "language": "en",
      "family_friendly": true
    }
  ],
  "response_time": 189,
  "total_results": 1250000
}
json
{
  "query": "React 19 new features",
  "results": [
    {
      "title": "React 19 Release Notes",
      "url": "https://react.dev/blog/2024/04/25/react-19",
      "description": "React 19 is now available on npm...",
      "age": "2 months ago",
      "language": "en",
      "family_friendly": true
    }
  ],
  "response_time": 189,
  "total_results": 1250000
}

Result Fields

结果字段

FieldTypeDescription
title
stringPage title
url
stringSource URL
description
stringRelevant excerpt from the page
extra_snippets
string[]Additional content snippets (only with --extra-snippets)
age
stringHow old the result is (e.g., "2 hours ago")
language
stringLanguage of the result
family_friendly
booleanWhether the result is family-friendly
字段类型描述
title
字符串页面标题
url
字符串来源URL
description
字符串页面相关摘录
extra_snippets
字符串数组额外内容摘要（仅使用--extra-snippets时返回）
age
字符串结果的发布时长（例如"2 hours ago"）
language
字符串结果的语言
family_friendly
布尔值结果是否适合全年龄浏览

Examples

示例

Example 1: Current Events Search

示例1：时事搜索

Scenario: Find recent news about a technology topic
bash
scripts/search.ts "OpenAI GPT-5 announcement" --freshness pw --results 10
Expected output: Recent web results about GPT-5 from the past week
场景：查找某个技术主题的近期新闻
bash
scripts/search.ts "OpenAI GPT-5 announcement" --freshness pw --results 10
预期输出：过去一周内关于GPT-5的最新网页结果

Example 2: Documentation Lookup

示例2：文档查询

Scenario: Find specific technical documentation
bash
scripts/search.ts "Deno deploy edge functions tutorial" --results 10 --extra-snippets
Expected output: Comprehensive results with extra snippets from documentation and tutorial sites
场景：查找特定技术文档
bash
scripts/search.ts "Deno deploy edge functions tutorial" --results 10 --extra-snippets
预期输出：来自文档和教程站点的完整结果，附带额外摘要

Example 3: Localized Search

示例3：本地化搜索

Scenario: Find results targeted to a specific country and language
bash
scripts/search.ts "aktuelle Nachrichten" --country DE --lang de --freshness pd
Expected output: German-language results from Germany from the past day
场景：查找针对特定国家和语言的结果
bash
scripts/search.ts "aktuelle Nachrichten" --country DE --lang de --freshness pd
预期输出：过去一天内来自德国的德语结果

Example 4: Filtered Search with JSON Output

示例4：带过滤的JSON输出搜索

Scenario: Get structured results with strict safe search
bash
scripts/search.ts "machine learning tutorials" --safesearch strict --extra-snippets --json
Expected output: JSON results with extra snippets, filtered for safe content
场景：获取严格安全搜索过滤的结构化结果
bash
scripts/search.ts "machine learning tutorials" --safesearch strict --extra-snippets --json
预期输出：带有额外摘要的JSON结果，已过滤为安全内容

Common Issues and Solutions

常见问题与解决方案

Issue: "BRAVE_API_KEY environment variable is not set"

问题："BRAVE_API_KEY environment variable is not set"

Symptoms: Script exits immediately with API key error
Solution:
  1. Get an API key from https://brave.com/search/api/
  2. Set the environment variable:
    bash
    export BRAVE_API_KEY="your-api-key-here"
  3. Or run with the variable inline:
    bash
    BRAVE_API_KEY="your-key" deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "query"
症状：脚本立即退出，返回API密钥错误
解决方案：
  1. 从https://brave.com/search/api/获取API密钥
  2. 设置环境变量：
    bash
    export BRAVE_API_KEY="your-api-key-here"
  3. 或在运行命令时直接传入变量：
    bash
    BRAVE_API_KEY="your-key" deno run --allow-env --allow-net=api.search.brave.com scripts/search.ts "query"

Issue: "Invalid Brave Search API key"

问题："Invalid Brave Search API key"

Symptoms: 401 authentication error
Solution:
  1. Verify your API key is correct (no extra spaces)
  2. Check if your API key has expired
  3. Verify your Brave Search API subscription is active
症状：401认证错误
解决方案：
  1. 验证你的API密钥是否正确（无多余空格）
  2. 检查你的API密钥是否已过期
  3. 验证你的Brave Search API订阅是否处于激活状态

Issue: "Brave Search API rate limit exceeded"

问题："Brave Search API rate limit exceeded"

Symptoms: 429 error response
Solution:
  1. Wait a moment and retry
  2. Reduce request frequency
  3. Consider upgrading your Brave Search API plan for higher limits
症状：429错误响应
解决方案：
  1. 稍等片刻后重试
  2. 降低请求频率
  3. 考虑升级你的Brave Search API套餐以获得更高的请求限额

Issue: No results returned

问题：无返回结果

Symptoms: Empty results array
Solution:
  1. Try broader search terms
  2. Remove country or language filters that might be too restrictive
  3. Remove or widen the freshness filter
  4. Check if the topic exists online
症状：结果数组为空
解决方案：
  1. 尝试使用更宽泛的搜索词
  2. 移除可能过于严格的国家或语言过滤条件
  3. 移除或放宽新鲜度过滤条件
  4. 确认该主题是否存在于公开网络上

Limitations

限制

This skill has the following limitations:
  • Requires active internet connection
  • API rate limits apply based on your Brave Search API plan
  • Results depend on Brave's index coverage
  • Cannot access paywalled or login-required content
  • No built-in AI-generated answer summaries (use 
    web-search-tavily
    for that)
  • Maximum 20 results per request
  • Extra snippets require a paid API plan
本技能存在以下限制：
  • 需要活跃的网络连接
  • API请求限额取决于你的Brave Search API套餐
  • 搜索结果取决于Brave的索引覆盖范围
  • 无法访问付费墙或需要登录的内容
  • 无内置AI生成的答案摘要（使用
    web-search-tavily
    获取该功能）
  • 每次请求最多返回20条结果
  • 额外摘要功能需要付费API套餐

Related Skills

相关技能

  • web-search: Basic web search using the agent's built-in capability
  • web-search-tavily: AI-optimized search with relevance scores and answer summaries
  • research-workflow: For comprehensive research projects that use multiple searches with planning and synthesis
  • web-search：使用Agent内置能力的基础网页搜索
  • web-search-tavily：AI优化的搜索，提供相关性评分和答案摘要
  • research-workflow：用于需要多次搜索、规划和整合的综合研究项目