可能是全网最适合用于系统学习 DeepAgents 的多智能体深度研究实战项目，配套系统性文字教程与对应章节分支，带你打通主智能体调度、专家助手分工、多来源检索、文件交付与前后端实时联动全链路
📢 说明：本套实战项目已于 2026 年 5 月 17 日 更新完成，配套教程、章节分支和前后端代码均可对照学习。
如果你正在找一个适合学习 DeepAgents、WebSocket、Tavily、RAGFlow 和 AI Agent 工程开发的实战项目，「深度研搜」很可能是最适合你的项目。
它不是只调用一次大模型接口，也不是套一个搜索 API 做问答演示。这个项目围绕深度研究场景，用 DeepAgents 组织主智能体和专家子智能体，让系统可以根据任务需要查公开网络、查结构化数据库、查 RAGFlow 私有知识库、读取用户上传附件，并把最终结果整理成回答、Markdown 或 PDF。换句话说，你学到的不是某一个框架 API，而是一条 AI 应用从多智能体规划、工具接入、上下文隔离、接口交付到前端联调的完整项目主线。
本套仓库是 ai-agents-from-zero 教程体系中的 实战项目-深度研搜 配套源码仓库，除了可直接运行和二次开发的项目代码之外，也提供了与教程章节对应的 Git 分支演进过程，以及完整的在线图文讲义入口。 如果你想系统学习「AI 智能体 大模型应用开发」，也可直接从系统教程 AI 智能体实战速成指南-大模型入门 开始。
在真实研究场景里，用户的问题经常不是一句普通问答可以解决的。
比如：
结合公开资料、数据库信息和我上传的文档，整理一份机器人行业研究报告，并生成 PDF。
这个任务背后可能包含多类动作：
- 判断需要公开资料、内部数据、私有知识库还是本次上传文件；
- 去互联网搜索最新新闻、政策、产品或行业资料；
- 到 MySQL 查询企业结构化业务数据；
- 到 RAGFlow 查询内部非结构化文档；
- 读取用户上传的 PDF、Word、Excel、Markdown 或文本文件；
- 汇总多来源信息，判断资料是否足够；
- 生成 Markdown 报告，并在需要时转换成 PDF；
- 把执行过程、最终结果和生成文件实时展示给前端。
所以「深度研搜」更像一个会分工、会查资料、会生成交付物的研究助手。用户只需要提出任务，系统会在后端组织一条可观察的多智能体执行链路。
用户任务
-> FastAPI 接口接收请求
-> run_deep_agent 创建会话目录并写入上下文
-> 主智能体分析任务
-> 分派给网络搜索助手 / 数据库查询助手 / RAGFlow 助手
-> 主智能体汇总多来源信息
-> 调用文件工具生成 Markdown / PDF
-> monitor 通过 WebSocket 推送进度
-> 前端展示事件、答案和文件列表
- 一主三从的多智能体架构
- 主智能体负责理解任务、规划步骤、调度助手和最终汇总。
- 网络搜索助手、数据库查询助手、RAGFlow 助手分别处理不同信息来源。
- 多来源检索，而不是模型裸答
Tavily负责互联网公开资料检索。MySQL负责查询结构化业务数据。RAGFlow负责查询内部非结构化文档。- 上传附件由主智能体通过文件工具读取。
- 从检索到交付的完整可运行链路
- 不停留在 Prompt 设计，而是会真实调用工具、读取数据、生成 Markdown，并在需要时转换成 PDF。
- 长任务执行过程可观察
- 工具调用、子智能体调用、工作目录创建、任务结果、取消和异常都会通过
monitor推送到前端。
- 工具调用、子智能体调用、工作目录创建、任务结果、取消和异常都会通过
- 会话级上下文隔离
- 通过
thread_id和session_dir区分不同任务，ContextVar让深层工具也能拿到当前会话身份和文件目录。
- 通过
- 工程化前后端结构清晰
- 基于
FastAPI + WebSocket + DeepAgents + React组织任务接口、异步执行、事件推送、文件上传和文件下载。
- 基于
- 不仅有实战代码，还有完整配套教程文档
- 项目配有一套系统化、完全免费的教程讲义，适合按章节从 DeepAgents 基础、子智能体、Backend、中间件一直学到完整项目闭环。
- 兼顾学习价值与可扩展性
- 既可以按教程章节逐步理解，也可以在此基础上继续扩展权限控制、任务队列、事件持久化、评测体系等能力。
这套课程十分适合这些场景：
- 想系统学习
DeepAgents，但不想只停留在几个玩具示例。 - 想把
Tavily、MySQL、RAGFlow和大模型放到同一个研究助手场景里理解。 - 想做一个比简单模型调用更接近真实开发的 AI Agent 项目。
- 想把项目写进简历，并且能说清楚智能体层、工具层、服务层、文件层和前端层分别做了什么。
项目采用 DeepAgents 中典型的 Orchestrator-Workers 模式：主智能体作为调度中心，三个专家助手负责信息获取，文件工具由主智能体直接掌握。
项目围绕两条主线展开：
| 主线 | 做什么 | 涉及模块 |
|---|---|---|
| 多智能体深度研搜 | 基于用户任务完成规划、分派、检索、读取附件、汇总和生成交付物 | DeepAgents / LangChain / LangGraph / Tavily / MySQL / RAGFlow |
| 前后端实时闭环 | 启动后台任务、上传文件、推送执行过程、展示结果和下载生成文件 | FastAPI / WebSocket / React / Vite |
| 归属 | 能力 | 工具 |
|---|---|---|
| 主智能体 | 任务规划、助手调度、结果汇总、文件交付 | read_file_content、generate_markdown、convert_md_to_pdf |
| 网络搜索助手 | 查询互联网公开信息、新闻、政策和网页资料 | internet_search |
| 数据库查询助手 | 发现表名、预览表结构和样例数据、执行 SQL | list_sql_tables、get_table_data、execute_sql_query |
| RAGFlow 助手 | 发现可用知识库助手，并向内部知识库提问 | get_assistant_list、create_ask_delete |
| 模块 | 技术 | 作用 |
|---|---|---|
| 智能体框架 | DeepAgents |
创建主智能体和子智能体，承接长任务、多工具、多助手调度 |
| 图与检查点 | LangGraph |
提供底层运行时和 InMemorySaver 会话检查点 |
| 模型与工具抽象 | LangChain / langchain-core |
封装 OpenAI 兼容模型、工具声明和 Agent 调用结构 |
| 大模型接入 | OpenAI 兼容接口 | 通过 .env 中的 OPENAI_BASE_URL、OPENAI_API_KEY、LLM_QWEN_MAX 接入模型 |
| 网络搜索 | Tavily |
为网络搜索助手提供公开资料检索 |
| 结构化数据 | MySQL / mysql-connector-python |
为数据库助手提供药品、库存、销售等教学业务数据 |
| 私有知识库 | RAGFlow / ragflow-sdk |
为知识库助手提供内部文档问答能力 |
| 文件处理 | pypdf / python-docx / pandas / ReportLab |
读取上传附件，生成 Markdown，转换 PDF |
| 后端接口 | FastAPI / Uvicorn |
提供任务、取消、上传、文件列表、下载和 WebSocket 接口 |
| 实时通信 | WebSocket |
推送工具调用、助手调用、最终结果和错误事件 |
| 前端 | React / Vite / Ant Design / Tailwind CSS |
提供对话式研搜界面、事件流、附件上传和文件下载 |
| 依赖管理 | uv / pnpm |
管理 Python 后端和前端依赖 |
deepsearch-agents/
├── app/
│ ├── agent/
│ │ ├── subagents/ # 网络搜索、数据库查询、RAGFlow 三个子智能体
│ │ ├── llm.py # OpenAI 兼容模型初始化
│ │ ├── main_agent.py # 主智能体组装与 run_deep_agent 执行入口
│ │ └── prompts.py # 读取 app/prompt/prompts.yml
│ ├── api/
│ │ ├── context.py # ContextVar 保存 thread_id 和 session_dir
│ │ ├── monitor.py # 工具调用、助手调用、结果和异常事件推送
│ │ └── server.py # FastAPI 任务、上传、文件、下载、WebSocket 接口
│ ├── prompt/
│ │ └── prompts.yml # 主智能体和子智能体提示词配置
│ ├── ragflow/ # RAGFlow 配置和基础调用示例
│ ├── tools/ # Tavily、MySQL、RAGFlow、文件读取、Markdown、PDF 工具
│ ├── utils/ # 路径解析、Markdown/PDF 底层转换等普通 Python 工具
│ ├── output/ # 运行时生成：每个会话的 Markdown、PDF 等产物
│ └── updated/ # 运行时生成：用户上传文件的会话暂存目录
├── docker/
│ ├── docker-compose.yaml # 本地 MySQL 教学环境
│ └── mysql/mysql.sql # 药品、库存、销售记录模拟数据
├── docs/knowledge_base/ # RAGFlow 知识库示例 PDF
├── examples/ # DeepAgents 章节示例脚本
├── frontend/ # React + Vite 前端项目
├── tests/ # 测试目录
├── .env.example # 环境变量示例
├── pyproject.toml # Python 项目依赖声明
├── requirements.txt # 依赖清单
└── uv.lock # uv 锁定文件
- Python
3.12 uv- Docker 与 Docker Compose
- Node.js 与
pnpm - 可用的大模型 API Key
- Tavily API Key
- RAGFlow 服务与 API Key
git clone https://github.com/didilili/deepsearch-agents.git
cd deepsearch-agentsuv synccp .env.example .env按本机实际服务和密钥修改 .env：
# LLM 配置
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_API_KEY=你的大模型_API_KEY
LLM_QWEN_MAX=qwen-max
# Tavily 配置
TAVILY_API_KEY=你的_TAVILY_API_KEY
# RAGFlow 配置
RAGFLOW_API_URL=http://your-ragflow-host
RAGFLOW_API_KEY=ragflow-your-api-key
# MySQL 配置
MYSQL_USER=root
MYSQL_PASSWORD=root
MYSQL_DATABASE=deepsearch_db
MYSQL_HOST=localhost
MYSQL_PORT=3307
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_SQL_MODE=TRADITIONAL本仓库的 docker/mysql/mysql.sql 会在 MySQL 容器首次创建数据目录时自动导入药品、库存和销售记录模拟数据。
docker compose -f docker/docker-compose.yaml up -dRAGFlow 不在本仓库的 Docker Compose 中启动，需要接入你已有的 RAGFlow 服务，或按配套教程部署。仓库内的 docs/knowledge_base/ 提供了电商、金融等示例 PDF，可用于创建 RAGFlow 知识库和聊天助手。
如果暂时不使用私有知识库能力，也可以先跑网络搜索、数据库查询和上传文件读取链路；只有任务触发 RAGFlow 助手时才会依赖 RAGFLOW_API_URL 和 RAGFLOW_API_KEY。
uv run uvicorn app.api.server:app --host 0.0.0.0 --port 8000 --reload后端默认接口：
| 接口 | 说明 |
|---|---|
POST /api/task |
启动一次 DeepAgents 后台任务 |
POST /api/task/{thread_id}/cancel |
取消指定会话任务 |
POST /api/upload |
上传一个或多个文件到当前会话 |
GET /api/files |
列出当前会话输出目录中的生成文件 |
GET /api/download |
下载输出目录中的文件 |
WebSocket /ws/{thread_id} |
推送工具调用、助手调用、结果和异常事件 |
cd frontend
pnpm install
pnpm dev前端默认连接：
API: http://localhost:8000
WS: ws://localhost:8000
如需修改，可以在 frontend/.env.local 中配置：
VITE_API_BASE_URL=http://localhost:8000
VITE_WS_BASE_URL=ws://localhost:8000从数据库中查询心血管药品的库存情况，并生成 Markdown 报告。
搜索 2026 年 AI 在电商行业的应用趋势，并结合知识库资料生成一份 PDF。
请先读取我上传的行业报告，再结合公开资料整理一份研究摘要。
教程总入口：深度研搜完整教程
| 章节 | 标题 | 学习重点 | 对应分支 |
|---|---|---|---|
| 0 | 前言 | 项目定位、学习价值、技术栈和能力边界 | - |
| 1 | DeepAgents 基础与核心概念 | 智能体演进、框架定位、核心能力和多智能体设计边界 | - |
| 2 | DeepAgents 快速入门与流式解析 | create_deep_agent()、invoke、stream、chunk |
02-quickstart-streaming |
| 3 | 子智能体进阶与异步执行 | 字典式子智能体、助手调度、astream 和嵌套边界 |
03-deepagents-subagents-async |
| 4 | 接入 LangGraph 与 LangChain | CompiledSubAgent、LangGraph 子图、LangChain Agent 包装 |
04-deepagents-langgraph-langchain |
| 5 | 人机协作与中断恢复 | 人工审批、编辑工具参数、中断和恢复执行 | 05-deepagents-hitl-interrupt |
| 6 | 长期记忆与 Backend 存储 | FilesystemBackend、StoreBackend、CompositeBackend |
06-deepagents-backends-memory |
| 7 | 中间件机制与 Skills 配置 | 上下文摘要、模型调用限制、工具调用限制、自定义中间件和 Skills | 07-deepagents-middleware-governance |
| 8 | 项目总览与工程初始化 | 一主三从架构、9 个工具、前后端交互、工程目录 | 09-deepsearch-core-config |
| 9 | 基础模块与模型配置 | .env、ContextVar、monitor、路径工具、模型和提示词配置 |
09-deepsearch-core-config |
| 10 | 网络搜索子智能体与 Tavily 工具 | internet_search、Tavily 配置、网络搜索助手组装和进度上报 |
10-deepsearch-network-subagent |
| 11 | 数据库查询子智能体与 MySQL 工具 | 本地 MySQL、查表、预览数据、执行 SQL、数据库助手组装 | 11-deepsearch-database-subagent |
| 12 | RAGFlow 子智能体与知识库准备 | RAGFlow 部署、助手列表查询、临时会话问答、知识库助手组装 | 12-deepsearch-ragflow-subagent |
| 13 | 主智能体搭建与异步执行 | 主智能体组装、上传文件读取、Markdown/PDF 工具、会话目录隔离 | 13-deepsearch-main-agent |
| 14 | FastAPI 接口与项目闭环 | 任务启动/取消、上传、文件列表、下载、WebSocket 和前端联调 | 14-deepsearch-api-websocket |
可以用分支切换对照每一阶段的代码演进：
git checkout 10-deepsearch-network-subagent
git checkout mainmain 分支保留当前完整闭环版本。
「深度研搜」适合入门到进阶阶段学习多智能体工程主链路，但它不是一个完整企业级生产系统。当前版本重点覆盖 DeepAgents 多智能体调度、真实工具接入、文件交付、FastAPI 接口、WebSocket 实时推送和前后端联调。
它没有刻意展开以下生产治理能力：
- 用户登录、角色权限和多租户隔离；
- 文件上传安全扫描和内容审核；
- 任务队列、分布式执行和大规模并发治理；
- 全量事件持久化、历史会话恢复和审计追踪；
- 系统化评测集、自动化回归和 Agent 质量评估；
- 生产监控、告警、链路追踪和灰度发布；
- 复杂报告编辑、协同工作流和权限化文件管理。
这些能力适合在主链路跑通之后继续扩展。本仓库先承担一个清晰角色：把 DeepAgents 多智能体项目最关键、最必要、最值得学习的工程骨架讲清楚、跑起来，并为后续企业级扩展打基础。