Deep Agents：LangChain 官方「开箱即用」的 Agent——内置能力全解析

前两篇，一篇讲 LangGraph（把 Agent 画成一张图的低层引擎），一篇讲 create_agent（十行代码的最小 Agent 入口）。今天补上 LangChain 三层架构的最顶层：Deep Agents—— 官方那句 "batteries-included"（开箱即用）的 Agent。三篇读下来，LangChain 官方这条 "从最小到全家桶"的 Agent 路径就完整了。

一、它是什么：不是又一个框架，是"装好电池的 Agent"

Deep Agents 是一个独立的库（PyPI 包名就是 deepagents），构建在 LangChain 的核心组件之上，底下跑的依然是 LangGraph 运行时（所以 durable execution、流式、human-in-the-loop 这些能力自动继承）。官方对它的定位说得很直白：

Deep Agents 是一个 "agent harness"——和别的 agent 框架是同一个核心的 tool calling 循环，但内置了一些让 Agent 能胜任真实任务的能力。

关键在"真实任务"四个字。官方还给了选择建议，把三层的关系一次说清：

要开箱即用、要内置能力（上下文压缩、虚拟文件系统、子代理）→ 用 Deep Agents；
要自己掌控、不需要这些内置能力 → 用 create_agent；
要手绘完整控制流 → 自己写 LangGraph workflow。

换句话说，Deep Agents 不是来取代前两层的，而是站在它们之上、把最常见的需求提前做好。上手方式和 create_agent 几乎一样：

pip install -U deepagents

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

换模型同样只改一行 model=。官方支持的 provider 和 create_agent 重叠度很高：openai:gpt-5.5、google_genai:gemini-3.6-flash、openrouter:z-ai/glm-5.2、fireworks:accounts/fireworks/models/glm-5p2、baseten:zai-org/GLM-5.2、ollama:north-mini-code-1.0 等， Claude 这边则是 anthropic:claude-sonnet-4-6。唯一要注意的是：示例里 Claude 的 model 字符串带了 anthropic: 前缀，和 create_agent 文档里默认 provider 的写法不同——provider 前缀不是可省就省的，具体写哪个、什么时候能省，要看版本和文档。

二、内置能力一：一个"虚拟文件系统"，让 Agent 真去干活

Deep Agents 最实在的增量，是给 Agent 配了一个虚拟文件系统。它把日常操作都做成了内置工具：

ls、read_file、write_file、edit_file、delete、glob、grep——文件读写检索一整套；
代码执行——接上沙箱后端，还能用 execute 跑 shell 命令；加了解释器，就用 eval 在受限的 QuickJS 运行时里跑 JavaScript；
可插拔后端——内存、本地磁盘、LangGraph store、复合路由，按需换。

文件系统的权限控制也是内置的：用声明式规则（operations 指定 "read"/"write"，paths 写 glob 模式，mode 设 "allow"/"deny"），从上到下第一个匹配生效——想"只读、只碰某个目录"，写几条规则就行。

三、内置能力二：上下文管理，治"越跑越忘"的病

Agent 跑久了最头疼的问题就是上下文膨胀：聊到后面，前面的内容要么被挤出去、要么 token 越烧越多。Deep Agents 把这类问题内置化了：

技能（Skills）——遵循 Agent Skills 标准，放在含 SKILL.md 的目录里，采用渐进式加载（progressive disclosure）：用到了才加载，不占常住上下文；
记忆——AGENTS.md 通过 memory 参数传入，常驻加载，存在配置的后端里，跨会话保留；
摘要与上下文卸载——内置的 offloading 和 summarization 自动压缩对话历史和大段的中间结果；子代理把重活隔离到自己的小上下文里；长期记忆跨线程持久；
Prompt 缓存——对 Anthropic 和 Amazon Bedrock 的模型自动启用，作用在静态的 system prompt 部分，省 token 省钱。

这正好接上之前写 ECC 时的那个观察： "记忆是下一个前沿"。Deep Agents 把它做成了内置的默认能力。

四、内置能力三：规划、子代理、人机协同

任务规划（Task Planning）

TodoListMiddleware 会给 Agent 加一个 write_todos 工具，让它自己拆任务。注意：从 v0.7 开始这个能力改成可选了（更早的版本是默认开的）——官方默认了"不给 Agent 加戏"，需要再开。

子代理（Subagents）

内置的 task 工具可以创建临时子代理：子代理有自己的全新上下文、自主执行，最后交回一份最终报告就结束。流式事件里 stream.subagents还会给每个被委派的任务一个独立的句柄，方便跟踪。这对"把重活拆给小代理干"非常实用—— 主代理保持轻量，重活不污染它的上下文。

Human-in-the-loop

关键操作前可以插入人工审批：interrupt_on 参数把工具名映射到中断配置，比如 interrupt_on={"edit_file": True} 就在每次编辑前暂停，等人工放行。这比"跑完再审查"安全得多。

五、和生态的关系：三层架构的完整拼图

至此，LangChain 官方文档里的三层就都齐了，三篇连起来就是一张完整的图：

层	定位	适合谁
Deep Agents	开箱即用的 Agent harness，内置文件系统、上下文管理、子代理	要快速交付真实任务的人
LangChain（create_agent）	高度可配置的 Agent 框架，模型/工具/循环的抽象	要掌控行为又不想折腾的人
LangGraph	低层编排框架与运行时，持久化 / 流式 / 人工介入	要手绘控制流、做复杂系统的人

官方还给了两个延伸对比的入口：Frameworks, runtimes, and harnesses 讲这三者到底差在哪；Deep Agents vs. Claude Agent SDK 则是和 Anthropic 自家 harness 的正面对比—— 这个对比文章值得单开一篇，因为它把"开源框架派"和"闭源生态派"两条 Agent 路线的取舍讲得很透。

老规矩，可观测性交给 LangSmith：trace 请求、调试 Agent 行为、评估输出。

我的收获

"开箱即用"不是贬义，是一种工程选择——Deep Agents 把真实任务最高频的需求（文件系统、上下文管理、子代理）全部内置，让你从"搭框架"变成"跑业务"。这和 ECC 的思路异曲同工：都在做"给 Agent 配好工作环境"。
上下文管理会变成 Agent 框架的标配——从 Deep Agents 的自动摘要、prompt 缓存，到 ECC 的记忆保险库、instincts，大家都在治同一个病：上下文是 Agent 最贵的资源。
文件系统权限是"Agent 安全"的第一道闸——声明式 allow/deny 规则、glob 路径匹配，这个设计值得所有 Agent 框架抄。Agent 能读写文件的那一刻，权限就不再是可选配置。
三层不是互斥，是同一件事的三种粒度——Deep Agents 用内置能力换速度，create_agent 用中间件换掌控，LangGraph 用画图换自由。按任务选粒度，比纠结"哪个框架最好"有意义得多。

想深入了解，官方文档在docs.langchain.com/oss/python/deepagents/overview，配着 LangGraph 和create_agent 两篇一起读，就是 LangChain 官方这套 Agent 架构的完整版图。