first commit

autonomous-ai-agents/hermes-agent/references/search-tools.md

@@ -0,0 +1,96 @@
+# 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 限制 / 网络不通 / 浏览器沙盒问题），并建议用户在本地自行搜索。