🧱 从零开始的深度研究

深度研究已成为最受欢迎的智能体应用之一。OpenAI、Anthropic、Perplexity 和 Google 都推出了深度研究产品，这些产品能够利用多种来源的上下文信息生成全面的报告。此外，还有许多开源的实现可供使用。我们构建了一个简单且可配置的开源深度研究员，允许用户引入自己的模型、搜索工具和 MCP 服务器。在本仓库中，我们将从头开始构建一个深度研究员！以下是我们将要构建的主要模块图：

🚀 快速入门

前置条件

• Node.js 和 npx（第 3 个笔记本中的 MCP 服务器需要）：

# 安装 Node.js（包含 npx）
# 在 macOS 上使用 Homebrew：
brew install node

# 在 Ubuntu/Debian 上：
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装：
node --version
npx --version

• 确保您使用的是 Python 3.11 或更高版本。
• 此版本是与 LangGraph 最佳兼容所必需的。

python3 --version

• uv 包管理器

curl -LsSf https://astral.sh/uv/install.sh | sh
# 更新 PATH 以使用新的 uv 版本
export PATH="/Users/$USER/.local/bin:$PATH"

安装

1. 克隆仓库：

git clone https://github.com/langchain-ai/deep_research_from_scratch
cd deep_research_from_scratch

2. 安装软件包及依赖项（此操作会自动创建并管理虚拟环境）：

uv sync

3. 在项目根目录下创建 .env 文件，并填入您的 API 密钥：

# 创建 .env 文件
touch .env

将您的 API 密钥添加到 .env 文件中：

# 用于具有外部搜索功能的研究智能体
TAVILY_API_KEY=your_tavily_api_key_here

# 用于模型调用
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 可选：用于评估和追踪
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=deep_research_from_scratch

4. 使用 uv 运行笔记本或代码：

# 直接运行 Jupyter 笔记本
uv run jupyter notebook

# 或者如果您更喜欢激活虚拟环境
source .venv/bin/activate  # Windows 上：.venv\Scripts\activate
jupyter notebook

背景

研究是一项开放性的任务；很难提前确定回答用户请求的最佳策略。不同的请求可能需要不同的研究策略以及不同程度的搜索深度。请考虑以下请求。

智能体非常适合进行研究，因为它们能够灵活地应用不同的策略，并利用中间结果来指导探索过程。开源深度研究系统采用智能体，通过三步流程来进行研究：

1. 界定范围 – 明确研究范围
2. 研究 – 执行研究
3. 撰写 – 生成最终报告

📝 组织结构

本仓库包含 5 个教程笔记本，将从零开始构建一个深度研究系统：

📚 教程笔记本

1. 用户澄清与简报生成（notebooks/1_scoping.ipynb）

目的：明确研究范围，并将用户输入转化为结构化的研究简报。

关键概念：

• 用户澄清：通过结构化输出判断是否需要用户补充更多上下文。
• 简报生成：将对话内容转化为详细的研究问题。
• LangGraph 命令：利用命令系统进行流程控制和状态更新。
• 结构化输出：使用 Pydantic 模型实现可靠决策。

实现亮点：

• 两步工作流：澄清 → 简报生成。
• 使用结构化输出模型（ClarifyWithUser、ResearchQuestion）以防止幻觉。
• 根据澄清需求进行条件路由。
• 基于日期的提示词，支持上下文敏感的研究。

学习要点：状态管理、结构化输出模式、条件路由。

---

2. 带有自定义工具的研究代理（notebooks/2_research_agent.ipynb）

目的：构建一个使用外部搜索工具的迭代式研究代理。

关键概念：

• 代理架构：LLM 决策节点 + 工具执行节点模式。
• 顺序工具执行：可靠且同步的工具执行机制。
• 搜索集成：Tavily 搜索结合内容摘要。
• 工具执行：基于 ReAct 风格的代理循环，支持工具调用。

实现亮点：

• 同步工具执行，确保可靠性和简洁性。
• 内容摘要用于压缩搜索结果。
• 迭代式研究循环，配合条件路由。
• 丰富的提示工程设计，支持全面的研究任务。

学习要点：代理模式、工具集成、搜索优化、研究工作流设计。

---

3. 带有 MCP 的研究代理（notebooks/3_research_agent_mcp.ipynb）

目的：将模型上下文协议（MCP）服务器作为研究工具集成进来。

关键概念：

• 模型上下文协议：AI 工具访问的标准化协议。
• MCP 架构：通过 stdio/HTTP 实现客户端-服务器通信。
• LangChain MCP 适配器：无缝将 MCP 服务器集成为 LangChain 工具。
• 本地与远程 MCP：理解不同的传输机制。

实现亮点：

• 使用 MultiServerMCPClient 管理 MCP 服务器。
• 基于配置的服务器设置（如文件系统示例）。
• 丰富的格式化设计，用于展示工具输出。
• 符合 MCP 协议要求的异步工具执行（无需嵌套事件循环）。

学习要点：MCP 集成、客户端-服务器架构、基于协议的工具接入。

---

