WebResearcher 

WebResearcher 

简介

WebResearcher 是迭代式深度研究智能体，基于 IterResearch 范式构建的自主研究智能体，旨在模拟专家级别的研究工作流。与遭受上下文溢出和噪音累积困扰的传统 Agent 不同，WebResearcher 将研究分解为离散的轮次，并进行迭代综合。

本项目提供两种研究智能体：

• WebResearcher Agent: 单智能体迭代研究，适合快速问答
• WebWeaver Agent: 双智能体协作研究，适合生成结构化长篇报告

传统 Agent 的问题

当前的开源研究 Agent 依赖于单上下文、线性累积模式：

1. 🚫 认知工作空间窒息: 不断膨胀的上下文限制了深度推理能力
2. 🚫 不可逆的噪音污染: 错误和无关信息不断累积
3. 🚫 缺乏周期性综合: 无法暂停以提炼、重新评估和战略性规划

WebResearcher 的解决方案

WebResearcher 实现了 IterResearch 范式，每轮通过单次 LLM 调用同时生成：

• Plan: 内部推理和分析
• Report（报告）: 综合所有发现的更新研究摘要
• Action（行动）: 工具调用或最终答案

这种一步式方法（相比传统的两步式"思考→行动→综合"）带来了：

• ⚡ 速度提升 50% - 每轮只需一次 LLM 调用而非两次
• 💰 成本降低 40% - 减少 Token 使用量
• 🧠 推理更优 - Plan、Report 和 Action 在统一上下文中生成

这实现了无界的研究深度，同时保持精简、聚焦的认知工作空间。

图：单上下文范式（上）vs. 迭代深度研究范式（下）

🏗️ 架构

核心组件

IterResearch 范式 - 每轮单次 LLM 调用：

第 i 轮:
┌─────────────────────────────────────────────────────────┐
│  工作空间状态: (问题, 报告_{i-1}, 结果_{i-1})              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  单次 LLM 调用 → 同时生成三部分：                          │
│  ├─ <plan>: 分析当前状态                                │
│  ├─ <report>: 综合所有发现的更新报告                      │
│  └─ <tool_call> 或 <answer>: 下一步行动                  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  如果是 <tool_call>: 执行工具                             │
│  如果是 <answer>: 返回最终答案                            │
└─────────────────────────────────────────────────────────┘
                          ↓
           使用更新后的报告和工具结果进入下一轮

核心优势: 报告在决定下一步行动之前就已完成综合，确保在统一上下文中进行连贯推理。

可用工具

工具	描述	使用场景
search	通过 Serper API 的 Google 搜索	通用网页信息
google_scholar	学术论文搜索	科研文献查询
visit	网页内容提取	深度内容分析
python	沙盒代码执行	数据分析、计算
parse_file	多格式文件解析器	文档处理

🚀 快速开始

安装

pip install webresearcher

WebUI 使用（推荐）

WebResearcher 提供了现代化的 Web 界面，支持桌面端和移动端：

# 启动 WebUI 服务
cd webui
python3 app.py

# 访问 http://localhost:8000

WebUI 特性：

• 🎨 现代化界面: 简洁优雅的对话式界面
• 📱 移动端适配: 完美支持手机和平板访问
• 🔄 实时流式输出: 研究过程实时可视化
• 📚 历史记录管理: 会话保存、编辑、删除
• 🎯 研究过程可视化: 计划、报告、工具调用分步展示
• ⚙️ 灵活配置: 支持自定义指令和工具选择

详见 WebUI 文档

CLI 基础使用

# 设置 API 密钥
export LLM_API_KEY="your_key"
export SERPER_API_KEY="your_key"

# 运行研究查询
webresearcher "刘翔破纪录时候是多少岁?"

Python API

import asyncio
from webresearcher import WebResearcherAgent

