🧱 从零构建深度智能体

Deep Research 与编程一起，成为最早出现的主要智能体应用场景之一。如今，我们正见证通用型智能体的兴起，它们能够胜任各种任务。例如，Manus 因其长周期任务而备受关注和欢迎；平均每个 Manus 任务会调用约 50 次工具！再比如，Claude Code 现已广泛应用于编程之外的其他任务。仔细梳理这些热门“深度”智能体中的 上下文工程模式，可以发现一些共通的方法：

• 任务规划（如 TODO 列表），通常配合复述机制
• 将上下文卸载到文件系统
• 通过子智能体委派实现上下文隔离

本课程将展示如何使用 LangGraph 从头开始实现这些模式！

🚀 快速入门

前提条件

• 确保您使用的是 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-agents-from-scratch.git
cd deep_agents_from_scratch

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

uv sync

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

# 创建 .env 文件
touch .env

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

# 用于具备外部搜索功能的研究型智能体
TAVILY_API_KEY=your_tavily_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-agents-from-scratch

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

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

# 或者如果您更习惯，可以激活虚拟环境
source .venv/bin/activate  # Windows 上：.venv\Scripts\activate
jupyter notebook

📚 教程概览

本仓库包含五个循序渐进的笔记本，教您构建高级 AI 智能体：

0_create_agent.ipynb -

学习如何使用 create_agent 组件。该组件：

• 实现了 ReAct（推理-行动）循环，这是许多智能体的基础。
• 使用简单、设置快速。
• 作为

1_todo.ipynb - 任务规划基础

学习如何使用 TODO 列表实现结构化任务规划。本笔记本介绍：

• 带状态管理的任务跟踪（待办/进行中/已完成）
• 进度监控与上下文管理
• write_todos() 工具，用于组织复杂的多步工作流
• 保持专注、防止任务偏离的最佳实践

2_files.ipynb - 虚拟文件系统

实现存储在智能体状态中的虚拟文件系统，用于上下文卸载：

• 文件操作：ls()、read_file()、write_file()、edit_file()
• 通过信息持久化进行上下文管理
• 使智能体能够在多次对话轮次中“记忆”信息
• 通过将详细信息存储在文件中来减少令牌消耗

3_subagents.ipynb - 上下文隔离

掌握子智能体委派技术，以处理复杂的工作流：

• 创建具有特定工具集的专业子智能体
• 通过上下文隔离避免混淆和任务干扰
• task() 委派工具与智能体注册表模式
• 支持独立研究流程的并行执行能力

4_full_agent.ipynb - 完整的研究型智能体

将所有技术整合成一个可投入生产的研究型智能体：

• 集成 TODO 列表、文件和子智能体
• 结合智能上下文卸载的真实网络搜索
• 内容摘要与战略思考工具
• 与 LangGraph Studio 集成，完成复杂研究任务的完整工作流

每个笔记本都建立在前一个概念的基础上，最终形成一套能够应对现实世界研究与分析任务的成熟智能体架构。

deep-agents-from-scratch 快速上手指南

本指南帮助中国开发者快速搭建基于 LangGraph 的高级 AI Agent（智能体），实现任务规划、上下文卸载及子代理 delegation 等核心功能。

环境准备

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

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python 版本：必须为 Python 3.11 或更高版本（LangGraph 最佳兼容性要求）。

  python3 --version
  

• 包管理器：推荐使用 uv，它比 pip 更快且能自动管理虚拟环境。
  • 安装 uv (国内用户若下载缓慢，可尝试配置代理或使用镜像):

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  • 配置环境变量 (将 uv 加入 PATH):

  export PATH="/Users/$USER/.local/bin:$PATH"
  # Windows PowerShell: $env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"
  

安装步骤

1. 克隆项目

从 GitHub 获取源代码并进入目录：

git clone https://github.com/langchain-ai/deep-agents-from-scratch.git
cd deep-agents-from-scratch

提示：如果 git clone 速度较慢，可使用国内镜像源： git clone https://gitee.com/mirrors/deep-agents-from-scratch.git (注：若官方无 Gitee 镜像，请配置本地 git proxy)

2. 安装依赖

使用 uv 同步依赖并自动创建虚拟环境：

uv sync

3. 配置 API 密钥

在项目根目录创建 .env 文件，并填入必要的 API Key。本项目主要依赖 Anthropic 模型和 Tavily 搜索工具。

touch .env

编辑 .env 文件，填入以下内容（替换为您的真实密钥）：

# 必需：用于外部搜索工具 (Tavily)
TAVILY_API_KEY=your_tavily_api_key_here

# 必需：用于调用大模型 (Anthropic Claude)
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 可选：用于评估和链路追踪 (LangSmith)
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=deep-agents-from-scratch

基本使用

本项目通过一系列 Jupyter Notebook 教程循序渐进地构建 Agent。最直接的启动方式是运行交互式笔记本。

启动 Jupyter Notebook

使用 uv run 直接启动开发环境：

uv run jupyter notebook

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

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

jupyter notebook

运行第一个示例

在浏览器打开的 Jupyter 界面中，依次打开以下文件进行学习：

1. 基础入门：打开 0_create_agent.ipynb
   • 学习如何使用 create_agent 组件构建基础的 ReAct (Reason-Act) 循环 Agent。
2. 进阶实践：按顺序运行后续笔记本
   • 1_todo.ipynb: 实现待办事项列表进行任务规划。
   • 2_files.ipynb: 构建虚拟文件系统以卸载上下文。
   • 3_subagents.ipynb: 实现子代理委派与上下文隔离。
   • 4_full_agent.ipynb: 整合所有功能，运行完整的深度研究 Agent。

每个 Notebook 均包含可执行的代码单元格，按顺序执行即可体验从简单到复杂的 Agent 构建过程。