下一代Agent框架来了:langgraph-101带你入门Deep Agents——create_deep_agent、文件工具与子代理委托一次掌握
下一代Agent框架来了:langgraph-101带你入门Deep Agents——create_deep_agent、文件工具与子代理委托一次掌握
学习 Deep Agents 入门不必再翻长篇文档!开源教程仓库 langgraph-101 通过一个"从零构建研究代理"的实战 Notebook,带你一次性掌握 create_deep_agent 的用法、内置文件工具、后端存储、子代理(Subagent)委托、人机协作(HITL)与长期记忆。无论你是刚接触 LangGraph 的新手,还是想把 Agent 投入生产的工程师,这篇教程都能帮你快速建立完整的知识地图 🚀
1️⃣ langgraph-101 是什么?两条学习轨道
langgraph-101 是 LangChain 官方出品的 LangGraph 实战教程仓库,内容浓缩自 LangChain Academy 课程,分为两条学习轨道:
| 轨道 | 位置 | 内容 |
|---|---|---|
| 101 基础篇 | notebooks/101/ | 模型、工具、记忆、流式输出、中间件与人工介入 |
| 201 进阶篇 | notebooks/201/ | 多智能体系统、Deep Agents、生产级工作流 |
本文聚焦进阶篇中的 deep_agents.ipynb——它按照"渐进式构建"的思路,从最基础的 create_deep_agent() 调用出发,一步步为研究代理叠加搜索工具、子代理、中间件、人工审批、长期记忆,最终得到一个可运行的完整 Agent。
2️⃣ 理解 Agent Harness:create_deep_agent 开箱即得什么
Deep Agents 是构建在 LangGraph 之上的"agent harness"(智能体骨架):它保留了核心的"模型调用工具"循环,但预置了一套开箱即用的工具与上下文管理能力。
调用一次 create_deep_agent(),你就免费获得:
- 文件工具:
ls、read_file、write_file、edit_file、glob、grep - 规划工具:
write_todos,用于任务拆解与进度跟踪 - 子代理委托:
task()工具,把复杂工作隔离到独立上下文 - 大结果自动卸载:超过 2 万 token 的工具结果自动写入文件系统
- 对话摘要:上下文接近 85% 容量时自动压缩历史
- 悬空工具调用修补:自动修复消息历史的兼容性问题
最小示例只需一行核心代码:
from deepagents import create_deep_agent
agent = create_deep_agent(model=model)
就这么简单,一个拥有文件系统和规划能力的 Deep Agent 就诞生 🎉
3️⃣ 文件工具 + Backends:Agent 的文件到底存在哪?
这是很多新手最容易困惑的点:write_file 写下去的文件去哪儿了?答案是由 Backend(可插拔存储后端) 决定的:
| 后端 | 存储位置 | 持久性 | 典型场景 |
|---|---|---|---|
| StateBackend | 内存(Agent 状态) | 单线程 | 草稿、中间结果(默认) |
| FilesystemBackend | 本地磁盘 | 永久 | 直接读写真实文件 |
| StoreBackend | LangGraph Store | 跨线程 | 长期记忆 |
| CompositeBackend | 路由到多个后端 | 混合 | 选择性持久化 |
实战中的推荐组合是 CompositeBackend——按路径前缀把文件路由到不同存储:
composite_backend = CompositeBackend(
default=FilesystemBackend(root_dir=AGENT_DIR, virtual_mode=True),
routes={"/memories/": StoreBackend()},
)
⚠️ 提示:
FilesystemBackend会写真实磁盘,务必设置virtual_mode=True把路径沙箱化,防止路径穿越攻击。
完整实现可参考 agents/deep_agent/agent.py。
4️⃣ 子代理委托:用 task() 解决上下文爆炸
随着 Agent 干的活越来越多,主上下文会被一次次搜索的中间结果塞满。子代理(Subagent) 的解法是:把脏活累活隔离到独立上下文里干,主 Agent 只拿回一份干净的最终结果。
无子代理:搜索 → 5000 token 结果 → 思考 → 再搜索…… 上下文越滚越大
有子代理:task("research-agent", "调研某主题") → 隔离执行 → 只返回压缩后的摘要
定义子代理只需一个字典,无需手写图结构:
research_subagent = {
"name": "research-agent",
"description": "Delegate research tasks. Give one topic at a time.",
"system_prompt": RESEARCHER_INSTRUCTIONS,
"tools": [tavily_search],
}
主 Agent 传入 subagents=<a href="https://link.gitcode.com/i/2f9858ae22cb871c7b1117e1dcc0bbc2" target="_blank">research_subagent] 后即可随时通过 task() 委托研究任务。仓库中的完整定义见 [agents/deep_agent/agent.py。
5️⃣ 中间件与人工介入:给 Agent 装上"安全闸门"
Deep Agents 采用模块化中间件架构,create_deep_agent() 会自动装配 TodoList、Filesystem、SubAgent、Summarization、PatchToolCalls 等中间件;你也可以通过 middleware=[...] 传入自定义中间件(比如用 @wrap_tool_call 钩子实时记录每次工具调用)。
对于敏感操作,interrupt_on 参数可以让 Agent 在执行前暂停并等待人类决策——批准(approve)、修改参数(edit)或拒绝(reject):
仓库的示例 Agent 就对 write_file 和 edit_file 开启了人工审批:
agent = create_deep_agent(
model=model,
tools=[tavily_search],
subagents=[research_subagent],
backend=composite_backend,
interrupt_on={"write_file": True, "edit_file": True},
)
6️⃣ 长期记忆 + AGENTS.md + Skills:让 Agent 越用越懂你
长期记忆:借助 CompositeBackend,/memories/* 路径路由到 StoreBackend,文件即可跨会话、跨线程持久保存;其他路径保持临时性。你甚至可以按认知科学把记忆分为语义记忆(事实偏好)、情景记忆(历史经验)、程序性记忆(规则流程)三类目录。
AGENTS.md:可自我进化的系统提示词。仓库中的 agents/deep_agent/AGENTS.md 用纯 Markdown 定义了研究助手的身份、工作流(规划 → 委托调研 → 综合 → 写报告 → 记忆沉淀)与引用规范。它通过 memory=["./AGENTS.md"] 参数注入系统提示词,而且 Agent 可以编辑自己的 AGENTS.md——这等于一个"可自我修改的系统提示词"。生产环境建议把关键规则锁进不可编辑的 system_prompt。
Skills:按需加载的能力包。每个 Skill 是一个带 frontmatter 的 SKILL.md 文件,启动时只加载"名称 + 描述"几个 token,Agent 判断相关时才读取全文(渐进式披露)。仓库内置了两个示例技能:
7️⃣ 快速上手:三步跑起来
- 克隆仓库:
git clone https://gitcode.com/gh_mirrors/la/langgraph-101,然后cp .env.example .env填入 API Key(Tavily Key 用于联网搜索) - 安装依赖:
pip install uv && uv sync && source .venv/bin/activate - 启动开发环境:在项目根目录运行
langgraph dev,获得本地 API 服务与 LangGraph Studio 可视化调试界面,然后打开"Deep Agent"试一句"调研某个话题并写一篇 LinkedIn 帖子"
Agent 注册表在 langgraph.json 中定义,包含 Deep Agent、Research Agent、Music Store Supervisor 等 9 个可直接运行的示例。
8️⃣ 总结:一张表看懂 Deep Agents 核心能力
| 概念 | 作用 | 学习位置 |
|---|---|---|
| Agent Harness | 预置文件/规划工具 + 上下文管理 | notebooks/201/deep_agents.ipynb Part 1 |
| Backends | 控制文件存储:临时、磁盘、持久、混合 | Part 3 |
| Subagents | task() 委托,隔离上下文 |
Part 4 |
| Middleware | 可插拔能力模块,自动装配 | Part 5 |
| HITL | 敏感操作人工审批 | Part 6 |
| Long-term Memory | 路径路由 + 命名空间隔离 | Part 7 |
| AGENTS.md / Skills | 文件化身份 + 按需能力 | Part 8 |
Deep Agents 的设计哲学很清晰:框架负责编排,你只需专注能力。沿着 notebooks/201/deep_agents.ipynb 从 Part 0 到 Part 10 逐节执行,你就能亲手构建出与 agents/deep_agent/ 一致的生产级研究代理 🧠



