下一代Agent框架来了:langgraph-101带你入门Deep Agents——create_deep_agent、文件工具与子代理委托一次掌握

原创2026-11-02 21:44:252,274 阅读

下一代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"(智能体骨架):它保留了核心的"模型调用工具"循环,但预置了一套开箱即用的工具与上下文管理能力。

Deep Agents 架构图:LangChain、LangGraph 与文件工具、规划工具的层次关系

调用一次 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 就诞生 🎉

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 只拿回一份干净的最终结果。

Deep Agents 子代理委托流程:task 工具隔离工作并返回最终结果

无子代理:搜索 → 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):

Deep Agents 人机协作 HITL 流程:中断、人工审批与执行

仓库的示例 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️⃣ 快速上手:三步跑起来

  1. 克隆仓库:git clone https://gitcode.com/gh_mirrors/la/langgraph-101,然后 cp .env.example .env 填入 API Key(Tavily Key 用于联网搜索)
  2. 安装依赖:pip install uv && uv sync && source .venv/bin/activate
  3. 启动开发环境:在项目根目录运行 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/ 一致的生产级研究代理 🧠

登录后查看全文
langgraph-101