终极实战:deep-agents-from-scratch第4课——组装支持联网搜索的完整Deep Research智能体
终极实战: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 + 三组工具构成:
| 能力 | 对应工具 | 解决的问题 |
|---|---|---|
| 📋 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。它并不是"搜到什么就把什么塞给智能体",而是一条完整的上下文卸载流水线:
- 执行搜索:
run_tavily_search()调用 Tavily API 发起联网搜索,支持general/news/finance三种主题过滤; - 抓取与转换:
process_search_results()用 httpx 抓取网页全文,再通过markdownify把 HTML 转成 Markdown; - AI 摘要:
summarize_webpage_content()使用轻量模型(GPT-4o-mini)生成 150 词以内的极简摘要,并自动起一个有语义的文件名(如mcp_protocol_overview.md); - 落盘 + 最小返回:
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
)
实际运行:让智能体联网调研 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,你的下一个自研智能体框架就有了最扎实的起点。🚀




