type
Post
status
Published
date
Mar 28, 2026
slug
deepagents-003
summary
基于DeepAgents深度搜索项目（1）
tags
Agent
category
DeepAgents
icon
password
二、深度搜索项目介绍
本项目是 DeepAgents 框架的一个典型最佳实践，旨在构建一个**"深度搜索研究员"**。
2.1 项目目标
利用DeepAgent 来模拟人类高级研究员思维的多路组合智能体系统，以「主智能体统筹 + 多专家子智能体并行协作」为核心架构，突破传统 RAG 单次检索局限，通过搜索 - 阅读 - 反思 - 再搜索多轮迭代，深度挖掘海量信息背后的隐藏逻辑，实现广覆盖、高精准、强可靠的复杂信息处理与文档生成。
2.2 Agent Design
系统采用1 主 + N 专多路组合模式，主智能体统一调度，三类专家子智能体各司其职、并行工作：
主智能体（Main Agent）是整个智能团队的 "项目经理" (Leader)。它不直接执行具体的搜索或查询任务，而是专注于理解需求、拆解任务、调度资源、交付结果。
- Main Agent (主智能体):
- 职责: 项目经理。负责理解用户意图、拆解任务步骤、生成子任务、以及最终汇总报告。
- 能力: 拥有全局视野，管理整个会话的状态和记忆。
- Sub Agent (子智能体):
- 网络搜索助手：负责公开知识广域检索，支持由浅入深、多轮递进搜索，最多执行 5 次精准检索，覆盖 3 个以上信息维度。
- 数据库查询助手：对接企业业务数据库，支持表结构读取、数据预览、自定义 SQL 查询，精准提取商品 / 业务明细数据。
- RAGFlow 助手：对接企业私有知识库，先获取可用助手列表，再分层提问、深度检索，确保内部专有信息安全可用。
2.3 工具体系
我们为 Agent 装备了硬核的工具库：
主智能体工具
- generate_markdown —— 生成标准 Markdown 文档
- convert_md_to_pdf —— 将 Markdown 转为 PDF 文件
网络搜索助手
- internet_search（tavily） —— 互联网公开信息多轮、多角度检索
数据库查询助手
- list_sql_tables —— 列出数据库所有表结构
- get_table_data —— 读取表数据预览
- execute_sql_query —— 执行自定义 SQL 查询
RAGFlow 知识库助手
- get_assistant_list —— 获取知识库可用助手列表
- create_ask_delete —— 向知识库发起提问查询
2.4 技术栈
本项目采用了全异步的高性能架构：
- LangChain / LangGraph / DeepAgent:
- 介绍 : 项目的“神经中枢”。LangGraph 负责构建 有状态的循环工作流 (StateGraph) ，让 Agent 具备记忆、规划和自我修正能力，打破了传统 LLM 单次问答的限制。
- OpenAI SDK :
- 介绍 : 调用 GPT-4o / DeepSeek 等大模型的官方接口。通过 bind_tools 实现 Tool Calling（函数调用）。
- Pydantic :
- 介绍 : 数据校验基石。用于定义 Agent 的状态结构 ( AgentState ) 和工具的输入参数模型，确保数据流转的类型安全。
- FastAPI :
- 介绍 : 高性能异步 Web 框架。提供 RESTful API 接口，支持文件上传与静态资源托管。
- WebSocket :
- 介绍 : 全双工通信。用于将 Agent 的 思考过程 (Thinking Process) 和工具执行结果实时推送到前端，提升用户体验。
- Uvicorn :
- 介绍 : ASGI 服务器，FastAPI 的启动引擎。
- Tavily Search API ( tavily_tools.py ):
- 介绍 : 专为 AI 设计的搜索引擎。相比 Google，它返回的内容更结构化，不仅包含链接，还包含清洗后的网页正文，极大减少了 Agent 的 Token 消耗。
- RAGFlow ( ragflow_tools.py ):
- 介绍 : 企业级 RAG 引擎。用于连接本地知识库，支持 PDF、Word 等文档的深度解析与语义检索。
- PyMuPDF (fitz) ( pdf_tools.py ):
- 介绍 : 高性能 PDF 处理库。用于精准提取 PDF 中的文本和表格，辅助 Agent 阅读文献。
- PyMySQL / SQLAlchemy ( mysql_tools.py ):
- 介绍 : 数据库连接器。赋予 Agent 操作结构化数据（SQL）的能力，使其能查询业务报表。
- Markdown / File IO ( markdown_tools.py , upload_file_read_tool.py ):
- 介绍 : 文件读写能力。支持 Markdown 格式的报告生成，以及读取用户上传的任意文本文件。
- Asyncio :
- 介绍 : Python 异步编程标准库。通过 async/await 实现非阻塞 IO，让 Agent 在等待网络请求（如搜索、LLM 生成）时，服务器仍能响应其他请求。
- ContextVars :
- 介绍 : 线程上下文变量。在异步并发环境中，像“隐形传态”一样传递 thread_id 和 user_id ，确保日志和工具能正确归属到对应用户，防止数据串线。
- Pathlib :
- 介绍 : 面向对象的文件路径处理。解决了 Windows/Linux 路径分隔符差异的痛点。
- Shutil :
- 介绍 : 高级文件操作。用于高效地复制、移动和归档用户上传的文件。
三、项目搭建指南
3.1 创建项目
3.2 导入依赖
安装依赖：
- 将资料中requirements.txt文件粘贴到项目根路径下
- 使用命令进行批量安装
3.3 项目包结构
请按照以下结构创建目录和空文件
3.4 基础导入
在开始写智能体之前，先导入一些基础类和前端工程：日志、监控、会话隔离以及UI前端先导入。
3.4.1 导入前端项目
环境准备
- 安装 Node.js，推荐版本 20.19.0（可通过
nvm或 Node 官网安装包配置）
- 验证安装：执行
node -v，确认输出版本为 v20.19.0 及以上
项目文件部署
将
资料/ui 目录完整复制到当前项目根目录下启动服务
打开终端，执行以下命令：
访问测试
服务启动成功后，在浏览器访问：
补充说明
- 若启动报错，优先检查：Node 版本是否匹配、ui 目录下
package.json依赖是否完整（可执行npm install安装依赖）
- 端口 5173 被占用时，可修改 ui 目录下的配置文件（如
vite.config.js）调整端口
3.4.2 api通信相关
以下是项目中需导入的四个核心类:
- server.py —服务入口
接收客户请求（API 接口）、分配唯一标识（Thread ID），将任务派给后台异步处理，同时通过 WebSocket 实时反馈进度。
- context.py —数据隔离
为任务打上专属标识，支持任意环节快速获取任务身份，核心实现多任务(请求)数据隔离，避免信息串混。
- monitor.py —实时反馈
收集后台任务执行状态，结合任务标识精准推送消息，解决后台与前台的跨线程通信问题。
- logger.py —— 全程记录
记录任务全流程操作（含思考、工具调用、结果），按任务标识分类归档日志，方便故障排查与复盘。
3.4.2.1 会话数据（api/context.py)
说明：使用
ContextVars 确保不同用户的请求（协程）在服务器内部是完全隔离的，不会混淆文件路径。3.4.2.2 实时监控 (api/monitor.py)
说明：这是一个单例（Singleton）类，负责将智能体的内部思考过程实时推送到前端 WebSocket。
3.4.3 配置文件
创建文件：根路径/.env
3.4.4 导入工具
文件：
utils/word_converter.py负责将md转成pdf的工具类
文件：
utils/path_utils.py处理路径工具，确保路径处于当前会话下！并且去掉大模型生成的虚拟路径！
四、功能开发&测试
4.1 大模型准备
4.1.1 检查配置文件
文件：
.env4.1.2 创建大模型对象
文件：
agent/llm.py4.2 提示词配置&加载
4.2.1 创建提示词配置文件（yml）
文件:
prompt/prompts.yml 【简化，独立智能体进行优化提示词】| 被称为块折叠标量（Literal Block Scalar）它是 YAML 里专门用来处理多行文本的语法（用
| 开头），核心作用是：让你能把需要换行的内容（比如 prompt、描述、长文本）清晰地分行写，YAML 解析时会完整保留换行格式，不会把所有内容挤成一行，特别适合写大段的文本配置4.2.2 读取提示词文件
文件：
agent/prompts.py📎 参考文章
- 一些引用
- 引用文章
欢迎您在底部评论区留言，一起交流~
Loading...