# 配置
llm_config = {
    "model": "gpt-4o",
    "api_key": "your-api-key",      # 可选，默认从环境变量 LLM_API_KEY 读取
    "base_url": "https://api.openai.com/v1",  # 可选，默认从环境变量 LLM_BASE_URL 读取
    "generate_cfg": {"temperature": 0.6}
}

# 创建 Agent（也可以通过参数直接传入 api_key 和 base_url）
agent = WebResearcherAgent(
    llm_config=llm_config,
    function_list=["search", "google_scholar", "python"],
)

# 开始研究
async def main():
    result = await agent.run("您的研究问题")
    print(result['prediction'])

asyncio.run(main())

Multi-Turn ReAct：ReactAgent

如果你更偏好接近 ReAct 论文的多轮对话实现，本项目提供了 ReactAgent。

使用示例：

import asyncio
from webresearcher.react_agent import ReactAgent

llm_config = {
    "model": "gpt-4o",
    "api_key": "your-api-key",      # 可选，默认从环境变量 LLM_API_KEY 读取
    "base_url": "https://api.openai.com/v1",  # 可选，默认从环境变量 LLM_BASE_URL 读取
    "generate_cfg": {"temperature": 0.6}
}

agent = ReactAgent(
    llm_config=llm_config,
    function_list=["search", "google_scholar", "visit", "python"],
)

async def main():
    result = await agent.run("2024 年巴黎的人口是多少？请给出平方根。")
    # 返回结构包含：question / prediction / termination / trajectory
    print(result["prediction"])  # 始终为非空字符串

asyncio.run(main())

日志中的消息轨迹（trajectory）示意：

• system：系统提示
• user：原始问题
• user：合并后的工具调用与返回（<tool_call>... </tool_call> + OBS_START<tool_response>...</tool_response>OBS_END 结果）
• assistant：模型继续推理或给出 <answer> 最终答案

📚 高级用法

测试时扩展 (TTS)

对于需要最高准确性的关键问题，使用 TTS 模式（3-5倍成本）：

webresearcher "复杂问题" --use-tts --num-agents 3

from webresearcher import TestTimeScalingAgent

agent = TestTimeScalingAgent(llm_config, function_list)
result = await agent.run("复杂问题", num_parallel_agents=3)

自定义工具

通过继承 BaseTool 创建您自己的工具：

from webresearcher import BaseTool, WebResearcherAgent, TOOL_MAP

class MyCustomTool(BaseTool):
    name = "my_tool"
    description = "工具功能描述"
    parameters = {"type": "object", "properties": {...}}
    
    def call(self, params, **kwargs):
        # 您的工具逻辑
        return "结果"

# 注册并使用
TOOL_MAP['my_tool'] = MyCustomTool()
agent = WebResearcherAgent(function_list=["my_tool", "search"])

查看 examples/custom_agent.py 获取完整示例。

批量处理

高效处理多个问题：

from webresearcher import WebResearcherAgent

questions = ["问题 1", "问题 2", "问题 3"]
agent = WebResearcherAgent()

for question in questions:
    result = await agent.run(question)
    print(f"Q: {question}\nA: {result['prediction']}\n")

查看 examples/batch_research.py 获取高级批量处理示例。

Python 解释器配置

PythonInterpreter 工具支持两种执行模式：

1. 沙箱模式（生产环境推荐）：

# 配置沙箱端点
export SANDBOX_FUSION_ENDPOINTS="http://your-sandbox-endpoint.com"

2. 本地模式（自动降级）：

• 当未配置 SANDBOX_FUSION_ENDPOINTS 时，代码在本地执行
• 适用于开发和测试
• ⚠️ 警告：本地执行会在当前 Python 环境中运行代码

from webresearcher import PythonInterpreter

# 如果配置了沙箱则使用沙箱，否则降级到本地执行
interpreter = PythonInterpreter()
result = interpreter.call({'code': 'print("Hello, World!")'})

详细示例请参考 examples/python_interpreter_example.py。

日志管理

WebResearcher 提供了统一的日志管理系统，可以通过环境变量或编程方式控制日志级别：

通过环境变量：

