上个月，我正在为团队搭建一个自动化研究流水线。想法很简单：给系统一个主题，让它去搜索信息、综合研究结果，最后生成一份结构化的报告。我一开始用了一个基础的 ReAct 智能体，处理简单查询时表现还不错。但当我抛出类似“比较欧盟、美国和中国在 AI 监管方式上的异同”这种问题时，一切都崩了。智能体会忘记自己已经研究过什么，跑到一半上下文窗口就爆了，而且生成的报告里前后章节经常自相矛盾。
我一直卡在三个绕不开的痛点上：长任务的上下文管理、无法将复杂目标拆解为可追踪的步骤，以及没法让独立的研究线索并行处理。就在这时，我偶然发现了 LangChain 推出的 Deep Agents。这是一个专为长时间运行的复杂任务打造的开源智能体框架——开箱即用地解决了规划、上下文管理和多智能体编排的问题。搭了几个周末之后，以下是我的心得体会。
Deep Agents 到底提供了什么？
Deep Agents 可不是又一层普通的智能体封装。它是一个框架，包含三个核心原语，正好解决了我遇到的那些痛点：
- 规划工具：让智能体可以拆解任务、追踪进度，并根据新获取的信息动态调整
- 子智能体：可以为独立的子任务生成子智能体，且各自拥有隔离的上下文
- 虚拟文件系统：用于跨会话持久化存储知识、系统提示词、技能和长期记忆
上下文管理这块是它真正的杀手锏。该框架内置了中间件，可以压缩对话历史、转存庞大的工具返回结果、通过子智能体隔离上下文，并利用提示词缓存来降低延迟和成本。对于长时间运行的任务来说，有没有这套机制，直接决定了你的智能体是能稳定跑完，还是半路撞上上下文限制而崩溃。
第一步：安装
我选了 uv，因为我喜欢隔离的项目环境，不过用 pip 也完全没问题：
# 使用 uv
uv init
uv add deepagents tavily-python
uv sync
# 或者使用 pip
pip install deepagents tavily-python
搭建研究智能体需要一个搜索提供方。官方文档默认用的是 Tavily，但你也可以换成 DuckDuckGo、SerpAPI 或 Brave Search。我还是坚持用了 Tavily，因为它是专为智能体场景设计的，返回的结果更干净。
第二步：配置 API Keys
Deep Agents 是模型无关的——它支持任何支持工具调用的 LangChain 聊天模型。我用的是 Anthropic 的 Claude，但你也可以用 Google Gemini、OpenAI、OpenRouter、Fireworks、Baseten，甚至用 Ollama 跑本地推理。
export ANTHROPIC_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"
有一点让我踩了坑：模型必须支持工具调用。我一开始试着通过 Ollama 指向一个不支持函数调用的旧本地模型，结果智能体直接“静默失败”，什么工具都没调用。在开始抓耳挠腮 debug 之前，一定要先确认你的模型支持哪些能力。
第三步：创建搜索工具
这一步我们来接入搜索能力。Tavily 的集成非常直接：
import os
from typing import List
from langchain_community.tools.tavily_search import TavilySearchResults
def create_search_tool():
"""使用 Tavily 创建网络搜索工具。"""
search = TavilySearchResults(
max_results=5,
tavily_api_key=os.environ["TAVILY_API_KEY"],
)
return search
search_tool = create_search_tool()
如果你想用其他搜索提供方，只需要把它封装成 Deep Agents 能调用的工具接口就行。关键在于，你创建的任何工具，返回的结果必须是结构化的，这样智能体才能解析。
第四步：构建研究智能体
接下来是重头戏。Deep Agents 提供了一个 create_deep_agent 函数，把规划、文件系统和子智能体的能力都串联了起来：
from deepagents import create_deep_agent
# 创建具备研究能力的深度智能体
agent = create_deep_agent(
tools=[search_tool],
prompt="""你是一个严谨的研究智能体。当接到一个研究主题时：
1. 使用规划工具将主题拆解为若干子问题
2. 系统地研究每一个子问题
3. 随时将研究发现存入虚拟文件系统
4. 将所有发现综合成一份连贯的报告
5. 将最终报告写入文件系统
务必使用计划来追踪进度。当你发现新信息或需要调整策略时，请更新计划。""",
)
# 让智能体执行研究任务
result = agent.invoke({
"messages": [{"role": "user", "content": "研究量子计算的现状，并撰写一份2000字的报告，涵盖硬件路线、关键里程碑和近期应用。"}]
})
我第一次跑这段代码时，它和基础 ReAct 智能体的行为差异让我挺惊讶的。它没有一上来就跳去搜索，而是先用子问题创建了一个计划。然后它逐个解决，把中间结果存在虚拟文件系统里。当它发现某条信息改变了之前的理解时，还会回过头去更新计划。
第五步：了解底层到底发生了什么
我来拆解一下运行这个智能体时到底发生了什么，因为搞懂这个流程能在出问题时帮你大忙。
规划阶段： 智能体接收任务，并使用规划工具进行拆解。以我那个量子计算的例子来说，它拆分出了类似“目前主流的量子计算硬件路线有哪些？”、“2024年取得了哪些里程碑进展？”以及“目前正在探索哪些近期应用？”这样的子问题。
研究阶段： 针对每个子问题，智能体会进行搜索、阅读结果，并将摘要存入虚拟文件系统。这时候上下文管理中间件就派上用场了——庞大的搜索结果会被转存出去，不会吃掉你的上下文窗口。
生成子智能体： 遇到真正独立的子任务时，智能体会生成子智能体。每个子智能体都有自己独立的上下文，这意味着它们可以并行工作，而不会互相踩踏研究成果。这正是解决我那个多国监管对比需求的杀手锏——智能体分别为欧盟、美国和中国的研究生成了独立的子智能体。
综合阶段： 最后，智能体会读回所有存储的研究结果，将它们综合成一份连贯的报告，并写入文件系统。
实际效果与意外发现
我跑了那个量子计算的研究任务，输出结果确实令人惊艳。报告结构清晰，涵盖了智能体计划的所有角度，最重要的是——内部逻辑自洽。再也没有前后打脸的情况了。
但过程中也有一些意外：
意外 #1：智能体有时会过度规划。 在处理简单任务时，它依然会搞出一套复杂的计划，其实直接干反而更快。我后来学聪明了，会在提示词里告诉它“只有在任务包含多个不同子问题时才进行规划”。
意外 #2：子智能体的上下文隔离是把双刃剑。 当子智能体在隔离环境中工作时，它们无法实时共享发现。如果子智能体 A 找到了会改变子智能体 B 策略的信息，在研究过程中是没有机制传递的。智能体只能在综合阶段处理这种情况，但这意味着可能会做一些重复劳动。
意外 #3：成本积少成多。 带有规划、多次搜索调用和子智能体生成的长时间运行智能体，烧 token 的速度很快。我那个量子计算研究任务，用 Claude 跑大概花了 0.85 美元。作为一次性的任务这还算合理，但如果你要在生产环境中大规模跑，千万要注意成本。
使用命令行工具（CLI）
有个我没料到的点是，Deep Agents 还自带了 CLI。如果你只是想从终端跑个智能体，不想写 Python 代码：
deepagents run "Research the environmental impact of lithium mining"
用来做快速任务或测试还挺方便的，但如果要上生产环境，你肯定还是得用 SDK，这样才能更好地控制工具、提示词和配置。
实用建议
跟 Deep Agents 打了几个星期的交道后，这是我的一些建议：
在提示词里明确说明什么时候该做规划。 没有引导的话，智能体会对所有事情都做规划。告诉它：“包含3个及以上不同子问题的任务才做规划；简单问题直接处理。”
积极使用文件系统。 鼓励智能体存储中间结果。这正是让长时间运行的任务不至于上下文溢出的关键。
设置最大迭代次数。 不设上限的话，一个死磕到底的智能体可能会循环非常久。根据任务复杂度设一个合理的上限。
检查模型的工具调用支持。 这是最常见的静默失败原因。如果你的模型不支持工具调用，智能体就会……不用工具，然后给你一堆垃圾输出。
用 LangSmith 监控。 Deep Agents 原生集成了 LangSmith 做链路追踪。从一开始就打开它——没有追踪记录去 debug 一个长链路的智能体运行，简直是噩梦。
实事求是看局限
Deep Agents 并不完美。它的规划可能比较死板——一旦智能体制定了计划，哪怕早期发现暗示换种方法更好，它也会一条道走到黑。子智能体模式处理独立任务很在行，但子任务之间有依赖关系时就捉襟见肘了。而虚拟文件系统虽然是上下文管理的核心，但也增加了复杂性，导致 debug 更困难。
对于简单任务——单一问题、短对话、简单的工具调用——用 Deep Agents 纯属杀鸡用牛刀。基础的 ReAct 智能体会更快、更便宜。Deep Agents 的闪光点在于，当你面对真正复杂、多步骤的工作，且需要随时间推移追踪进度时。
这个框架还比较新，我也碰到了一些小毛病。文档把理想情况写得很清楚，但一旦出问题，你就得去啃源码了。错误提示信息还有待改进，尤其是工具调用失败时的报错。
话虽如此，针对我面临的特定问题——需要规划、上下文管理和并行执行的长时间研究任务——Deep Agents 是我用过的第一个真正搞定这些问题的框架，不用我自己从头去搭这套基础设施。它不是什么银弹，但对于那些需要长时间干实事的智能体来说，这绝对是扎实的一步。