Deep Agents 概览

Deep Agents 面向的是“模型需要持续规划、使用文件、委派任务并管理长上下文”的 Agent。它不是新的基础模型，也不是替代 LangGraph 的流程引擎，而是一套建立在 LangChain 与 LangGraph 之上的约定式 Harness。

版本基线：本文核心示例以 Python deepagents 0.6.12 和 TypeScript deepagents 1.10.7 为准。Python 包在 PyPI 中仍标记为 Beta，常规发行不等同于长期稳定承诺。

三层架构

层级	负责什么	何时直接使用
LangGraph Runtime	状态、checkpoint、streaming、interrupt、可恢复执行	需要自定义图结构或精确控制执行拓扑
LangChain `create_agent`	模型、工具与 middleware 驱动的基础 Agent 循环	需要轻量 Agent，不需要成套长任务能力
Deep Agents	预配置 planning、filesystem、subagents 与上下文管理	任务长、信息量大，需要委派与持久工作区

Deep Agents 最终返回的是一个已编译的 LangGraph 图，因此仍能使用 LangGraph 的 stream、 checkpointer、store 与部署生态。

前端类比

如果把 LangGraph 类比为浏览器的事件循环与状态调度能力，把 create_agent 类比为一个小型 React 应用入口，那么 Deep Agents 更像一个带路由、数据访问、错误边界和工程约定的应用框架。你可以接受默认组合，也可以替换其中的模块。

Deep Agents 原生语义：Deep Agents 并不生成另一种运行时。它组装 middleware、backend 与 subagent 配置，然后调用 LangChain create_agent；状态和执行语义继续由 LangGraph 提供。

默认提供什么

create_deep_agent 与 createDeepAgent 默认组装以下能力：

任务规划：通过 write_todos 管理可见的任务列表。
虚拟文件系统：通过 filesystem 工具读写、搜索和编辑文件。
子 Agent 委派：通过 task 把独立问题交给隔离上下文中的 subagent。
上下文压缩：接近上下文限制时总结历史，并可把大结果 offload 到文件。
工具调用修复：补齐或修复跨模型提供商的部分 tool-call 兼容问题。

默认 backend 是 StateBackend。文件存放在当前 LangGraph thread 的 Agent state 中，同一个 thread 可跨多轮访问，但它不是自动跨用户共享的长期存储。

以下能力不是无条件默认开启：

只有传入 skills 才加载 Skills middleware。
只有传入 memory 才加载 Memory middleware。
只有配置 interrupt_on 才加入 HITL 审批。
跨 thread 持久化需要 StoreBackend、CompositeBackend 或其他持久 backend。
任意代码执行需要明确选择 sandbox、LocalShell 或相应 backend。

最小创建方式

这里先看 API 形状。模型字符串通过环境变量注入，避免把易过时的模型名称写死在教程里。

PythonTypeScript

python

import os

from deepagents import create_deep_agent

model = os.environ["DEEPAGENTS_MODEL"]

agent = create_deep_agent(model=model)

import { createDeepAgent } from 'deepagents'

const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')

const agent = createDeepAgent({ model })

DEEPAGENTS_MODEL 使用 LangChain 支持的 provider:model-name 形式，并且所选模型必须支持 tool calling。你还需要安装该 provider 对应的 LangChain 集成包。

什么时候适合使用

适合 Deep Agents 的任务通常同时具备多个特征：

任务不能靠一次模型调用完成，需要显式计划与多轮工具使用。
中间材料较大，需要文件系统承载而不是全部塞进 messages。
可以拆成研究、实现、审查等相对独立的子任务。
需要在执行过程中暴露进度、暂停审批或恢复运行。
希望保留 LangChain 模型生态与 LangGraph 运行时能力。

如果任务只是“调用一个工具后返回结果”，create_agent 通常更直接。如果流程拓扑必须由应用代码完全决定，例如精确的分支、循环和汇聚节点，直接使用 LangGraph 会更清晰。

不应误解为什么

不是自动可靠性开关：更多工具和 subagents 也会增加失败面。
不是权限系统：模型能做什么最终由工具、backend、sandbox、网络和凭据决定。
不是无限上下文：summarization 与 offloading 只是管理预算，仍可能丢失细节。
不是单一产品：SDK、Deep Agents Code、部署 CLI 与 Managed Deep Agents 有不同职责。

学习路径

先用生态定位与选型判断是否需要 Harness。
在安装、版本与模型配置固定可靠的发行基线。
完成快速上手，观察 planning 与工具调用。
深入 filesystem、context engineering、subagents、HITL 与工程化页面。
最后组合研究型 Agent 或安全编码 Agent。

先修

下一步

Deep Agents 生态定位与选型

Deep Agents 概览 ​

三层架构 ​

前端类比 ​

默认提供什么 ​

最小创建方式 ​

什么时候适合使用 ​

不应误解为什么 ​

学习路径 ​

先修 ​

下一步 ​

官方参考 ​