使用 OpenAI Agents SDK 的智能体式深度研究

一款基于 OpenAI Agents SDK 构建的强大深度研究助手，旨在对任何给定主题进行深入研究。兼容 Azure OpenAI、OpenAI、Anthropic、Gemini、DeepSeek、Perplexity、OpenRouter、Hugging Face 以及 Ollama 等本地模型。

它采用多智能体架构，以迭代方式工作，不断深化对主题的理解，并生成越来越详细的见解，最终汇集成完整的报告。

该工具设计为可扩展，支持使用自定义工具以及任何符合 OpenAI API 规范的第三方大语言模型。LLM 和工具调用可以选择性地通过 OpenAI 的追踪功能进行跟踪。

相关背景介绍 在此。

概述

本包提供两种研究模式：

• IterativeResearcher：针对某个主题或子主题持续循环进行研究并撰写报告。
  • 推荐使用此模式，且适用于较短的报告（最多 5 页 / 1,000 字）。
  • 用户可以指定研究深度、时间限制、报告长度和格式要求等约束条件。
• DeepResearcher：执行更为全面和结构化的流程，首先制定报告大纲，然后为报告的每个部分并行运行多个 IterativeResearcher 实例。
  • 适用于较长的报告（例如 20 页以上）。

DeepResearcher 的工作流程如下：

1. 接收研究主题，进行初步研究以形成报告大纲/计划。
2. 针对报告计划中的每个部分，同时运行多个 IterativeResearcher 实例：
   1. 识别当前研究中的知识空白；
   2. 有针对性地选择合适的工具来填补这些空白；
   3. 通过专业智能体执行研究任务；
   4. 将研究成果综合成一个完整的章节。
3. 将所有章节整合成一份连贯且结构清晰的报告。

值得注意的是，深度研究智能体在开始时不会提出澄清性问题，因此可以以自动化方式使用。

示例输出

深度研究示例（使用 DeepResearcher）：

• 柏拉图生平与著作 - 7,980 字
• 量子计算教材 - 5,253 字
• 特斯拉深度解析 - 4,732 字

简单研究示例（使用 IterativeResearcher）：

• Quantera 市场规模 - 1,001 字
• 英国政府政策 - 1,077 字

流程图

IterativeResearcher 流程

flowchart LR
    A["用户输入<br>- 查询内容<br>- 最大迭代次数<br>- 最大时间<br>- 输出指令"] --> B

    subgraph "深度研究循环"
        B["知识空白智能体"] -->|"当前空白<br>及目标"| C["工具选择智能体"]
        C -->|"工具查询<br>(并行执行)"| D["工具智能体<br>- 网络搜索<br>- 爬虫<br>- 自定义工具"]
        D -->|"新发现"| E["观察智能体"]
        E --> |"对发现及研究策略的思考"| B
    end

    E --> F["撰写智能体<br>(最终输出<br>附参考文献)"]

DeepResearcher 流程

flowchart LR
    A["用户输入<br>- 查询内容<br>- 最大迭代次数<br>- 最大时间"] --> B["规划智能体"]
    
    B -->|"报告计划<br>(章节及背景信息)"| D2
    
    subgraph 并行["并行章节研究"]
        D1["IterativeResearcher<br>(第1章)"]
        D2["IterativeResearcher<br>(第2章)"]
        D3["IterativeResearcher<br>(第3章)"]
    end
    
    D1 -->|"第1章<br>草稿"| E["校对智能体"]
    D2 -->|"第2章<br>草稿"| E
    D3 -->|"第3章<br>草稿"| E
    
    E --> F["最终<br>研究报告"]

安装

使用 pip 安装：

pip install deep-researcher

或者克隆 GitHub 仓库：

git clone https://github.com/qx-labs/agents-deep-research.git
cd agents-deep-research
pip install -r requirements.txt

然后创建包含 API 密钥的 .env 文件：

cp .env.example .env

编辑 .env 文件，根据需要添加 OpenAI、Serper 等设置，例如：

OPENAI_API_KEY=<your_key>
SEARCH_PROVIDER=serper  # 或设置为 openai
SERPER_API_KEY=<your_key>

