【Agent智能体】36DeepAgents深度搜索项目

章节三十六：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 技术栈

二、项目实现

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字段做不同展示：

心跳保活：客户端发送任意文本，服务端回显pong。