4. 研究主管（notebooks/4_research_supervisor.ipynb）

目的：通过多智能体协作完成复杂的研究任务。

关键概念：

• 主管模式：协调代理 + 工作代理。
• 并行研究：利用并行工具调用，同时开展多个独立主题的研究。
• 研究委托：通过结构化工具进行任务分配。
• 上下文隔离：为不同研究主题维护独立的上下文窗口。

实现亮点：

• 采用双节点主管模式（supervisor + supervisor_tools）。
• 使用 asyncio.gather() 实现真正的并行执行。
• 通过结构化工具（ConductResearch、ResearchComplete）进行任务委派。
• 增强型提示词，包含并行研究指令。
• 详尽记录研究结果的聚合模式。

学习要点：多智能体模式、并行处理、研究协调、异步编排。

---

5. 完整的多智能体研究系统（notebooks/5_full_agent.ipynb）

目的：构建一个整合所有组件的端到端研究系统。

关键概念：

• 三阶段架构：范围界定 → 研究执行 → 报告撰写。
• 系统集成：将范围界定、多智能体研究和报告生成有机结合。
• 状态管理：跨子图的复杂状态流转。
• 端到端工作流：从用户输入到最终研究报告。

实现亮点：

• 完整的工作流集成，确保状态的正确过渡。
• 包含输出模式的主管与研究人员子图。
• 最终报告生成及研究结果综合。
• 基于线程的对话管理，用于澄清环节。

学习要点：系统架构、子图组合、端到端工作流。

---

🎯 主要学习成果

• 结构化输出：利用 Pydantic 模型实现可靠的 AI 决策。
• 异步编排：合理运用异步模式，在并行协调与同步简洁之间取得平衡。
• 代理模式：ReAct 循环、主管模式、多智能体协作。
• 搜索集成：外部 API、MCP 服务器、内容处理。
• 工作流设计：LangGraph 模式适用于复杂的多步骤流程。
• 状态管理：跨子图和节点的复杂状态流转。
• 协议集成：MCP 服务器及其他工具生态系统的接入。

每个笔记本都在前一节的基础上逐步深入，最终形成一套可投入生产的深度研究系统，能够智能地界定范围并协调执行，从而高效应对复杂、多维度的研究需求。

Deep Research From Scratch 快速上手指南

本指南帮助开发者从零开始构建一个可配置的深度研究智能体系统。该系统支持自定义模型、搜索工具及 MCP 服务器，能够自动完成“明确范围 -> 执行研究 -> 撰写报告”的全流程。

环境准备

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

系统要求

• Python: 版本 3.11 或更高（LangGraph 最佳兼容性要求）。
• Node.js: 必须安装（包含 npx），用于运行笔记本 3 中的 MCP 服务器。

前置依赖安装

1. 安装 Node.js

• macOS (使用 Homebrew):

  brew install node
  

• Ubuntu/Debian:

  curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
  sudo apt-get install -y nodejs
  

• 验证安装:

  node --version
  npx --version
  

2. 安装 uv 包管理器 本项目推荐使用 uv 进行依赖管理和虚拟环境创建。

curl -LsSf https://astral.sh/uv/install.sh | sh
# 更新 PATH 以使用新安装的 uv (根据实际输出调整路径，通常为 ~/.local/bin)
export PATH="/Users/$USER/.local/bin:$PATH"

3. 验证 Python 版本

python3 --version
# 确保输出为 Python 3.11.x 或更高

安装步骤

1. 克隆仓库

git clone https://github.com/langchain-ai/deep_research_from_scratch
cd deep_research_from_scratch

2. 同步依赖 使用 uv 自动创建并激活虚拟环境，同时安装所有必要依赖：

uv sync

3. 配置 API 密钥 在项目根目录创建 .env 文件：

touch .env

编辑 .env 文件，填入您的 API 密钥：

# 必需：用于外部搜索代理
TAVILY_API_KEY=your_tavily_api_key_here

# 必需：用于模型调用 (任选其一或全部配置)
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 可选：用于评估和追踪 (LangSmith)
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=deep_research_from_scratch

基本使用

本项目通过一系列 Jupyter Notebook 教程逐步构建系统。最简单的启动方式是直接运行交互式笔记本环境。

1. 启动 Jupyter Notebook 使用 uv run 直接在配置好的环境中启动：

uv run jupyter notebook

或者手动激活虚拟环境后启动：

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

jupyter notebook

2. 开始第一个教程 在浏览器打开的 Jupyter 界面中，依次进入 notebooks/ 目录，从 1_scoping.ipynb 开始执行。

• 步骤 1 (1_scoping.ipynb): 学习如何将用户模糊的请求转化为结构化的研究简报。
• 步骤 2 (2_research_agent.ipynb): 构建带有搜索工具的研究代理。
• 后续步骤: 逐步集成 MCP 服务器、多代理协作，最终在 5_full_agent.ipynb 中运行完整的端到端研究系统。

提示: 每个笔记本都包含详细的代码单元格和解释，按顺序执行即可体验完整的深度研究工作流。