# 运行前设置日志级别
export WEBRESEARCHER_LOG_LEVEL=DEBUG  # 选项：DEBUG, INFO, WARNING, ERROR, CRITICAL
webresearcher "你的问题"

编程方式：

from webresearcher import set_log_level, add_file_logger, WebResearcherAgent

# 设置控制台日志级别
set_log_level("WARNING")  # 只显示警告和错误

# 添加文件日志，支持自动轮转
add_file_logger("research.log", level="DEBUG")

# 现在执行研究
agent = WebResearcherAgent()
result = await agent.run("你的问题")

文件日志功能：

• 文件大小超过 10MB 时自动轮转
• 保留最近 7 天的日志
• 自动压缩旧日志为 .zip 格式

详细使用方法请参考 logger.py。

🎯 功能特性

核心特性

• ✅ 迭代综合: 通过周期性报告更新防止上下文溢出
• ✅ 无界深度: 几乎无限的研究轮次
• ✅ 智能 Token 管理: 自动上下文修剪和压缩
• ✅ 异步支持: 非阻塞 I/O 提升性能
• ✅ 强制最终回答（ReactAgent）: 在配额耗尽/超时时保证产出非空答案

工具特性

• ✅ 网页搜索: 通过 Serper 集成 Google 搜索
• ✅ 学术搜索: Google Scholar 查询研究论文
• ✅ 网页抓取: 智能内容提取
• ✅ 代码执行: 沙盒 Python 解释器
• ✅ 文件处理: 支持 PDF、DOCX、CSV、Excel 等
• ✅ 可扩展: 轻松创建自定义工具

生产特性

• ✅ 零框架锁定: 无 qwen-agent 等类似依赖
• ✅ CLI + API: 支持命令行和 Python 调用

📊 性能表现

基于论文的评估结果：

• HotpotQA: 在多跳推理任务上表现优异
• Bamboogle: 在复杂事实问题上表现出色
• 上下文管理: 即使 50+ 轮后仍保持精简的工作空间
• 准确性: 与基线 Agent 相当或超越

🔧 配置

环境变量

# 必需
LLM_API_KEY=...              # LLM API 密钥 (OpenAI/DeepSeek 等)
SERPER_API_KEY=...                 # Serper API（Google 搜索）

# 可选
LLM_BASE_URL=https://...        # 自定义 LLM 端点, 或 DeepSeek base url
LLM_MODEL_NAME=gpt-4o          # 默认模型名称
JINA_API_KEY=...                   # Jina AI（网页抓取）
SANDBOX_FUSION_ENDPOINTS=...       # 代码执行沙盒
MAX_LLM_CALL_PER_RUN=50           # 每次研究的最大迭代次数
FILE_DIR=./files                   # 文件存储目录

LLM 配置

llm_config = {
    "model": "deepseek-v3.1",              # 或: o3-mini, gpt-4-turbo 等
    "api_key": "your-api-key",             # 可选，默认从环境变量 LLM_API_KEY 读取
    "base_url": "https://api.openai.com/v1",  # 可选，默认从环境变量 LLM_BASE_URL 读取
    "generate_cfg": {
        "temperature": 0.6,          # 采样温度 (0.0-2.0)
        "top_p": 0.95,              # 核采样
        "presence_penalty": 1.1,     # 重复惩罚
        "model_thinking_type": "enabled"  # enabled|disabled|auto, 如果不支持thinking，则不设置
    },
    "max_input_tokens": 32000,      # 上下文窗口限制
    "llm_timeout": 300.0,           # LLM API 超时（秒）
    "agent_timeout": 600.0,         # Agent 总超时（秒）
}

🎭 WebWeaver Agent

WebWeaver 是一个双智能体研究框架，实现了动态大纲范式，提供比单智能体 WebResearcher 更结构化的研究方法。

架构组件

1. Memory Bank（记忆库）

共享的证据存储，连接 Planner 和 Writer 智能体：

