内容
# NIM Pi 研究代理
一款自主的网络搜索和网页爬取研究子代理，可以通过 **MCP** 从 Claude Desktop、Antigravity、Cursor、Windsurf 或任何兼容 MCP 的宿主调用。宿主代理不需要启动自己的浏览器进程，而是将研究委托给一个专用的 [`@earendil-works/pi-coding-agent`](https://github.com/earendil-works/pi) 子进程，该子进程由 **NVIDIA NIM** 推理 API 提供支持。
> **为什么使用它？** 在 Claude Code、Cursor 或 Codex 等托管中，子代理在执行简单的研究任务时，会消耗大量 token。如果 Pi 代理使用免费的 NVIDIA NIM API，可以处理研究任务，返回研究数据和信息，那些子代理通常会提供这些信息。这正是 MCP 服务器实现的功能。
## 架构
```
宿主代理 (Claude / Antigravity / Cursor)
│
├─ MCP 调用：run_research(query, instructions, timeout_minutes)
│
▼
FastMCP 服务器 (research_agent/mcp_server.py)
│
▼
研究代理 (research_agent/agent.py)
│
├─ 创建带有 search_tool.py 的临时工作空间
├─ 配置 NVIDIA NIM 提供商 (models.json)
├─ 启动 pi 编码代理子进程
│ │
│ ├─ bash 工具 → search_tool.py --search "query"
│ │ (Serper API → DuckDuckGo 备用)
│ ├─ bash 工具 → search_tool.py --scrape "url"
│ │ (BeautifulSoup → 清理的 markdown 文本)
│ └─ write 工具 → report.md
│
└─ 将 report.md 内容返回给宿主代理
```
## 功能
- **自主研究循环** — Pi 代理自主规划搜索、爬取网页和综合研究结果
- **双重搜索后端** — Serper API（Google 结果，每月 250 次免费调用）和零配置 DuckDuckGo 备用
- **智能爬取** — 剥离脚本/导航/页脚，提取标题/段落/列表，截断为 4000 字
- **超时保护** — 可配置的超时（默认为 5 分钟）防止 NVIDIA API 调用无限阻塞
- **MCP 集成** — 通过 FastMCP 暴露 `run_research` 工具，与任何 MCP 宿主无缝集成
- **NVIDIA NIM 支持** — 使用 `meta/llama-3.3-70b-instruct`（默认）或 `deepseek-ai/deepseek-v4-pro` 进行推理
## 安装
```bash
# 1. 克隆/导航到项目
cd "/path/to/Free subagents skill"
# 2. 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 3. 安装 Python 依赖
pip install -r requirements.txt
pip install -e .
# 4. 安装 pi 编码代理（需要 Node.js）
npm install @earendil-works/pi-coding-agent
```
### 环境变量
在项目根目录下创建 `.env` 文件：
```env
NVIDIA_NIM_API_KEY=nvapi-your-key-here
NVIDIA_NIM_API_BASE=https://integrate.api.nvidia.com/v1
NVIDIA_MODEL=meta/llama-3.3-70b-instruct
NVIDIA_VISION_MODEL=meta/llama-3.2-90b-vision-instruct
SERPER_API_KEY=your-serper-key-optional
```
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `NVIDIA_NIM_API_KEY` | ✅ | NVIDIA NIM API 密钥，用于 LLM 推理 |
| `NVIDIA_NIM_API_BASE` | ✅ | NIM API 基础 URL |
| `NVIDIA_MODEL` | ❌ | 文本模型（默认：`meta/llama-3.3-70b-instruct`） |
| `NVIDIA_VISION_MODEL` | ❌ | 视觉模型（默认：`meta/llama-3.2-90b-vision-instruct`） |
| `SERPER_API_KEY` | ❌ | Serper.dev API 密钥，用于 Google 搜索（每月 250 次免费调用） |
## 使用
### 1. MCP 服务器（推荐）
将以下内容添加到您的 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"nim-research-agent": {
"command": "/path/to/Free subagents skill/.venv/bin/research-agent-mcp",
"env": {
"NVIDIA_NIM_API_KEY": "nvapi-...",
"NVIDIA_NIM_API_BASE": "https://integrate.api.nvidia.com/v1",
"NVIDIA_MODEL": "meta/llama-3.3-70b-instruct",
"SERPER_API_KEY": "your-key-here"
}
}
}
}
```
宿主代理可以调用：
```python
run_research(
query="量子计算的最新进展是什么？",
instructions="关注 2025 年的纠错突破",
timeout_minutes=5
)
```
### 2. 命令行界面
```bash
# 基本研究
research-agent --query "核聚变的最新进展" --output report.md
# 带有附加指令
research-agent -q "NVIDIA NIM 2025" -i "关注基准测试" -o nim_report.md
```
**命令行参数：**
- `--query` / `-q`（必填）：研究主题或问题
- `--instructions` / `-i`（可选）：关注领域或格式化约束
- `--output` / `-o`（可选）：输出文件路径（默认为 `research_report.md`）
### 3. Python API
```python
from research_agent.agent import ResearchAgent
agent = ResearchAgent(timeout_seconds=300)
report = agent.run(
query="欧盟的人工智能监管现状如何？",
instructions="包括具体立法和时间表"
)
print(report)
```
## 工作原理
1. **工作空间设置** — 创建一个临时目录，带有 `search_tool.py`，并为 NVIDIA NIM 配置 `models.json`
2. **Pi 代理启动** — 在非交互模式下启动 `@earendil-works/pi-coding-agent`，并带有研究提示
3. **自主研究** — Pi 代理使用其 `bash` 和 `write` 工具：
- 运行 3+ 次网络搜索，搜索词各不相同
- 爬取 3-5 个相关页面
- 综合研究结果成结构化报告
4. **报告检索** — 读取工作空间中的 `report.md`，并将其返回给调用者
5. **清理** — 删除临时工作空间目录
## NVIDIA NIM 兼容性
代理配置了以下 `compat` 重写，以适应 NVIDIA NIM 的 OpenAI 兼容 API：
```json
{
"supportsStrictMode": false,
"supportsDeveloperRole": false,
"supportsReasoningEffort": false
}
```
这些是必需的，因为 NVIDIA NIM 不支持 OpenAI 的严格工具调用模式功能。
## 故障排除
| 问题 | 解决方法 |
|-------|-----|
| `Pi 编码代理未找到` | 运行 `npm install @earendil-works/pi-coding-agent` |
| Serper 返回 `403 Forbidden` | API 密钥可能已过期；将使用 DuckDuckGo 作为备用 |
| 代理无限阻塞 | 增加 `timeout_minutes` 或检查 NVIDIA API 状态 |
| 报告短小或质量低劣 | 尝试使用 `deepseek-ai/deepseek-v4-pro` 作为 `NVIDIA_MODEL` 以获得更好的推理能力 |
| `duckduckgo_search` 弃用警告 | 运行 `pip install ddgs`（已在 requirements 中处理） |