使用方法

Python 模块

# 可参阅 /examples 文件夹获取完整示例
import asyncio
from deep_researcher import IterativeResearcher, DeepResearcher

# 对于简单查询，运行 IterativeResearcher
researcher = IterativeResearcher(max_iterations=5, max_time_minutes=5)
query = "请提供关于量子计算的全面概述"
report = asyncio.run(
    researcher.run(query, output_length="5 页")
)

# 对于更长且结构化程度更高的报告，运行 DeepResearcher
researcher = DeepResearcher(max_iterations=3, max_time_minutes=5)
report = asyncio.run(
    researcher.run(query)
)

print(report)

运行时自定义 LLM 配置

在 Python 中运行深度研究时，您可以在运行时设置自定义的 LLM 配置变量，从而在代码中动态切换模型选择。

import asyncio
from deep_researcher import DeepResearcher, LLMConfig

# 这些配置选项将优先于环境变量
llm_config = LLMConfig(
    search_provider="serper",
    reasoning_model_provider="openai",
    reasoning_model="o3-mini",
    main_model_provider="openai",
    main_model="gpt-4o",
    fast_model_provider="openai",
    fast_model="gpt-4o-mini"
)
researcher = DeepResearcher(max_iterations=3, max_time_minutes=5, config=llm_config)
report = asyncio.run(
    researcher.run(query)
)

命令行

从命令行运行研究助理。

如果你通过 pip 安装的：

deep-researcher --mode deep --query "提供量子计算的全面概述" --max-iterations 3 --max-time 10 --verbose

或者如果你克隆了 GitHub 仓库：

python -m deep_researcher.main --mode deep --query "提供量子计算的全面概述" --max-iterations 3 --max-time 10 --verbose

参数说明：

• --query：研究主题或问题（如果不提供，系统会提示您输入）
• --mode：如果设置为 deep，则使用 DeepResearcher；如果设置为 simple，则使用 IterativeResearcher（默认值为 deep）
• --max-iterations：最大研究迭代次数（默认值为 5）
• --max-time：研究循环在自动退出以生成最终报告之前的最大时间（单位：分钟；默认值为 10）
• --output-length：报告期望的长度（默认值为“5页”）
• --output-instructions：对最终报告的额外格式化说明

布尔标志：

• --verbose：将研究进度打印到控制台
• --tracing：在 OpenAI 平台上跟踪工作流（仅适用于 OpenAI 模型）

兼容模型

Deep Researcher 设计用于运行任何符合 OpenAI API 规范的模型，并通过调整 base_url 参数来适配相应的模型提供商。兼容的提供商包括 Azure OpenAI、OpenAI、Anthropic、Gemini、DeepSeek、Hugging Face 和 OpenRouter，以及通过 Ollama 和 LM Studio 运行的本地托管模型。

然而，为了确保 Deep Researcher 能够顺利运行且不出现错误，它依赖于在工具调用方面表现优异的模型。

• 如果使用 OpenAI 模型，我们发现 gpt-4o-mini 在工具选择方面的效果与 o3-mini 不相上下，甚至更好（这与 此排行榜 的结果一致）。鉴于其速度和成本优势，我们建议在工作流中大多数代理使用 gpt-4o-mini，而将 o3-mini 用于规划任务，gpt-4o 则用于最终撰写。
• 如果使用 Gemini 模型，请注意只有 Gemini 2.5 Pro（当前为 gemini-2.5-pro-preview-03-25）表现良好。Gemini 2.0 Flash（gemini-2.0-flash）虽然被列为支持工具调用，但经常无法成功调用任何工具。

架构

Deep Research Assistant 由以下组件构成：

核心组件

• IterativeResearcher：协调单个主题或子主题的迭代式研究流程
• DeepResearcher：协调更深入、更广泛的流程，包括初始报告大纲、并行调用多个 IterativeResearch 实例，以及最后的校对步骤
• LLMConfig：管理与语言模型的交互，以便根据需要随时更换模型

代理系统