• 添加证据: Planner 存储发现的内容并分配引用 ID
• 检索证据: Writer 通过 ID 获取特定证据
• 解耦存储: 让智能体专注于各自的任务

2. Planner Agent（规划智能体）

探索研究问题并构建带引用的大纲：

• 操作:
  • search: 从网络收集信息
  • write_outline: 创建/更新带引用的研究大纲
  • terminate: 完成规划阶段
• 输出: 带有引用 ID 的结构化大纲

3. Writer Agent（写作智能体）

逐节撰写综合报告：

• 操作:
  • retrieve: 从 Memory Bank 获取证据
  • write: 撰写带内联引用的报告章节
  • terminate: 完成写作阶段
• 输出: 带有适当引用的完整研究报告

核心特性

动态大纲

与传统静态大纲不同，WebWeaver 的大纲随着新证据的发现而演化：

1. Planner 搜索并发现证据
2. 每个发现获得唯一的引用 ID
3. 大纲更新以纳入新证据
4. 过程重复直到大纲完整

引用支撑的报告

最终报告中的所有声明都有具体证据支持：

• 证据在 Memory Bank 中存储完整上下文
• Writer 仅检索每个章节的相关证据
• 引用内联嵌入（例如 [cite:id_1]）

WebWeaver 使用方法

基础使用

import asyncio
from webresearcher import WebWeaverAgent

async def main():
    # 配置 LLM
    llm_config = {
        "model": "gpt-4o",
        "generate_cfg": {
            "temperature": 0.1,  # 低温度用于事实性研究
            "top_p": 0.95,
            "max_tokens": 10000,
        },
        "llm_timeout": 300.0,
    }
    
    # 初始化智能体
    agent = WebWeaverAgent(llm_config=llm_config)
    
    # 执行研究
    question = "气候变化的主要原因是什么？"
    result = await agent.run(question)
    
    # 访问结果
    print("最终大纲:", result['final_outline'])
    print("最终报告:", result['final_report'])
    print("记忆库大小:", result['memory_bank_size'])

if __name__ == "__main__":
    asyncio.run(main())

命令行使用

# 使用 WebWeaver 模式
webresearcher "气候变化的原因是什么？" --use-webweaver

# 保存结果到文件
webresearcher "研究问题" --use-webweaver --output report.json

# 详细日志
webresearcher "问题" --use-webweaver --verbose

WebResearcher vs WebWeaver 对比

特性	WebResearcher	WebWeaver
架构	单智能体	双智能体
范式	IterResearch	动态大纲
记忆	无状态工作空间	Memory Bank
输出	直接答案	大纲 + 报告
引用	隐式	显式带 ID
结构	迭代综合	层次化
适用场景	快速问答	综合报告

何时使用 WebWeaver

选择 WebWeaver 当您需要：

• ✅ 长篇、综合性研究报告
• ✅ 显式引用追踪
• ✅ 带证据映射的结构化大纲
• ✅ 可复现的研究过程
• ✅ 多章节文档

选择 WebResearcher 当您需要：

• ✅ 快速、聚焦的答案
• ✅ 更简单的架构
• ✅ 直接的问答格式
• ✅ 更低的 Token 使用量
• ✅ 更快的结果

📝 示例

查看 examples/ 目录获取完整示例：

• webresearcher_usage.py - WebResearcher Agent 使用示例
• batch_research.py - 批量处理多个问题
• custom_agent.py - 创建自定义工具
• webweaver_usage.py - WebWeaver Agent 使用示例

🧪 测试

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行覆盖率测试
pytest --cov=webresearcher

🤝 参与贡献

我们欢迎各种形式的贡献！

贡献方式：

• 🐛 报告 Bug
• 💡 提出新功能建议
• 📝 改进文档
• 🔧 提交 Pull Request

详细指南请查看 CONTRIBUTING.md。

📧 联系方式

• GitHub Issues: 报告问题或功能请求
• 邮箱: xuming624@qq.com
• 微信: xuming624（备注：姓名-公司-NLP）