# Search Tools for Hermes Agent

## Current Environment

| Tool | Type | Usage |
|------|------|-------|
| **web** (built-in) | Web Search & Scraping | `web_search`, `web_extract` tools |
| **session_search** | Session history | `session_search(query="...")` |
| **mmx search** | MiniMax CLI | `mmx search query "关键词"` |

## Popular Search APIs for AI Agents

| Tool | Best For | Pricing | MCP Server |
|------|----------|---------|------------|
| **Tavily Search** | AI-native search, structured results | Free tier available | `tavily-mcp` |
| **SerpAPI** | Google results scraping | Paid (100 free/month) | `serpapi-mcp` |
| **Brave Search** | Privacy-focused, no tracking | Free tier (2000/month) | `brave-search-mcp` |
| **Perplexity API** | AI search with citations | Paid | API only |
| **Firecrawl** | Web scraping + extraction | Free tier | `firecrawl-mcp` |
| **Jina Reader** | URL to Markdown conversion | Free tier | API only |
| **SearXNG** | Self-hosted meta search | Free (self-hosted) | `searxng-mcp` |

## Configuration Examples

### Tavily Search (Recommended for AI Agents)

```yaml
# ~/.hermes/config.yaml
mcp_servers:
  tavily:
    command: npx
    args: ["-y", "tavily-mcp@latest"]
    env:
      TAVILY_API_KEY: "tvly-xxxxx"
```

Get API key: https://tavily.com (free tier: 1000 searches/month)

### Brave Search

```yaml
mcp_servers:
  brave-search:
    command: npx
    args: ["-y", "@anthropic/brave-search-mcp@latest"]
    env:
      BRAVE_API_KEY: "BSAxxxxx"
```

Get API key: https://brave.com/search/api/ (free tier: 2000 queries/month)

### Firecrawl (for Web Scraping)

```yaml
mcp_servers:
  firecrawl:
    command: npx
    args: ["-y", "firecrawl-mcp"]
    env:
      FIRECRAWL_API_KEY: "fc-xxxxx"
```

## When to Use Which

| Scenario | Recommended Tool |
|----------|------------------|
| Quick factual lookup | `mmx search` or built-in `web_search` |
| Structured data extraction | Tavily Search |
| Google-specific results | SerpAPI |
| Privacy-sensitive search | Brave Search |
| Deep web scraping | Firecrawl |
| Convert page to markdown | Jina Reader |
| Previous conversation context | `session_search` |

## Pitfalls

- **mcp_servers: {}** is currently empty in this environment
- Tool changes require `/reset` (new session) to take effect
- Free tiers have rate limits; monitor usage for production use
- Some MCP servers require Node.js (`npx` command)
- **mmx search Token Plan 限制**：`mmx search query` 需要 MiniMax Token Plan 支持 `coding-plan-search` 模型。报错 "your current token plan not support model" 表示 plan 不含搜索能力，需升级或换替代方案
- **服务器出站网络受限**：某些云服务器/容器的出站网络被限制，`urllib` 报 `Network is unreachable` (errno 101)。此时 curl、Python requests、mimo_search.py 均无法访问外部。排查：`curl -s -o /dev/null -w "%{http_code}" https://www.baidu.com`
- **Playwright/Chrome 沙盒问题**：服务器上 Chrome 需要 `--no-sandbox` 参数才能启动。Hermes 的 browser 工具可能因沙盒限制失败。排查：检查 Chrome stderr 中是否有 "No usable sandbox" 错误
- **mimo_search.py 环境变量**：脚本依赖 `XIAOMI_API_KEY` 环境变量，但 Hermes config.yaml 中的 key 不会自动 export。需手动 `export XIAOMI_API_KEY=...` 或从 config 提取

## 搜索降级策略（按优先级）

当用户请求搜索时，按以下顺序尝试：

1. **mmx search** — 最简单，但需 Token Plan 支持
2. **mimo_search.py** — MiMo 原生搜索，需 XIAOMI_API_KEY 环境变量 + 网络可达
3. **web_search 工具** — Hermes 内置，需 web toolset 启用
4. **Playwright 浏览器** — 通用兜底，但需 Chrome 可启动
5. **curl + 搜索引擎** — 最基础，需服务器出站网络可达

全部失败时，告知用户具体失败原因（Token Plan 限制 / 网络不通 / 浏览器沙盒问题），并建议用户在本地自行搜索。