Deep Agents 是什么？30.1K 星的开源 Agent 座架，把 Claude Code 那套拆成能自己拼的零件（基础篇）
导语
做 Agent 的人到后面都会碰到同一堵墙，难的不是调一次模型，是让一个 Agent 连着干二十步还不崩：上下文被工具输出塞满、子任务把主线程带跑偏、干到一半忘了自己要干嘛。LangChain 官方 2025 年 7 月专门开了个新仓库来啃这块硬骨头，就是 Deep Agents。我 2026 年 10 月 12 日实测拉了 GitHub API 和 PyPI 的数据：30,141 星、4,224 fork、MIT 协议；PyPI 上 0.7.23 版是 10 月 7 日发的，最近 30 天下载 566 万次。仓库 2025 年 7 月底才建，一年多做到这个量级，在 Agent 框架里已经算头部。
项目介绍
官方给它的定位一句话：agent harness，直译「座架」。跟 LangChain、LangGraph 的关系，官方 FAQ 里说得清楚：LangGraph 是图运行时，LangChain 的 create_agent 是最薄的一层座架，Deep Agents 是再往上一层「有主见」的座架：同样的积木，但下面这些默认给你装好了。
- 子代理委派：子任务丢给上下文隔离的子代理去跑，主线程不被撑爆；
- 虚拟文件系统：读、写、改、搜，后端可以是本地、沙箱或远程；
- 上下文管理：长对话自动摘要，工具返回的大块内容直接甩到磁盘；
- 持久记忆：state 和 store 都可插拔，跨会话召回；
- Skills：按需加载的可复用行为，和前面讲过的Agent Skills 是同一套思路；
- 人工审批（HITL）：关键工具执行前先停下来，等你批准、改写或拒绝；
- 工具层：自己的函数，或者任意 MCP server 直接挂进来。
底层跑在 LangGraph 上，流式输出、checkpoint、持久化全是现成的；模型层完全不挑，任何支持 function calling 的模型都能用，官方文档里直接给了 Ollama、vLLM、llama.cpp 的自托管写法。仓库 README 的致谢栏写得很直白：灵感来自 Claude Code，想把「它为什么能干通用活」这件事拆出来再往前推一步。想直接拿它当终端编码工具也有配套，Deep Agents Code 一行 curl 装完，模型随便换。想自己从头搭图编排的，可以回头看那篇 LangGraph 基础篇，那套执行模型在 Deep Agents 里原封不动在用。
上手
uv add deepagents
from deepagents import create_deep_agent
agent = create_deep_agent(
model="ollama:qwen3:8b", # 写法是 provider:model
system_prompt="你是一个调研助手",
)
agent.invoke({"messages": "调研 LangGraph，写一份 500 字摘要"})
跑起来之后它会自己列待办、开子代理、往虚拟文件系统里落文件；把 HITL 打开，写文件、执行命令这类动作会先停下来等你点头。接自己的工具就往 tools 里塞函数，或者直接挂 MCP server。注意依赖：现在要求 langchain >= 1.4.3，也就是 LangChain v1 那条线，塞进老项目会直接依赖冲突。本地模型怎么跑参考Ollama 那篇，哪个尺寸的模型撑得住工具调用看本地推理对比。
实话
一、模型门槛是真的。这套座架默认模型会规划、会用工具、会自己写文件。我这边的体感是 14B 往上才稳，7B 级别跑超过十步就开始丢待办、乱写文件路径。本地跑建议 14B 起步，关键步骤还是走 API，别跟自己过不去。
二、版本还在爬坡。0.7.x 意味着 API 没冻结，PyPI 上 8 月到 10 月几乎一周一版，每次发版都在动中间件和配置项。上生产就把版本锁死，升级前先看 changelog。
三、安全模型是「信任模型」。官方 SECURITY 文档说得直接：agent 能干的事等于它的工具能干的事，别指望模型自觉。想限制就靠沙箱和权限收紧，不靠提示词。README 里把 shell 执行当标配能力写出来，底气是「边界在沙箱层」这个架构选择，不是模型本身安全。
四、别为了用而用。只需要一个工具调用循环，LangChain 的 create_agent 更轻；流程形状不对就直接下到 LangGraph 自己画图。Deep Agents 的真正价值，是把座架层那堆脏活（上下文管理、委派、文件系统）替你干了，仅此而已，别把它当成银弹。
五、生态默认绑 LangSmith。官方把 LangSmith 当作追踪、评估、部署的默认配套，想自建观测体系就得自己把这块换掉，好在它底层是标准 LangGraph，钩子都在。