• 知识缺口代理：分析当前研究状态，识别知识上的空白
• 工具选择代理：确定用于填补特定知识缺口的工具
• 工具代理：专门执行特定研究任务的代理（可扩展以添加自定义工具）：
  • 网络搜索代理
  • 网站爬虫代理
• 撰写代理：将研究发现整合成连贯的报告

研究工具

• 网络搜索：通过 SERP 查询查找相关信息
  • 我们的实现默认使用 Serper 来运行 Google 搜索，这需要将 API 密钥设置到 SERPER_API_KEY 环境变量中。
  • 您可以通过将环境变量 SEARCH_PROVIDER 设置为 openai，将其替换为 OpenAI 的原生网络搜索工具。
• 网站爬虫：从给定网站的页面中提取详细内容

实现自定义工具代理

工具代理是专门使用一个或多个工具来执行特定任务的代理（例如网络搜索、从 API 获取并解释数据等）。要实现自定义工具代理：

• 在 deep_researcher/tools 文件夹中创建代理将使用的任何工具
• 在 deep_researcher/agents/tool_agents 文件夹中创建调用该工具的新工具代理
• 将工具代理的定义添加到 deep_researcher/agents/tool_agents/__init__.py 中的 init_tool_agents 函数中
• 更新 deep_researcher/agents/tool_selector_agent.py 的系统提示，加入新代理的名称和描述，以便 ToolSelectorAgent 能够识别它的存在

配置自定义 LLM

理论上，本仓库与任何遵循 OpenAI API 规范的 LLM 都兼容。这包括 DeepSeek 以及通过 OpenRouter 提供的模型。然而，这些模型需要与 OpenAI API 规范中的 结构化输出 兼容（即能够设置 response_format: {type: "json_schema", ...}）。

LLM 的配置和管理在 deep_researcher/llm_config.py 文件中进行。

跟踪监控

Deep Research Assistant 集成了 OpenAI 的跟踪监控系统。每次研究会话都会生成一个跟踪 ID，可用于通过 OpenAI 平台实时监控执行流程和代理之间的交互。

观察与局限性

速率限制

• DeepResearcher 会并行执行大量搜索和 API 调用（在任何给定时刻，它可能正在抓取 50–60 个不同的网页）。因此，您可能会遇到 OpenAI、Gemini、Anthropic 等模型提供商的速率限制，尤其是在使用较低或免费层级时。
• 如果遇到此类错误，您可以改用消耗较少 API 调用的 IterativeResearcher。

输出长度

LLM 对于严格遵循输出长度指导并不擅长。通常会出现以下两个问题：

• LLM 不擅长计数。在给出长度指示时，最好提供模型在其训练数据中熟悉的参考标准（如“一条推文的长度”、“几段文字”、“一本书的长度”），而不是具体的字数。
• 尽管许多模型的输出 token 限制非常大，但很难让它们每次回复生成超过 1–2 千字的内容。有一些方法可以生成更长的输出，例如 这种方法。

我们为 IterativeResearcher 添加了 output_length 参数，以便用户更好地控制输出长度，但请务必考虑到上述局限性。

待办事项：

• 为不同模型提供商添加单元测试
• 添加针对不同模型的示例实现
• 增加与其他搜索引擎提供商的兼容性（如 SearXNG、Bing、Tavily、DuckDuckGo 等）
• 添加缓存功能（如 Redis），以避免重复抓取网页或重复调用
• 添加更多专业化的研究工具（如维基百科、arXiv、数据分析等）
• 添加 PDF 解析器
• 添加本地文件集成 / RAG 功能

作者

由 Jai Juneja 在 QX Labs 创建。

agents-deep-research 快速上手指南

agents-deep-research 是一个基于 OpenAI Agents SDK 构建的强大深度研究助手。它采用多智能体架构，能够迭代式地深入调研任何主题，并生成结构化的研究报告。支持 OpenAI、Azure、Anthropic、Gemini、DeepSeek 以及本地模型（如 Ollama）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：建议 Python 3.10 或更高版本
• API Keys：
  • LLM 密钥：OpenAI API Key（默认），或兼容 OpenAI 接口规范的其它模型密钥（如 DeepSeek、Azure OpenAI 等）。
  • 搜索服务密钥：默认使用 Serper 进行网络搜索，需准备 SERPER_API_KEY。也可配置为使用 OpenAI 原生搜索工具。

