章节三十六：DeepAgents深度搜索项目
一、深度搜索项目概述
1.1 项目目标
本项目是DeepAgents框架的典型实践，目标是构建一个"深度搜索研究员"。
深度搜索：模拟人类高级研究员的思维，突破传统RAG单次检索的局限，通过"搜索-阅读-反思-再搜索"多轮迭代，深度挖掘信息背后的隐藏逻辑，实现广覆盖、高精准、强可靠的复杂信息处理与文档生成。
1.2 Agent设计
系统采用"1主 + N专"的多路组合模式：
主智能体（Main Agent）：项目经理（Leader），不直接执行具体任务，专注于理解需求、拆解任务、调度资源、汇总报告。拥有全局视野，管理整个会话的状态和记忆。
子智能体（Sub Agent）：
第一，网络搜索助手：负责公开知识的广域检索，支持由浅入深的多轮递进搜索，最多执行5次精准检索，覆盖3个以上信息维度。
第二，数据库查询助手：对接企业业务数据库，支持读取表结构、预览数据、执行自定义SQL，精准提取业务数据。
第三，RAGFlow知识库助手：对接企业私有知识库，先获取可用助手列表，再分层提问、深度检索，确保内部专有信息安全可用。
1.3 工具体系
主智能体工具：生成Markdown文档、将Markdown转为PDF。
网络搜索助手工具：Tavily互联网搜索（返回结构化结果，包含标题、链接、摘要、正文）。
数据库查询助手工具：列出数据库所有表、预览表数据、执行自定义SQL。
RAGFlow知识库助手工具：获取知识库可用助手列表、向知识库发起提问。
1.4 技术栈
| 技术 | 作用 |
|---|---|
| LangChain / LangGraph / DeepAgent | 项目的"神经中枢"，LangGraph构建有状态循环工作流 |
| OpenAI SDK | 调用GPT-4o / DeepSeek等大模型，通过bind_tools实现Tool Calling |
| Pydantic | 数据校验基石，定义Agent状态结构和工具输入参数 |
| FastAPI | 高性能异步Web框架，提供RESTful API接口 |
| WebSocket | 全双工通信，将Agent的思考过程实时推送到前端 |
| Tavily Search API | 专为AI设计的搜索引擎，返回结构化清洗后的网页正文 |
| RAGFlow | 企业级RAG引擎，连接本地知识库，支持文档深度解析与语义检索 |
| PyMuPDF | 高性能PDF处理库，提取PDF中的文本和表格 |
| PyMySQL / SQLAlchemy | 数据库连接器，赋予Agent操作结构化数据的能力 |
| Asyncio | Python异步编程，实现非阻塞IO |
| ContextVars | 线程上下文变量，在异步环境中传递thread_id和user_id，防止数据串线 |
二、项目实现
2.1 项目结构
项目主要包含以下模块：
- agent/：智能体相关。包括子智能体（数据库、网络搜索、RAGFlow）、大模型初始化、提示词配置加载、主智能体组装与执行。
- api/：接口层。包括ContextVars会话隔离、WebSocket实时监控、FastAPI服务入口。
- prompt/：提示词配置（prompts.yaml）。
- tools/：工具集。包括搜索工具、数据库工具、RAG工具、Markdown生成工具、PDF转换工具、文件读取工具。
- utils/：工具模块。包括路径操作、日志配置、格式转换。
2.2 API通信核心类
server.py（服务入口）：接收客户端请求，分配唯一标识（Thread ID），将任务派给后台异步处理，通过WebSocket实时反馈进度。
context.py（数据隔离）：使用ContextVars为任务打上专属标识，支持任意环节快速获取任务身份，实现多任务数据隔离，避免信息串混。
monitor.py（实时反馈）：单例类，收集后台任务执行状态，结合任务标识精准推送消息到前端，解决后台与前台的跨线程通信问题。
2.3 工具实现说明
联网搜索工具：基于Tavily实现，参数包括查询词、结果数量、主题类型、是否包含原始内容，返回结构化搜索结果。
数据库工具：MySQL操作工具集，包括列出所有表名、预览指定表的前N行数据、执行自定义SQL查询。
RAGFlow工具：知识库交互工具集，包括获取可用助手列表、向指定助手发起提问并获取回答。
文件生成工具：Markdown文档生成和PDF转换工具。
文件读取工具：支持多种格式（txt、md、docx、xlsx、pdf、csv等），根据文件扩展名选择对应的解析方式。
2.4 主智能体组装
主智能体的组装逻辑包括：加载提示词配置、初始化大模型、定义主智能体的工具列表、创建并配置各子智能体（网络搜索、数据库、RAGFlow）、通过create_deep_agent创建主智能体实例。
2.5 运行步骤
第一步：确保所有服务（MySQL、RAGFlow等）已启动。
第二步：配置.env文件中的API Key和数据库连接信息。
第三步：启动后端服务。
第四步：启动前端服务（安装Node.js不低于20.19.0版本，复制UI目录，执行npm run dev，访问http://localhost:5173）。
第五步：浏览器访问前端地址，输入任务指令测试。
第六步：观察WebSocket实时推送的执行过程和最终结果。
三、API接口文档
3.1 基础信息
- 基础地址：
http://<host>:8000 - WebSocket地址：
ws://<host>:8000
3.2 智能体任务启动接口
启动一个新的智能体任务，任务在后台异步执行，实时进度通过WebSocket推送到前端。
- 地址：
/api/task - 方法：POST
- 请求参数：query（用户输入的任务指令，必填）、thread_id（任务唯一标识，可选，不提供则自动生成UUID）
- 响应参数：status（固定为"started"）、thread_id（任务唯一标识）
3.3 文件上传接口
上传文件到指定会话的上下文目录，供Agent读取和分析。
- 地址：
/api/upload - 方法：POST
- 请求格式：multipart/form-data
- 请求参数：files（一个或多个文件对象，必填）、thread_id（关联的任务ID，必填）
- 响应参数：status（固定为"uploaded"）、files（成功保存的文件名列表）
3.4 文件下载接口
根据绝对路径下载文件，有安全检查（只能下载output目录下的文件）。
- 地址：
/api/download - 方法：GET
- 请求参数：path（文件的绝对路径）
3.5 文件列表查询接口
列出指定目录下的所有生成文件，支持递归遍历。
- 地址：
/api/files - 方法：GET
- 请求参数：path（目标目录的绝对路径，必须在output目录下）
- 响应参数：files数组，包含文件名、类型、路径、大小、修改时间等信息
3.6 WebSocket实时通讯
用于前端实时接收智能体执行过程中的状态反馈和工具调用详情。
- 地址：
/ws/{thread_id}
服务端推送的消息都是JSON格式，包含type（消息类型）、event（事件类型）、message（提示文字）、data（附加数据）、timestamp（时间）。
前端根据event字段做不同展示：
| 事件类型 | 触发时机 | 前端建议动作 |
|---|---|---|
| session_created | 工作目录创建成功 | 记录路径 |
| tool_start | Agent开始调用工具 | 展示执行详情 |
| assistant_call | 委派给子Agent | 展示咨询信息 |
| task_result | 任务完成 | 追加到对话框 |
| error | 发生异常 | 提示错误信息 |
心跳保活：客户端发送任意文本，服务端回显pong。
