14-FastAPI接口与项目闭环
14 - 深度研搜：FastAPI 接口与项目闭环 本章课程目标： 完成 DeepAgents 多智能体系统的 FastAPI 接口层。 看懂 /api/task、/api/task/{thread_id}/cancel、/api/upload、/api/files、/api/download、/ws/{thread_id} 这六个入口分别接住前端哪一步动作。 理解为什么 /api/task 只负责启动后台任务，而不直接等待主智能体返回最终结果。 掌握 asyncio.create_task()、active_tasks 和任务取消之间的关系。 理解 WebSocket 为什么要绑定 FastAPI 的事件循环，以及 run_coroutine_threadsafe() 解决什么问题。 按课堂路径完成闭环验证：前端连接、上传文件、发起任务、查看进度、生成 Markdown/PDF、下载文件。 学习建议： 这一章不是又开一条新知识线，而是把前面几章串起来。读的时候可以把自己放在浏览器旁边：先看页面发了什么请求，再看 FastAPI 把任务交给谁，最后看 monitor...
13-主智能体搭建与异步执行
13 - 深度研搜：主智能体搭建与异步执行 本章课程目标： 理解主智能体和三个子智能体的分工关系。 明确为什么主智能体需要文件类工具：读取上传文件、生成 Markdown、转换 PDF。 完成 main_agent.py 的核心组装：模型、提示词、工具、子智能体、检查点。 读懂主智能体系统提示词中的任务边界和执行顺序要求。 理解为什么主智能体执行要选择 astream() 异步流式方式。 拆解 run_deep_agent()：会话目录、上传文件、ContextVar、流式执行、事件推送和上下文清理。 看清前端、FastAPI、主智能体、WebSocket、monitor 之间的协作关系，为接口层开发做准备。 学习建议： 这一章分两段看。前半先看主智能体的“创建态”：它是调度中心，负责理解任务、分派任务、汇总结果和生成文件；真正查网络、查数据库、查知识库的是子智能体和工具。后半再看主智能体的“运行态”：前端请求如何触发它，它如何用 astream() 流式执行，执行过程又如何通过 monitor 和 WebSocket 回到前端。把这两段连起来，下一章看 FastAPI 接口...
12-RAGFlow子智能体与知识库准备
12 - 深度研搜：RAGFlow 子智能体与知识库准备 本章课程目标： 理清 RAGFlow 的四层结构：服务、知识库、聊天助手、会话。 掌握课程环境中 RAGFlow 的部署思路和页面准备流程。 完成模型供应商配置、知识库创建、文件上传与解析。 创建 RAGFlow 聊天助手，并通过页面测试知识库问答效果。 理解为什么 RAGFlow 子智能体需要两个工具：先查助手列表，再向指定助手提问。 学习建议： RAGFlow 这章先别急着封装 API。它自己有页面、模型配置、知识库、助手和会话，第一遍先把这些对象之间的关系捋清楚。等你能说清“文件进知识库、助手绑定知识库、会话用助手回答”之后，再看工具封装和子智能体配置，会顺很多。 对应代码分支： 12-deepsearch-ragflow-subagent 1、RAGFlow 解决哪类问题前两章已经完成了两个子智能体，本章补上第三个子智能体： 子智能体 底层能力 特点 网络搜索助手 Tavily API 直接调用搜索 API 数据库查询助手 MySQL Connector 直接连接数据库执行查询 RAGFl...
11-数据库查询子智能体与MySQL工具
11 - 深度研搜：数据库查询子智能体与 MySQL 工具 本章课程目标： 理解数据库查询助手在「深度研搜」项目中的职责边界。 明确为什么数据库助手不能直接让模型生成 SQL，而要按三步查询。 准备 MySQL 连接配置，并理解 get_db_config 的作用。 实现 list_sql_tables、get_table_data、execute_sql_query 三个数据库工具。 组装 database_query_agent，为后续主智能体调度做准备。 学习建议： 数据库助手不要一上来就看 SQL 怎么写。先看它如何知道有哪些表，再看表结构和样例数据如何暴露给模型，最后才是执行查询。这个顺序很重要：这类系统最怕的不是 SQL 写得慢，而是模型一开始就把表名、字段名、字段含义猜错。 对应代码分支： 11-deepsearch-database-subagent 上一章已经完成了网络搜索助手。网络搜索助手负责公开互联网信息，它面对的是网页、新闻、外部资料。 本章要写第二个子智能体：数据库查询助手。 它面对的是企业内部结构化数据，比如： 药品基础信息； 药品库存； 药品...
10-网络搜索子智能体与Tavily工具
10 - 深度研搜：网络搜索子智能体与 Tavily 工具 本章课程目标： 理解 DeepAgents 子智能体的三个核心组成：描述、提示词、工具。 完成 internet_search 工具封装，并接入 Tavily 搜索能力。 理解两种向前端推送进度的方式：流式解析和工具内部埋点。 组装 network_search_agent，让它成为主智能体后续可以调度的专家助手。 学习建议： 网络搜索助手是最适合入门的子智能体，因为它不涉及数据库结构，也不涉及 RAGFlow 的平台层级。读本章时重点看一个子智能体字典里到底放了什么：名称、职责描述、提示词、工具。能把 Tavily 换成别的搜索工具并说清要改哪里，就说明这章吃透了。 对应代码分支： 10-deepsearch-network-subagent 从本章开始，我们正式进入子智能体实现阶段。整个「深度研搜」项目会陆续实现 3 个专家助手： 子智能体 负责内容 本章是否实现 网络搜索助手 查询互联网公开资料和最新信息 是 数据库查询助手 查询企业内部结构化业务数据 否，下一章 RAGFlow 助手 查...
9-基础模块与模型配置
9 - 深度研搜：基础模块与模型配置 本章课程目标： 准备 .env，把模型、搜索、数据库、RAGFlow 等配置从代码里拆出来。 理解 ContextVar 如何保存当前任务的 thread_id 和 session_dir，避免多用户请求串台。 理解 monitor.py 如何把工具调用、助手调用和任务结果推送给前端。 熟悉 path_utils.py、word_converter.py 这两个普通工具模块的职责，其中 word_converter.py 使用 ReportLab 生成 PDF。 完成 agent/llm.py、prompt/prompts.yml、agent/prompts.py 这组模型与提示词配置。 学习建议： 这一章看的是项目底座，不是零散工具函数。可以顺着“配置入口 -> 请求上下文 -> 实时进度 -> 文件工具 -> 模型与提示词”追一遍，边读边问：这个模块被谁创建、被谁调用、出了问题会影响哪条链路。把这些基础模块的位置看清，后面主智能体代码会轻很多。 对应代码分支： 09-deepsearch-core-config...
8-项目总览与工程初始化
8 - 深度研搜：项目总览与工程初始化 本章课程目标： 理解「深度研搜」项目要解决什么问题，以及它和普通问答、普通 RAG 的区别。 建立对项目整体架构的第一印象：1 个主智能体、3 个专家子智能体、9 个核心工具。 理解 thread_id、session_dir 和 WebSocket 在前后端联动中的位置。 学习建议： 这章是深度研搜项目的工程地图。建议边读边画一条链路：前端发起任务，主智能体拆分和调度，网络搜索、数据库、RAGFlow 等助手各做一部分，进度再推回前端。工程初始化部分不用死记目录，先知道每类文件支撑链路上的哪一段。 对应代码分支： 09-deepsearch-core-config 1、本章导读1.1 先看最终要做成什么样「深度研搜」项目会提供一个类似研究助手的页面。用户可以输入研究任务，也可以上传文件，后端智能体会根据任务需要去查网络、查数据库、查私有知识库，最后整理回答或生成文件。 先看两个入口：一个是文本输入，一个是附件上传。这也提醒我们，后端不能只处理一句 prompt，还要能处理上传文件、会话目录、执行进度和最终产物。 1.2 本章先做什...
7-中间件机制与Skills配置
7 - 深度研搜：中间件机制与Skills配置 本章课程目标： 理解中间件在 Agent 执行链路中的位置：它不负责具体业务，而是负责链路治理。 掌握上下文摘要、模型调用限制、工具调用限制三类常用中间件。 区分 thread_limit、run_limit、exit_behavior 的作用。 知道中间件如何与 interrupt_on、子智能体、WebSocket 进度推送配合。 学习建议： 先把中间件理解成 Agent 执行链路上的检查口：模型调用前、工具调用前、上下文送入前，都可以在这里观察或改写。读代码时重点看它怎样做日志、参数调整、次数限制和风险拦截。Skills 部分先看它如何作为可复用说明被加载，不必和工具、子智能体混在一起。 对应代码分支： 07-deepagents-middleware-governance 参考资料：LangChain 内置中间件：https://docs.langchain.com/oss/python/langchain/middleware/built-in 1、中间件先解决什么问题1.1 用一句话理解中间件中间件的英文是 Mid...
6-长期记忆与Backend存储
6 - 深度研搜：长期记忆与 Backend 存储 本章课程目标： 理解 DeepAgents 中 Backend 的定位：它是 Agent 文件系统和长期存储的连接层。 区分短期记忆和长期记忆，知道二者差异不在“保存多久”，而在“保存什么”。 区分 checkpointer、StateBackend、FilesystemBackend、StoreBackend、CompositeBackend 的作用。 学习建议： Backend 不只是“保存聊天记录”，更像给 Agent 准备的文件柜。读这一章时比较几种后端背后的取舍：状态里存、磁盘里存、KV Store 里存、按路径分流存。重点看 Agent 仍然用文件读写的方式工作，而 Backend 决定这些文件最终落到哪里、能不能跨会话复用。 对应代码分支： 06-deepagents-backends-memory 参考资料：DeepAgents 后端存储：https://docs.langchain.com/oss/python/deepagents/backends 1、记忆体系与 Backend 总览1.1 从中断恢复...
5-人机协作与中断恢复
5 - 深度研搜：人机协作与中断恢复 本章课程目标： 理解为什么企业级智能体需要人机协作机制。 掌握 interrupt_on 的作用，知道如何配置需要审批的工具。 理解 checkpointer、thread_id 和中断恢复之间的关系。 掌握 Command(resume=...) 的基本用法。 能区分审批放行、拒绝执行和编辑参数三类人工动作。 学习建议： 人机协作不是为了多聊几句，而是把高风险动作挡在执行前。学习时抓住一条线：第一次运行只规划并触发中断，不真正执行危险工具；人工审批后，再用同一个 thread_id 恢复执行。读代码时特别留意“中断前保存了什么、恢复时靠什么接上”。 对应代码分支： 05-deepagents-hitl-interrupt 参考资料：DeepAgents 人机协作：https://docs.langchain.com/oss/python/deepagents/human-in-the-loop 前面几章里，Agent 调用工具时都是自动执行的。模型判断要调用工具，Agent 就直接执行。 这种方式适合低风险工具，比如：查询天气；搜索公...