终极实战:deep-agents-from-scratch第4课——组装支持联网搜索的完整Deep Research智能体

原创2026-10-25 09:50:021,330 阅读

终极实战:deep-agents-from-scratch第4课——组装支持联网搜索的完整Deep Research智能体

deep-agents-from-scratch 是一个带你从零开始、用 LangGraph 构建 Deep Research 智能体的开源教程项目。本课(第4课)将把前三课积累的核心能力——TODO 任务规划、虚拟文件系统、子智能体上下文隔离——全部组装到一起,并接入真实联网搜索,打造一个能自主完成深度调研的完整 Deep Research 智能体。🔍

第4课快速上手:安装与一键环境配置

在动手组装之前,先准备好运行环境(要求 Python 3.11+):

git clone https://gitcode.com/gh_mirrors/de/deep-agents-from-scratch
cd deep-agents-from-scratch
uv sync

联网搜索是"Deep Research"的灵魂,所以本课需要配置 API Key。参考 example.env,在项目根目录创建 .env 文件:

# 联网搜索必备
TAVILY_API_KEY=your_tavily_api_key_here
# 模型调用必备
ANTHROPIC_API_KEY=your_anthropic_api_key_here

💡 小贴士:配置完成后,运行 uv run jupyter notebook 即可打开本课的 4_full_agent.ipynb,跟着 Notebook 一步步执行即可看到完整效果。

整体架构:三大上下文工程能力一图看懂

第4课的核心思想只有一句话:用上下文工程(Context Engineering)让智能体跑得久、记得住、分得开。整个 Deep Research 智能体由 LLM + 三组工具构成:

Deep Research智能体整体架构图:LLM配合Plan任务规划、Offload Context上下文卸载、Sub-Agent子智能体三类工具协同工作

能力 对应工具 解决的问题
📋 Plan(计划) write_todos / read_todos 多步任务不跑偏,随时掌握进度
📁 Offload Context(卸载) ls / read_file / write_file 海量搜索结果不撑爆上下文窗口
🤖 Sub-Agent(子智能体) task 复杂调研并行分工,上下文互不污染

这三组工具全部定义在 src/deep_agents_from_scratch/ 目录下,是本课程前3课的"成果仓库",第4课负责把它们组合成完整系统。

联网搜索工具:搜索即写文件的上下文卸载

本课最精华的部分,是一个经过精心设计的搜索工具 research_tools.py。它并不是"搜到什么就把什么塞给智能体",而是一条完整的上下文卸载流水线:

上下文卸载模式:搜索结果先写入虚拟文件系统,智能体随时按需检索读取

  1. 执行搜索:run_tavily_search() 调用 Tavily API 发起联网搜索,支持 general / news / finance 三种主题过滤;
  2. 抓取与转换:process_search_results() 用 httpx 抓取网页全文,再通过 markdownify 把 HTML 转成 Markdown;
  3. AI 摘要:summarize_webpage_content() 使用轻量模型(GPT-4o-mini)生成 150 词以内的极简摘要,并自动起一个有语义的文件名(如 mcp_protocol_overview.md);
  4. 落盘 + 最小返回:tavily_search 工具把完整内容写入虚拟文件,而返回给智能体的只有一句"找到了什么、存在哪个文件"的简短提示,并提示"需要详情时请用 read_file()"。

这一设计正是 Manus 等头部 Deep Research 产品普遍采用的模式——智能体的"工作台"保持清爽,细节全部归档进文件。此外还配有一个 think_tool(策略反思工具),强制智能体在每次搜索后停下来分析:找到了什么?还缺什么?该继续搜还是该给出答案?

子智能体委派:上下文隔离与并行调研

对于复杂调研任务,单线程的上下文迟早会"打架"。本课用子智能体(Sub-agent)实现上下文隔离:主智能体调用 task() 工具,为每个研究方向派生一个全新的、只含任务描述的研究员。

子智能体模式:主智能体将上下文分发给多个隔离的研究子智能体并行调研

智能体上下文拆分原理:单个智能体的冗长上下文被拆解为多个子智能体的干净上下文

  • 隔离:每个 research-agent 从干净上下文启动,看不到父智能体的历史对话,只带任务描述出发;
  • 并行:在单轮回复中发出多个 task 调用即可并行调研(本课限制最多 3 个并发研究员);
  • 回收:子智能体写入的文件会合并回主智能体的状态,其最终结论则以 ToolMessage 形式返回——例如"对比三家公司的 AI 安全策略"会被拆成 3 个子智能体,分别产出 findings_*.md 文件。

