建站实战干货

27000星deepagents：LangChain把Claude Code架构抽象成了通用框架

先收藏，回头一定用得上。

Harrison Chase 在 2025 年 7 月底发了一篇博客，讲他研究 Claude Code 之后发现的一个模式：那些真正能处理复杂任务的 Agent，和普通的"LLM + 工具循环"之间，差的不只是模型能力，而是架构。

他把这个发现做成了开源包 deepagents，半年不到拿了 27000+ star。这不是又一个 Agent 框架轮子——它是对 Claude Code、Manus、OpenAI Deep Research 这类"深度 Agent"背后共同模式的一次系统化抽象。

我自己用了几周，觉得它解决了一个真实痛点：你想做一个能长时间运行、能规划、能拆分任务的 Agent，但不想从零写状态管理和上下文工程。

本文提纲

1. 什么是 Deep Agent？和普通 Agent 有什么区别
2. 四大核心架构组件
3. deepagents 包的 API 设计
4. 虚拟文件系统：Agent 的"工作台"
5. Sub Agent：上下文隔离的并行执行
6. Skills 和 Memory：让 Agent 越用越聪明
7. 和 LangChain / LangGraph 的关系
8. 谁该用，谁不该用

什么是 Deep Agent？和普通 Agent 有什么区别

大部分 Agent 框架的核心都是同一个循环：LLM 在一个 while 循环里不断调用工具，直到任务完成。Harrison Chase 把这类 Agent 叫做"shallow agent"——不是贬义，而是说它们在处理简单任务时很高效，但一旦任务变复杂、时间跨度变长，就会开始"跑偏"。

跑偏的表现很具体：执行到一半忘了最初的目标，上下文窗口被中间结果撑爆，遇到子任务时不知道该停下来拆分，做了大量重复工作。

Deep Agent 的定义是：能对复杂任务做规划，然后在较长时间跨度上稳定执行的 Agent。Claude Code 是典型代表——它能连续工作几十分钟甚至几个小时，始终围绕目标推进，不会中途迷失。

Harrison Chase 的思路是：Claude Code 之所以能做到这点，不是因为 Anthropic 的模型特别强，而是因为它的架构有四个关键设计。把这四个设计抽象出来，配上任意模型，就能得到一个通用版本的 Deep Agent。

四大核心架构组件

MERMAID_BLOCK_0

这四个组件加在标准 Agent 循环上，构成了 deepagents 的全部核心。

1. 详细的 System Prompt

Claude Code 的 system prompt 非常长，包含工具使用说明、few-shot 示例、行为约束。Harrison Chase 的原话是："没有这些 system prompt，Agent 不会这么 deep。"

这句话在 prompt engineering 被唱衰的今天尤其值得注意。很多人觉得有了更强的模型就不用写复杂 prompt 了，但 Deep Agent 的经验恰恰相反——模型越强，你越需要详细的 prompt 来引导它如何使用工具、如何规划。

deepagents 内置了一个参考 Claude Code 但更通用的 system prompt，你可以通过 system_prompt 参数注入自定义指令。

2. Planning Tool

Claude Code 有一个 Todo List 工具，Harrison Chase 调侃说它"basically a no-op"——它不执行任何实际操作，只是让 Agent 把计划写下来。

但就是这个 no-op，效果显著。原因是它起到了"上下文工程"的作用：Agent 在规划时把任务拆解成具体步骤写进 todo list，执行过程中可以反复回顾这个列表，保持对全局的感知。

deepagents 在 v0.7 之后把 planning 改成了 opt-in，通过 TodoListMiddleware 启用：

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddlewareagent = create_deep_agent(model="anthropic:claude-sonnet-4-6",middleware=[TodoListMiddleware()],
)

3. Sub Agent

Claude Code 能 spawn 子 Agent 来处理子任务。这个设计的核心价值不是"并行"，而是"上下文隔离"。

主 Agent 把一个子任务交给 sub agent，sub agent 在自己的上下文窗口里独立完成，最后只把结果返回给主 Agent。这意味着子任务产生的所有中间 token——搜索结果、代码片段、错误日志——都被隔离在 sub agent 的上下文里，不会污染主 Agent 的窗口。

deepagents 内置了一个 task 工具用于创建临时 sub agent，你也可以定义自己的专用 sub agent。

4. 虚拟文件系统

Claude Code 能读写文件系统，Manus 也大量使用文件系统来做"记忆"。Deep Agent 运行时间长，上下文会不断膨胀，文件系统提供了一个外部存储——把中间结果写进去，需要时再读出来。

deepagents 实现了一套虚拟文件系统，后端可以是内存、本地磁盘、LangGraph Store，甚至沙箱环境。Agent 通过 read_file、write_file、edit_file、grep 等工具操作文件。

