QUICK_START_WEB_SEARCH.md

Web Search 快速开始

🚀 5 分钟上手

1. 无需配置（使用 DuckDuckGo）

直接使用，无需任何设置：

// 在 super-agents 中调用 web_search 工具
{
  "query": "TypeScript best practices 2026"
}

优点：开箱即用
缺点：可能遇到 rate limiting

---

2. 配置 Brave Search（推荐）

步骤 1: 获取 API Key

1. 访问 https://brave.com/search/api/
2. 注册账号
3. 选择 Free 计划（2,000 queries/月）
4. 复制 API key

步骤 2: 设置环境变量

方法 A: 使用 .env 文件

在项目根目录创建或编辑 .env 文件：

BRAVE_API_KEY=your_actual_api_key_here

方法 B: 系统环境变量

MacOS/Linux:

export BRAVE_API_KEY=your_actual_api_key_here

Windows (PowerShell):

$env:BRAVE_API_KEY="your_actual_api_key_here"

步骤 3: 重启 super-agents

关闭并重新启动应用，环境变量即生效。

步骤 4: 使用

{
  "query": "Claude AI latest features",
  "limit": 10
}

系统会自动使用 Brave Search（因为检测到 API key）。

---

3. 验证配置

使用以下查询测试：

{
  "query": "test search",
  "limit": 3
}

检查返回的 metadata.provider 字段：

{
  metadata: {
    provider: "Brave Search",  // ✅ 配置成功
    // 或
    provider: "DuckDuckGo",    // ℹ️ 使用默认
    hadFallback: false
  }
}

---

📋 常见用例

用例 1: 快速搜索

{
  "query": "React 19 new features"
}

用例 2: 深度研究

{
  "query": "machine learning transformers architecture",
  "limit": 10,
  "provider": "brave"
}

用例 3: 时效性信息

{
  "query": "stock market news today",
  "timeoutMs": 30000
}

---

🔍 检查提供商状态

在 super-agents 中，web_search 的返回结果会显示使用的提供商：

Search results via Brave Search
Found 10 results

1. Result Title
URL: https://...
Snippet: ...

---

⚠️ 故障排除

问题 1: Rate Limit 错误

错误信息：

Web search temporarily blocked due to rate limiting

解决方案：

1. 等待 30-60 秒后重试
2. 配置 Brave 或 Tavily API key

问题 2: API Key 无效

错误信息：

Brave Search API error (401): Unauthorized

解决方案：

1. 检查环境变量名称是否正确：BRAVE_API_KEY
2. 确认 API key 没有多余空格
3. 重启应用以加载新的环境变量

问题 3: 超时

错误信息：

Web search failed: The operation was aborted

解决方案：

1. 增加超时时间："timeoutMs": 30000
2. 检查网络连接
3. 尝试其他提供商

---

💡 提示和技巧

提示 1: 间隔搜索请求

避免连续快速搜索，建议间隔 2-3 秒。

提示 2: 使用合适的 limit

• 快速预览：limit: 3-5
• 一般搜索：limit: 5-7
• 深度研究：limit: 10

提示 3: 结合 web_fetch 使用

// 1. 搜索
const searchResult = await web_search({
  query: "TypeScript documentation"
});

// 2. 获取第一个结果的详细内容
const url = searchResult.metadata.results[0].url;
const content = await web_fetch({
  url,
  format: "markdown"
});

---

🆘 需要帮助？

1. 查看完整文档：docs/WEB_SEARCH.md
2. 查看实现细节：WEB_SEARCH_IMPLEMENTATION.md
3. 查看配置示例：.env.example.websearch

---

🎯 下一步

• 获取 Brave API key（推荐）
• 或获取 Tavily API key
• 配置环境变量
• 测试搜索功能
• 阅读完整文档了解高级用法

---

版本: v0.1.4+
更新: 2026-06-17