子智能体的核心逻辑在 task_tool.py 中,研究人员的系统提示词则定义在 prompts.py 的 RESEARCHER_INSTRUCTIONS,里面用"硬性预算"约束了搜索次数(简单问题 1-2 次、复杂问题最多 5 次),防止无限搜索。

组装完整智能体:状态、工具与提示词三合一

万事俱备,开始组装!Deep Research 智能体的骨架由三部分组成:

① 扩展状态 state.py:DeepAgentState 在 LangGraph 标准 AgentState 基础上增加了 todos(任务清单)和 files(虚拟文件系统)两个字段,并通过 reducer 函数支持增量合并——这是文件能"跨轮次持久保存"的关键。

② 工具装配:主智能体拿到文件工具(file_tools.py)、TODO 工具(todo_tools.py)、think_tool 和 task 委派工具;子智能体只保留 tavily_search + think_tool 两件武器,专注检索。

③ 系统提示词:TODO 管理规则、文件系统使用规范、子智能体委派策略三大模块拼接成 INSTRUCTIONS,最后用 create_agent 一步生成智能体:

from langchain.agents import create_agent

agent = create_agent(
    model, all_tools,
    system_prompt=INSTRUCTIONS,
    state_schema=DeepAgentState
)

智能体运行流程:LLM在推理-工具调用-观察的ReAct循环中持续执行直至任务完成

实际运行:让智能体联网调研 MCP 协议

组装完成后,只需一句自然语言指令就能触发完整的调研流程:

result = agent.invoke({
    "messages": [{"role": "user",
                 "content": "Give me an overview of Model Context Protocol (MCP)."}]
})

执行时你可以观察到:主智能体先用 write_todos 立下调研计划 → 调用 task 派出研究员子智能体 → 子智能体执行 tavily_search 联网搜索,全文自动归档进虚拟文件 → 反思后返回结论 → 主智能体读取文件、更新 TODO,最终输出一份结构化的调研报告。整个过程平均会使用数十次工具调用,而主智能体的上下文始终保持精简。⚡

学完原理之后,LangChain 官方也提供了 deepagents 抽象包,只需提供子智能体配置和工具即可快速创建同类智能体,本课 Notebook 末尾给出了对应用法。

项目文件导读

文件 作用
notebooks/4_full_agent.ipynb 本课完整教程:组装并运行 Deep Research 智能体
src/deep_agents_from_scratch/research_tools.py Tavily 联网搜索、网页摘要与上下文卸载
src/deep_agents_from_scratch/file_tools.py 虚拟文件系统:ls / read_file / write_file / edit_file
src/deep_agents_from_scratch/todo_tools.py write_todos / read_todos 任务规划工具
src/deep_agents_from_scratch/task_tool.py task 委派工具与子智能体注册机制
src/deep_agents_from_scratch/state.py DeepAgentState:TODO 与文件状态管理
src/deep_agents_from_scratch/prompts.py 全部系统提示词与工具描述模板

常见问题与排错

  • 搜索报错 401 / 无结果? 检查 .env 中的 TAVILY_API_KEY 是否有效,且 load_dotenv 已正确加载(Notebook 首单元格会执行)。
  • 智能体疯狂搜索不停止? 这是子智能体提示词中"搜索预算"在发挥作用(最多 5 次搜索);若仍觉得不够,可调整 prompts.py 中的 RESEARCHER_INSTRUCTIONS。
  • 想看到完整调用轨迹? 配置 LANGSMITH_API_KEY 并开启 tracing,即可在 LangSmith 中查看每一步推理与工具调用。

写在最后

到这里,课程五课内容已全部走完全程:从最简单的 ReAct 智能体,到 TODO 规划、虚拟文件系统、子智能体隔离,最终组装出一个真正支持联网搜索的 Deep Research 智能体。这套"计划 + 卸载 + 隔离"的上下文工程范式,正是当前主流深度智能体的共同底座。动手跑通 Notebook,你的下一个自研智能体框架就有了最扎实的起点。🚀

登录后查看全文
deep-agents-from-scratch