章节三十六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 CallingPydantic数据校验基石定义Agent状态结构和工具输入参数FastAPI高性能异步Web框架提供RESTful API接口WebSocket全双工通信将Agent的思考过程实时推送到前端Tavily Search API专为AI设计的搜索引擎返回结构化清洗后的网页正文RAGFlow企业级RAG引擎连接本地知识库支持文档深度解析与语义检索PyMuPDF高性能PDF处理库提取PDF中的文本和表格PyMySQL / SQLAlchemy数据库连接器赋予Agent操作结构化数据的能力AsyncioPython异步编程实现非阻塞IOContextVars线程上下文变量在异步环境中传递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:8000WebSocket地址ws://host:80003.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_startAgent开始调用工具展示执行详情assistant_call委派给子Agent展示咨询信息task_result任务完成追加到对话框error发生异常提示错误信息心跳保活客户端发送任意文本服务端回显pong。