deepagents 包的 API 设计

核心入口就一个函数 create_deep_agent，API 设计极其简洁：

from deepagents import create_deep_agentdef 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",
)agent.invoke({"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

model 参数用 provider:model-name 格式，支持 Anthropic、OpenAI、Google Gemini、OpenRouter、Fireworks、Baseten、Ollama 等主流提供商。换模型只改一个字符串，其余代码不动。

完整的参数表：

参数	作用
model	模型字符串，格式 provider:model-name
tools	自定义函数、LangChain 工具或 MCP 工具
system_prompt	Agent 的自定义指令
middleware	中间件列表（文件系统、Todo 等）
memory	持久化记忆文件（AGENTS.md）
interrupt_on	人工审批的工具映射
permissions	文件系统访问的声明式权限规则
subagents	自定义 sub agent 定义

MCP（Model Context Protocol）是原生支持的，你可以直接把 MCP server 的工具传进去。这一点对接入企业内部数据源非常友好。

虚拟文件系统：Agent 的"工作台"

虚拟文件系统是 deepagents 最有意思的设计之一。它不是简单的"让 Agent 能读写文件"，而是一整套上下文管理基础设施。

内置的文件操作工具：

工具	功能
ls	列出目录，含文件大小和修改时间
read_file	读取文件内容，支持行号、offset/limit、多模态
write_file	创建或覆盖文件
edit_file	精确字符串替换，支持全局替换
delete	删除文件或目录（v0.7+）
glob	按模式查找文件
grep	搜索文件内容
execute	执行 shell 命令（仅沙箱后端）

read_file 支持多模态内容——图片、视频、音频、PDF、PPT 都能读。这意味着 Agent 可以"看"文件里的图片，而不只是处理文本。

如果你只想让 Agent 有读权限，没有写权限，可以通过 FilesystemMiddleware 限制工具子集：

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware# Read-only agent
agent = create_deep_agent(model="claude-sonnet-4-6",middleware=[FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),],
)

注意 read_file 是必须包含的，省略会报 ValueError。这是框架的强制设计——没有读能力的 Agent 没法用文件系统。

文件系统权限用声明式规则，按声明顺序匹配，first-match-wins：

permissions = [PermissionRule(operations={"read", "write"}, paths=["/workspace/**"], mode="allow"),PermissionRule(operations={"write"}, paths=["/workspace/secrets/**"], mode="deny"),
]

上面的规则允许 Agent 读写 /workspace 下的所有文件，但禁止写入 /workspace/secrets 目录。

Sub Agent：上下文隔离的并行执行

Sub Agent 的设计原理值得单独说一下，因为它和很多人想象的"多 Agent 协作"不太一样。

deepagents 的 sub agent 有几个特点：

• Fresh context：每次调用创建全新的 Agent 实例，干净的上下文窗口
• Autonomous execution：独立运行直到完成
• Single handoff：只返回一份最终报告给主 Agent
• Stateless messaging：sub agent 不能多次给主 Agent 发消息

这个设计是有意为之的。Harrison Chase 在博客里解释：深度是通过"spinning up sub agents that specifically focused on individual tasks"来实现的。子任务的所有中间过程被压缩成一份紧凑的结果返回，主 Agent 的上下文保持干净。

实际使用场景：主 Agent 在做深度研究，需要搜索 10 个不同的子话题。如果自己在主上下文里逐个搜索，10 个搜索结果 + 网页内容会把上下文撑爆。用 sub agent 的话，每个子话题由独立的 sub agent 搜索和总结，主 Agent 只收到 10 份摘要。

如果你想禁用 sub agent（比如简单任务不需要拆分），不能直接移除 SubAgentMiddleware——框架会拒绝。正确做法是通过 harness profile 禁用默认的 general-purpose sub agent，同时不传 subagents= 参数。

Skills 和 Memory：让 Agent 越用越聪明

deepagents 引入了两个上下文管理机制：Skills 和 Memory。

Skills

Skills 遵循 Agent Skills 标准（agentskills.io），每个 Skill 是一个目录，包含 SKILL.md 文件和可能的脚本、模板、参考文档。

关键设计是"渐进式加载"：Agent 启动时只读 SKILL.md 的 frontmatter（名称、描述、触发条件），需要用到时才加载完整内容。这避免了启动时把所有 Skill 的全文塞进上下文。

Memory

Memory 用 AGENTS.md 文件实现，通过 memory 参数传入。和 Skills 不同，Memory 文件是始终加载的——它们是 Agent 的"长期记忆"。

更有意思的是 Agent 可以在运行过程中更新 Memory。比如用户告诉 Agent "我喜欢用 pytest 不用 unittest"，Agent 可以把这个偏好写回 Memory 文件，下次对话自动生效。

上下文管理的四层模型

deepagents 的上下文管理是一个四层流程：

MERMAID_BLOCK_1

1. Input Context：system prompt + memory + skills + tool prompts
2. Compression：历史和大量结果的摘要与卸载
3. Isolation：sub agent 隔离重子任务，只返回最终结果
4. Long-term Memory：持久化到虚拟文件系统

此外，Anthropic 和 Amazon Bedrock 模型会自动启用 prompt caching——对 system prompt 的静态部分（基础指令、memory、skill 内容）做缓存，不需要配置。这对长 system prompt 的场景能省不少 token。

和 LangChain / LangGraph 的关系

很多人会问：我已经在用 LangChain 或 LangGraph 了，deepagents 和它们什么关系？

Harrison Chase 在博客里做了明确区分：

框架	定位	适用场景
LangChain	快速启动 Agent，支持任意模型提供商	简单 Agent、原型验证
LangGraph	低级控制，可靠 Agent 的运行时	需要精确控制流程、状态、错误处理
deepagents	电池全含的 Agent harness	长时间运行的复杂任务

deepagents 建立在 LangChain 和 LangGraph 之上——LangChain 提供核心构建块（模型集成、工具定义），LangGraph 提供运行时（durable execution、streaming、human-in-the-loop），deepagents 在两者之上封装了 Deep Agent 的四件套（prompt + planning + sub agent + filesystem）。

如果你已经在用 LangGraph 并且自己实现了类似的架构，deepagents 可能就是帮你省了一些样板代码。如果你从头开始做复杂 Agent，直接用 deepagents 会省很多事。

Human-in-the-loop 也是通过 LangGraph 的 interrupt 机制实现的：

agent = create_deep_agent(model="anthropic:claude-sonnet-4-6",interrupt_on={"edit_file": True},
)

这会让 Agent 在每次调用 edit_file 之前暂停，等你批准、修改或添加指导后再执行。对生产环境的敏感操作审批很有用。

LangChain 还基于 deepagents 做了一个 open_deep_research 项目（12000+ star），是一个开箱即用的深度研究 Agent，可以作为学习 deepagents 用法的参考实现。

谁该用，谁不该用

deepagents 不是银弹。根据我的使用经验，适用场景和踩坑点都比较明确。

适合用的场景：

• 需要长时间运行的 Agent（深度研究、代码分析、数据处理 pipeline）
• 任务可以自然拆分成子任务
• 需要跨对话保持记忆和偏好
• 需要人工审批关键操作

不太适合的场景：

• 简单的一问一答（杀鸡用牛刀，徒增开销）
• 对延迟敏感的实时场景（sub agent spawn 有额外开销）
• 需要精确控制每一步流程的 Agent（用 LangGraph 直接写更合适）

踩坑提醒：

1. v0.7 是个分水岭：planning 从默认启用改成了 opt-in，升级版本时注意检查你的 middleware 配置
2. sub agent 不能移除：SubAgentMiddleware 和 FilesystemMiddleware 是"intentionally rejected"的，不能通过 excluded_middleware 移除。想禁用只能通过 harness profile
3. read_file 必须保留：限制文件系统工具子集时，read_file 不能省略，否则直接报错
4. 沙箱后端不受权限规则约束：permissions 不适用于 sandbox backends，如果你需要严格的权限控制，别用沙箱模式

一个实际建议：先用 open_deep_research 跑通一个完整流程，理解四件套怎么协作，再回来定制自己的 deep agent。直接从 create_deep_agent 开始配会漏掉很多设计意图。

参考文档与链接

• Deep Agents - Harrison Chase 博客原文 - 概念定义、四大组件、设计思路的权威来源
• GitHub: langchain-ai/deepagents - 27596 star，Python，核心包源码
• Deep Agents 官方文档 - API 参考、quickstart、customization 指南
• GitHub: langchain-ai/open_deep_research - 12582 star，基于 deepagents 的深度研究 Agent 参考实现
• GitHub: langchain-ai/deep-agents-ui - 1708 star，Deep Agents 的自定义 UI
• GitHub: langchain-ai/deep-agents-from-scratch - 804 star，从零实现 Deep Agent 的教程
• Agent Skills 标准 - Skills 的规范定义，deepagents 遵循此标准
• Deep Agents API Reference - 完整 API 文档
• LangGraph 文档 - 运行时层文档，理解 durable execution 和 interrupt 机制

试过了？评论区说说你的体验。还没试？收藏起来周末折腾。觉得有用点个赞让更多人看到。

---

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。