LangChain Deep Agents：内置的规划、文件处理与子智能体功能。

那些认真对待智能体开发的团队往往都会走相同的路径。他们从 LangChain 的链结构开始，这类结构很适合处理简单的流程。但随着任务复杂度的提升，就需要进行工具调用、处理循环以及长度不固定的输出，此时链结构已无法满足需求，于是他们转向 LangGraph，甚至在着手解决实际问题之前就开始编写状态架构、条件边以及图编译代码。

LangGraph 本身并非问题所在，它的功能非常强大。但它只是一种运行时环境、低级原语，而人们却常常将其当作应用框架来使用。deepagents 正是 LangChain 为应对这种错位而推出的解决方案。

它是什么

“深度智能体”几乎可以指代任何事物，因此准确地说：deepagents 是一个独立的 Python 包，可通过 pip install deepagents 安装，它建立在 LangChain 和 LangGraph 之上。LangChain 的文档将其称为智能体框架。它与其他框架一样运行核心的工具调用循环，但内置了额外的功能，无需每次都重新实现。

入口函数是 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图结构、状态、流处理以及上下文窗口，而你无需亲自处理任何相关内容。更有趣的是它还附带了诸多功能。

五种内置功能

通过write_todos进行规划

每个深度智能体都会自动获得一个write_todos工具。面对复杂任务时，它会将工作分解为多个步骤，为每个步骤标记待处理、进行中或已完成状态，并根据情况变化调整计划。这并非提示词技巧——该列表存储在智能体状态中，因此智能体可以在整个会话期间随时返回查看、更新或引用它。无需有人告诉模型要逐步思考，因为这种结构早已内置于系统中。

虚拟文件系统

这或许是最令人惊讶的一点。默认情况下，该智能体具备 ls、read_file、write_file、edit_file、glob 和 grep 这些功能。智能体为何需要文件？是为了进行上下文管理。

上下文窗口的大小是有限的，长时间的研究、代码执行或大型工具的输出会迅速使历史记录膨胀。深度智能体会将大量内容存储到虚拟文件系统中，而非全部保留在提示词中。当某个工具的输出超过20,000个标记时，系统会将其保存到配置好的后端，并在上下文中留下文件路径以及10行的预览内容。当智能体需要完整内容时，它会调用 read_file 或 grep。这既不是分块处理，也不是截断处理，而是有意识地将数据卸载到外部存储，并按需检索。

文件系统后端是可插拔的：默认为内存存储，也可使用本地磁盘、LangGraph Store实现跨线程持久化，或是Modal和Daytona这样的沙箱环境。

子代理

内置的task工具允许主代理为独立的子任务创建专门的子代理。这一功能的重要性超出想象。在漫长的研究任务中，如果由一个代理处理所有事务，其上下文会充斥着中间步骤、搜索结果和部分输出。而通过子代理，主代理可以将子任务交给一个上下文清空的新的实例来处理。该实例独立工作、完成任务后仅返回一个总结，这样主代理的上下文就能保持整洁。

你可以定义带有自己工具和系统提示语的定制子代理。首先从导入开始：

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.",
)

一个具备文件系统工具的通用子代理随时可用，无需任何额外设置。

自动总结

对于耗时较长的任务，这就是该库发挥作用的地方。当上下文内容达到模型处理窗口的85％且没有内容可另存为文件时，该框架会触发总结功能。大型语言模型会生成一份结构化的总结，涵盖会话的意图、生成的成果以及后续步骤，这份总结会取代工作记忆中的完整历史记录。原始消息则作为标准记录保存在文件系统中，以便日后调取具体内容。实际上，这样的深度代理能够在不触及上下文限制的情况下持续处理复杂任务，而这在直接使用LangGraph时需要手动实现。

跨对话的记忆保持

