深度研搜——对话式多智能体研究系统
欢迎来到「深度研搜」项目，正式进入「AI 智能体实战速成指南」里更偏多智能体、长任务和工程闭环的一套实战项目。
如果你已经学过大模型接口调用、Prompt、RAG、LangChain 或 LangGraph，下一步通常会遇到一个更实际的问题：复杂任务到底怎么组织成一个能跑、能看、能交付的项目？
「深度研搜」就是围绕这个问题设计的。它不是再写一个聊天框，也不是只接一个搜索 API，而是用 DeepAgents 搭一个对话式多智能体研究台：用户输入研究任务或上传附件，主智能体判断任务需要哪些信息，再调度网络搜索、数据库查询、RAGFlow 知识库等能力，最后整理回答，或生成 Markdown / PDF 文件。
「深度研搜」不是一个只让大模型回答问题的 Demo，而是一套围绕“主智能体规划调度、子智能体分工执行、多来源资料检索、文件生成交付、前后端实时联动”展开的 DeepAgents 多智能体实战项目。
它可能还不是一个完整的企业级生产系统，但非常适合作为入门到进阶阶段的项目实战课程。你可以在这里系统学习一个多智能体应用如何从概念、示例、子智能体、长期记忆、中间件，一步步走到真实的 FastAPI 接口和前端页面。
📖 项目介绍
在真实研究场景里，用户的问题经常不是一句普通问答可以解决的。
比如：
代码块
Plain Text
结合公开资料、数据库信息和我上传的文档，整理一份机器人行业研究报告，并生成 PDF。
这个任务背后可能包含多类动作：
•
判断需要公开资料、内部数据、私有知识库还是本次上传文件；
•
去互联网搜索最新新闻、政策、产品或行业资料；
•
到 MySQL 查询企业结构化业务数据；
•
到 RAGFlow 查询内部非结构化文档；
•
读取用户上传的 PDF、Word、Excel、Markdown 或文本文件；
•
汇总多来源信息，判断资料是否足够；
•
生成 Markdown 报告，并在需要时转换成 PDF；
•
把执行过程、最终结果和生成文件实时展示给前端。
所以「深度研搜」更像一个会分工、会查资料、会生成交付物的研究助手。用户只需要提出任务，系统会在后端组织一条可观察的多智能体执行链路。
代码块
Shell
用户任务
-> 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 模式：主智能体作为调度中心，三个专家助手负责信息获取，文件工具由主智能体直接掌握。
项目围绕两条主线展开：
智能体与工具
表格加载中...
#qMHKlAzkQlKf text{white-space:pre}.fb0{stroke:var(--N900-FG, 0.15)}.fx0{stroke-miterlimit:10}.fa1{fill:#bbbfc4}.fx1{font:normal 400 12px MonospacedNumber,LarkHackSafariFont,LarkEmojiFont,LarkChineseQuote,-apple-system,BlinkMacSystemFont,Helvetica Neue,Tahoma,PingFang SC,Microsoft Yahei,Arial,Hiragino Sans GB,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji}.fx2{text-anchor:middle}.fx3{dominant-baseline:central}.fx4{stroke:none}.fc0{fill:var(--text-caption)}.fa2{fill:var(--text-link-disabled)}.fx5{font:400 normal 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"}.fx6{text-anchor:start}.fx7{dominant-baseline:alphabetic}.fc1{fill:rgb(0, 0, 0)}.fx8{font:400 normal 13px LarkHackSafariFont, LarkEmojiFont, "ui-monospace", -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui}.fb1{fill:var(--N900-FG, 0.15)}.fb2{fill:rgb(209, 217, 224)}.fa3{fill:var(--bg-body)}ABC12345归属主智能体网络搜索助手数据库查询助手RAGFlow 助手能力任务规划、助手调度、结果汇总、文件交付查询互联网公开信息、新闻、政策和网页资料发现表名、预览表结构和样例数据、执行 SQL发现可用知识库助手，并向内部知识库提问工具、、、、、read_file_contentgenerate_markdownconvert_md_to_pdfinternet_searchlist_sql_tablesget_table_dataexecute_sql_queryget_assistant_listcreate_ask_delete
🛠️ 项目技术栈
📁 项目结构
代码块
Bash
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 # 工具调用、助手调用、结果和异常事件推送
🚀 快速开始
准备环境
•
Python 3.12
•
uv
•
Docker 与 Docker Compose
•
Node.js 与 pnpm
•
可用的大模型 API Key
•
Tavily API Key
•
RAGFlow 服务与 API Key
克隆项目
代码块
Plain Text
git clone https://github.com/didilili/deepsearch-agents.git
安装后端依赖
代码块
Plain Text
uv sync
配置环境变量
代码块
Plain Text
cp .env.example .env
按本机实际服务和密钥修改 .env：
代码块
Plain Text
启动 MySQL 教学库
本仓库的 docker/mysql/mysql.sql 会在 MySQL 容器首次创建数据目录时自动导入药品、库存和销售记录模拟数据。
代码块
Plain Text
docker compose -f docker/docker-compose.yaml up -d
准备 RAGFlow 知识库
RAGFlow 不在本仓库的 Docker Compose 中启动，需要接入你已有的 RAGFlow 服务，或按配套教程部署。仓库内的 docs/knowledge_base/ 提供了电商、金融等示例 PDF，可用于创建 RAGFlow 知识库和聊天助手。
如果暂时不使用私有知识库能力，也可以先跑网络搜索、数据库查询和上传文件读取链路；只有任务触发 RAGFlow 助手时才会依赖 RAGFLOW_API_URL 和 RAGFLOW_API_KEY。
启动后端
代码块
Plain Text
uv run uvicorn app.api.server:app --host 0.0.0.0 --port 8000 --reload
后端默认接口：
启动前端
代码块
Plain Text
cd frontend
pnpm install
pnpm dev
前端默认连接：
代码块
Plain Text
WS: ws://localhost:8000
如需修改，可以在 frontend/.env.local 中配置：
代码块
Plain Text
VITE_API_BASE_URL=http://localhost:8000
VITE_WS_BASE_URL=ws://localhost:8000
试几个任务
代码块
Plain Text
从数据库中查询心血管药品的库存情况，并生成 Markdown 报告。
搜索 2026 年 AI 在电商行业的应用趋势，并结合知识库资料生成一份 PDF。
请先读取我上传的行业报告，再结合公开资料整理一份研究摘要。
🚧 能力边界
「深度研搜」适合入门到进阶阶段学习多智能体工程主链路，但它不是一个完整企业级生产系统。当前版本重点覆盖 DeepAgents 多智能体调度、真实工具接入、文件交付、FastAPI 接口、WebSocket 实时推送和前后端联调。
它没有刻意展开以下生产治理能力：
•
用户登录、角色权限和多租户隔离；
•
文件上传安全扫描和内容审核；
•
任务队列、分布式执行和大规模并发治理；
•
全量事件持久化、历史会话恢复和审计追踪；
•
系统化评测集、自动化回归和 Agent 质量评估；
•
生产监控、告警、链路追踪和灰度发布；
•
复杂报告编辑、协同工作流和权限化文件管理。
这些能力适合在主链路跑通之后继续扩展。本仓库先承担一个清晰角色：把 DeepAgents 多智能体项目最关键、最必要、最值得学习的工程骨架讲清楚、跑起来，并为后续企业级扩展打基础。