97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 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 限制 / 网络不通 / 浏览器沙盒问题），并建议用户在本地自行搜索。
|