许多人仍在 LangGraph 里手搓 agent 循环。Deep Agents 给出了一个更高层的答案——而且比你预想的更 opinionated。
几乎所有认真构建 agent 的团队，我都看到同一个模式在重复上演。
先是用 LangChain 的 chains。做简单 pipeline 没问题。等任务一复杂——需要 tool calls、需要 loop、需要处理 variable-length outputs——chains 就不够用了。于是转向 LangGraph，然后在真正开始解决问题之前，就已经在写 state schemas、conditional edges 和 graph compilation 逻辑了。
并不是说 LangGraph 不好。它非常强大。但它是一个 runtime（低层原语），而大多数人却把它当成 application framework 来用。LangChain 注意到了这一点，deepagents 就是他们的答案。
Deep Agents 究竟是什么
直说吧，“deep agents” 听起来可能泛指很多东西。
deepagents 是一个独立的 Python 库（用 pip install deepagents 安装），构建在 LangChain 和 LangGraph 之上。LangChain 文档把它称为一个 “agent harness”：它提供与其他框架相同的核心 tool-calling loop，但把一组关键能力内置好了，你就不用每次都重造轮子。
核心函数是 create_deep_agent()。最简单的用法：
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(
tools=[get_weather],
system_prompt="You are a helpful assistant",
)
agent.invoke(
{"messages": [{"role": "user", "content": "What is the weather in Mumbai?"}]}
)
就这样，一个函数。底层由库来处理 LangGraph graph、state management、streaming 和 context window management——这些你都不需要碰。
但真正的亮点在于它默认内置了什么。
五个让它与众不同的能力
1. 内置规划：write_todos
每个 deep agent 都自动拥有一个 write_todos 工具。面对复杂任务时，agent 会用它把工作拆成离散步骤，跟踪它们的状态（pending、in_progress、completed），并在任务推进中动态调整计划。
这点很关键，因为这不只是 prompt 技巧——to-do 列表会持久化在 agent state 中。agent 可以回访、更新，并在整个会话生命周期内引用它。你不需要手动提示模型 “think step by step”。这种结构被烘焙进了 harness。
2. 一个虚拟文件系统
这点最让我意外。Deep agents 默认带了一组 filesystem 工具：ls、read_file、write_file、edit_file、glob 和 grep。
为什么 agent 需要 filesystem？为了做 context management。
LLM 的 context window 是有限的。长时间的调研、跑代码、或处理大型工具结果时，会话历史很容易爆炸式增长。Deep agents 的做法是把大内容 offload 到虚拟 filesystem，而不是都塞进 context window。
当某个工具结果超过 20,000 tokens 时，库会自动把它保存到配置好的 backend，并在上下文中用文件路径引用和 10 行预览替代原文。agent 之后可在需要时 read_file 或 grep 该文件。这是智能的 context compression——既不是 chunking，也不是粗暴的 truncation，而是有目的的 offloading 与按需 retrieval。
filesystem 的 backend 可选：内存（默认）、本地磁盘、用于跨 thread 持久化的 LangGraph Store，或像 Modal、Daytona 这样的 sandboxed 环境。backend 是可插拔的。
3. Subagent Spawning
harness 内置了一个 task 工具，让主 agent 可以为隔离的子任务 spawn 专门的 subagents。
为什么这比听起来更重要？在长时间调研里，如果一个单一 agent 处理一切，它的上下文会被中间步骤、搜索结果和半成品挤满。Subagents 是个优雅的解法：主 agent 把特定子任务委派给一个干净上下文的新 agent 实例。subagent 自主运行、完成工作，只把一个总结返回给主 agent。主 agent 的上下文保持干净。
你可以配置自定义 subagents，拥有各自的 tools 和 system prompts：
from deepagents import create_deep_agent, Subagent
code_reviewer = Subagent(
name="code-reviewer",
system_prompt="You are an expert code reviewer. Analyze code for bugs, style, and performance.",
tools=[read_file_tool],
)
agent = create_deep_agent(
tools=[internet_search],
subagents=[code_reviewer],
system_prompt="You are a research and engineering assistant.",
)
默认 subagent（一个带 filesystem 工具的通用型）始终可用，无需额外配置。
4. 自动 Context Compression 与 Summarization
这正是该库在长时间任务中体现价值的地方。
当 agent 的上下文达到模型 context window 限制的 85%，且已无内容可再 offload 到 filesystem 时，harness 会触发自动 summarization。一个 LLM 会生成结构化摘要——会话意图、已产出的 artifacts、下一步计划——并用该摘要替换工作内存中的完整历史。原始消息则保存到 filesystem 作为权威记录，必要时 agent 仍能找回具体细节。
结果就是，deep agents 能在复杂任务上无限期运行而不触碰 context 限制——这在用原生 LangGraph 时通常需要你手动工程化实现。
5. 跨会话的长期记忆
默认情况下，agent state 只存在于单一 thread 内。但如果用带 LangGraph Store 的 CompositeBackend 进行配置，agent 就能在会话与 threads 之间持久化记忆。
存放在 /memories/ 路径（或你自定义位置）的文件，会在 agent 重启后依然存在，并可从任意会话 thread 访问。这使你可以构建一个能记住你的偏好、代码库约定，或数天研究进展的 agent。
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()
backend = CompositeBackend(
routes={"/memories/": StoreBackend(store=store)},
default=StateBackend(),
)
agent = create_deep_agent(
tools=[...],
backend=backend,
memory=["path/to/AGENTS.md"], # persistent context file
)
它在 LangChain 生态中的定位
这部分容易让人困惑，值得明确说说。
LangChain 是提供构件的框架：models、tools、prompts、chains。它是基础层。
LangGraph 是一个 runtime，用于可持久的、有状态的、基于 graph 的 agent 执行。它处理 persistence、streaming、interrupts 和复杂的 conditional flows。它是 engine。
Deep Agents 是构建在两者之上的 harness。它不是 LangGraph 的替代品——底层一切都用的 LangGraph。它提供的是更高层的 API 和 opinionated defaults，这样你就不用每次都从零实现 planner、filesystem 层、context compression 和 subagent 基础设施。
这么想：LangGraph 给你的是 engine 和 transmission。Deep Agents 给你的是一辆车。
对直截了当的 agent，LangChain 的 create_agent 可能就够了。对复杂、长时间、多步骤、且有大 context 需求的任务，deepagents 的抽象成本才真正值回票价。
构建一个 Research Agent：真正的 Quickstart
这是一个实用例子——一个能搜索网页并产出结构化报告的 research agent：
import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(
query: str,
max_results: int = 5,
topic: Literal["general", "news", "finance"] = "general",
include_raw_content: bool = False,
):
"""Run a web search and return results."""
return tavily_client.search(
query,
max_results=max_results,
include_raw_content=include_raw_content,
topic=topic,
)
research_instructions = """You are an expert researcher.
Your job is to conduct thorough research and then write a polished report.
Use internet_search to gather information.
Write your findings to files as you go to avoid losing context.
Use write_todos to plan your research steps before starting.
"""
agent = create_deep_agent(
model="anthropic:claude-sonnet-4-6", # default model
tools=[internet_search],
system_prompt=research_instructions,
)
result = agent.invoke({
"messages": [{
"role": "user",
"content": "Research the current state of agentic AI frameworks in 2025 and write a structured report."
}]
})
print(result["messages"][-1].content)
运行后会发生什么：
agent 调用
write_todos来规划研究步骤它执行搜索，并把大的结果自动 offload 到虚拟 filesystem
如果任务复杂，它会 spawn 一个 subagent 处理特定部分
按需回读相关文件并综合出最终报告
全程由 harness 管理上下文，模型不会触达 window 极限
这些基础设施你一行都没写——harness 自带了。
Deep Agents CLI
还有一件值得知道的事：deepagents 也提供了一个基于同一 SDK 的命令行 agent。
pip install deepagents
deepagents # launches the interactive CLI agent
这是一个能在终端里运行的 coding agent——想想 Claude Code 或 Aider，但它是基于 Deep Agents SDK 构建的。它支持交互模式、非交互管道模式（用于脚本的 -n 标志）、自定义 skills，以及持久化 memory。你可以教会它你的项目约定，它会在会话间记住这些。
这意味着支撑你生产级 research agent 的同一 SDK，同时也开箱即用地提供了一个可用的开发者工具。
什么时候该用（以及不该用）
deepagents 适用于：
-
任务需要规划，并由多个步骤完成 -
工具结果很大，需要在长会话中进行管理 -
你想要 subagent 委派，但不想自己搭基础设施 -
需要跨会话 threads 的持久化 memory -
你在构建 coding agent 或自主研究系统
继续用 LangChain 的 create_agent 或原生 LangGraph 当：
-
你的 agent 很简单：一两次 tool calls、短回复 -
你需要对 graph topology 有极细粒度控制 -
你已经深度投入自定义的 LangGraph workflow，不想被 opinionated defaults 约束
该库在自己的文档里也很诚实：简单的 agent 就用更简单的工具。
为什么这不只是又一个框架发布
时机值得一提。
Agentic AI 正处在拐点。基础模式——tool calling、ReAct loops、简单 RAG——已人尽皆知。业内现在在攻克的，是如何让 agent 在 long-horizon 任务上更可靠：需要规划、大上下文、持久化和委派的任务。
每个做生产级 agent 的团队，都不得不从零工程化解决这些同样的问题。Context management 策略、subagent 模式、memory 架构——这些在不同组织里被一遍遍用略微不同的形式重造。
deepagents 是 LangChain 的一个押注：这些解法足够通用，可以标准化。所谓 agent harness——有主见的默认、内建的基础设施、可插拔 backends——就是把话题从 “怎么搭管道？” 转向 “我们真想让 agent 做什么？” 的一次尝试。
能否成功要看这些默认在生产中是否扛打。但从设计方向看，这是对的。
开始上手
pip install deepagents tavily-python
设置你的 API keys：
export ANTHROPIC_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
export LANGSMITH_TRACING=true # optional, for debugging
export LANGSMITH_API_KEY="your-key"
完整文档——包括 backends、subagents、sandboxes、human-in-the-loop，以及 CLI——见 docs.langchain.com/oss/python/deepagents。
如果你现在在做任何严肃的 agent 项目，花一个下午弄懂 deepagents 在你的技术栈里处于什么位置，都是值得的——即使你不会立刻用上它。
在用 Deep Agents 做项目吗？尤其欢迎做 research automation、financial analysis 或 coding workflows 的同学留言分享。