通常情况下，状态会保留在单个线程中。不过，如果配置带有 LangGraph Store 的 CompositeBackend，智能体便能在不同会话和线程之间保留记忆。存储在 /memories/ 路径下或您指定的任何路径中的文件不会因重启而丢失，且可以从任何对话中读取。利用这一功能可以让智能体记住您的偏好、代码库的编码习惯，或是持续数天的研究工作之前的进展。首先进行导入：

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提供了基础构建模块：模型、工具、提示词以及任务链，它是整个系统的基础。
• LangGraph则是用于实现持久化、带状态的全图式执行的运行时环境，能够处理数据持久化、流式处理、中断以及复杂的条件逻辑，它是系统的引擎。
• Deep Agents则是基于这两者的上层框架。它并不取代LangGraph，而是利用LangGraph的所有功能，并添加了带有默认配置的高级API，这样你就无需自行构建规划器、文件系统层、上下文压缩机制以及子代理架构。

可以这样理解：LangGraph为你提供引擎和传动系统，而Deep Agents则为你提供了一辆完整的汽车。

对于简单的智能体，LangChain 的 create_agent 函数就已经足够用了。当任务较为复杂、需要长时间运行且涉及大量上下文时，deepagents 才能体现出其抽象层带来的优势。

实用的快速入门：研究型智能体

这是一个能够搜索网络并撰写结构化报告的研究型智能体。首先需要进行配置：

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)

运行它后会触发一系列操作。代理会调用write_todos来规划研究任务。它会执行搜索，并将大量搜索结果自动上传到虚拟文件系统中。如果任务量较大，它会为每个部分启动一个子代理。在需要时，它会读取相关文件并将所有内容整合成最终报告。在整个过程中，框架会管理上下文，确保模型不会超出其处理限制。这些基础设施并非你自行编写，因为它们是随框架一同提供的。

命令行代理

该软件包还包含一个基于相同SDK开发的终端代理：

pip install deepagents
deepagents  # launches the interactive CLI agent

它是一种类似 Claude Code 或 Aider 的编程助手，但运行在 Deep Agents SDK 上。它提供交互模式、用于脚本编写的非交互式管道模式（-n 参数）、自定义技能以及持久内存功能。你可以将项目规范教给它，这样它就能在多次会话之间记住这些规范。因此，用于驱动生产级研究助手的 SDK 同时也能立即为你提供实用的开发者工具。

何时使用它

deepagents 适合以下情况：

• 任务需要规划且包含多个步骤。
• 工具生成的输出量很大，需要在长时间会话中持续处理。
• 你想实现子助手分工，但又不想自行构建相关架构。
• 你需要能在不同对话线程之间保持内存的持续性。
• 你正在开发编程助手或自主研究系统。

在以下情况下，建议继续使用 create_agent 或纯 LangGraph：

• 智能体结构简单，仅包含一两次工具调用及简短回复。
• 需要对图结构进行精细控制。
• 已深度使用自定义的 LangGraph 工作流，不愿接受预设的默认设置。

文档本身也明确指出：简单的智能体适合使用更简单的工具。

为何这很重要

时间节点能反映问题所在。目前，基本的智能体模式、工具调用、ReAct 循环以及简单的 RAG 技术都已得到广泛理解。而该领域仍在探索的是那些需要长期规划、处理大规模上下文、具备持久性及任务分配能力的任务的可靠性问题。所有正在部署生产级智能体的团队都不得不从零开始解决这些相同的问题，而上下文管理策略、子智能体模式以及内存设计也不断以略有不同的形式被重新设计。

deepagents 是 LangChain 的一种尝试，旨在让这类解决方案变得足够普遍从而实现标准化。它通过预设的默认配置、内置的基础设施以及可插拔的后端，试图将问题焦点从“如何构建基础架构？”转变为“智能体实际上应该执行什么任务？”。其成败取决于这些默认设置能否在实际应用中持续有效。不过从发展方向来看，这一思路是合理的。

入门指南

请先安装该包以及搜索客户端：

pip install deepagents tavily-python

然后设置您的密钥：

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"

LangChain 文档中的 Deep Agents 概述涵盖了后端、子智能体、沙箱环境、人工干预机制以及命令行界面。如果您打算使用智能体构建重要的应用，不妨花点时间了解它如何融入您的技术架构，即便您不立即采用它也并无妨。