安装步骤

您可以通过 PyPI 直接安装，或克隆源代码进行自定义开发。

方式一：通过 pip 安装（推荐）

pip install deep-researcher

方式二：从源码安装

git clone https://github.com/qx-labs/agents-deep-research.git
cd agents-deep-research
pip install -r requirements.txt

配置环境变量

安装完成后，在项目根目录创建 .env 文件并填入您的密钥：

cp .env.example .env

编辑 .env 文件，配置必要的 API Key：

OPENAI_API_KEY=<your_openai_key>
SEARCH_PROVIDER=serper
SERPER_API_KEY=<your_serper_key>

提示：如果您使用国内模型（如 DeepSeek）或本地模型（Ollama），可在代码运行时通过 LLMConfig 动态指定 base_url 和模型名称，无需修改环境变量中的默认值。

基本使用

该工具提供两种研究模式：

1. IterativeResearcher：适用于简短报告（约 5 页以内），单线程迭代调研。
2. DeepResearcher：适用于长篇深度报告（20 页+），先生成大纲，再并行调用多个智能体分章节调研。

1. Python 模块调用

创建一个 Python 文件（例如 run_research.py）：

import asyncio
from deep_researcher import IterativeResearcher, DeepResearcher

# --- 模式 A: 简单快速调研 (IterativeResearcher) ---
# 适合短报告，用户可指定最大迭代次数和时间
researcher_simple = IterativeResearcher(max_iterations=5, max_time_minutes=5)
query = "Provide a comprehensive overview of quantum computing"
report_simple = asyncio.run(
    researcher_simple.run(query, output_length="5 pages")
)
print("简单调研报告完成")

# --- 模式 B: 深度结构化调研 (DeepResearcher) ---
# 适合长报告，自动规划大纲并并行处理各章节
researcher_deep = DeepResearcher(max_iterations=3, max_time_minutes=10)
report_deep = asyncio.run(
    researcher_deep.run(query)
)
print("深度调研报告完成")
print(report_deep)

动态配置模型示例（以使用 DeepSeek 为例）：

import asyncio
from deep_researcher import DeepResearcher, LLMConfig

llm_config = LLMConfig(
    search_provider="serper",
    reasoning_model_provider="openai_compatible", # 假设使用兼容接口
    reasoning_model="deepseek-chat",
    main_model_provider="openai_compatible",
    main_model="deepseek-chat",
    fast_model_provider="openai_compatible",
    fast_model="deepseek-chat"
)
# 注意：实际使用时需在代码中设置正确的 base_url，此处仅为配置结构示意
# 具体 base_url 设置需参考 llm_config.py 实现或通过环境变量注入

researcher = DeepResearcher(max_iterations=3, max_time_minutes=5, config=llm_config)
report = asyncio.run(researcher.run("量子计算概述"))

2. 命令行调用

如果您通过 pip 安装了包，可以直接在终端运行：

# 深度研究模式
deep-researcher --mode deep --query "Provide a comprehensive overview of quantum computing" --max-iterations 3 --max-time 10 --verbose

# 简单研究模式
deep-researcher --mode simple --query "UK Government Policies" --max-iterations 2 --max-time 5

如果您是从源码克隆的仓库，请使用以下命令：

python -m deep_researcher.main --mode deep --query "Provide a comprehensive overview of quantum computing" --max-iterations 3 --max-time 10 --verbose

常用参数说明：

• --query: 研究主题或问题。
• --mode: deep (深度模式) 或 simple (简单模式)，默认为 deep。
• --max-iterations: 最大研究迭代次数。
• --max-time: 最大运行时间（分钟），超时后会自动生成当前最佳报告。
• --verbose: 打印详细的研究进度日志。
• --tracing: 启用 OpenAI 平台的流程追踪（仅限 OpenAI 模型）。