LangChain DeepAgents：构建长期任务智能体的开源框架

随着 AI 智能体技术的快速发展，Agent 任务长度正在呈指数级增长——根据 METR（Model Evaluation & Threat Research）的数据，智能体处理任务的平均长度每 7 个月就翻一番。面对这一趋势，LangChain 推出了 DeepAgents 框架，一个开源的、可扩展的智能体套件，专门用于处理长期复杂任务。

什么是 DeepAgents？

DeepAgents 是 LangChain 推出的一个轻量级但功能强大的智能体框架，它借鉴了 Claude Code、Manus 等成熟产品的核心设计理念，包括：

• 规划循环（Planning Loops）：在任务执行前进行详细规划
• 计算机访问：提供完整的文件系统和 Shell 访问能力
• 子智能体委托（Sub-agent Delegation）：将复杂任务分解并委托给专门的子智能体
• 人机协同（Human-in-the-loop）：支持关键操作的人工审批工作流

与 Claude Code 等商业产品不同，DeepAgents 完全开源，允许开发者自由扩展自定义工具和指令。

核心架构设计

1. 基于 LangGraph 的状态图

DeepAgents 使用 LangGraph 的 StateGraph 作为底层执行引擎，这意味着：

• 流式输出支持：可以实时查看智能体的思考过程
• 检查点机制：支持状态持久化和恢复
• 人机交互：内置 interrupt 能力，可在关键节点暂停等待人工反馈
• 内存管理：支持跨对话的长期记忆

from deepagents import create_deep_agent

agent = create_deep_agent(
    tools=[internet_search],
    system_prompt="Conduct research and write a polished report.",
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "What is LangGraph?"
    }]
})

2. 内置工具集

每个通过 create_deep_agent 创建的智能体都自带一套标准工具：

3. 可插拔后端系统

DeepAgents 支持多种文件系统后端，灵活控制文件操作的持久化方式：

• StateBackend（默认）：文件存储在智能体的临时状态中
• FilesystemBackend：真实的磁盘操作，指定根目录
• StoreBackend：使用 LangGraph Store 持久化存储
• CompositeBackend：混合路由，不同路径使用不同后端

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/path/to/project"),
)

核心特性解析

特性一：规划循环（Planning Loops）

长期任务的成功关键在于"想清楚再动手"。DeepAgents 的规划循环机制包括：

1. 任务分解：将复杂任务拆分为可执行的子任务
2. 优先级排序：根据依赖关系和重要性安排执行顺序
3. 动态调整：根据执行结果实时调整计划
4. 进度跟踪：通过 TODO 列表可视化任务进度

最佳实践：

• ✅ 在 system_prompt 中定义领域特定的工作流程（如研究方法论、数据分析步骤）
• ✅ 提供具体示例说明任务的完成标准
• ✅ 明确停止条件和资源限制
• ✅ 解释工具在工作流中如何协作

research_instructions = """
你是专业的研究助手，工作流程如下：
1. 使用搜索工具收集信息
2. 批量处理相似的研究任务
3. 验证信息来源的可靠性
4. 撰写结构化报告

停止条件：
- 收集到至少 5 个可靠来源
- 报告篇幅达到 2000 字
- 或用户主动停止
"""

agent = create_deep_agent(
    system_prompt=research_instructions,
    tools=[internet_search]
)

特性二：子智能体委托（Sub-agent Delegation）

当面对复杂的多领域任务时，单一智能体往往难以胜任。DeepAgents 支持将任务委托给专门的子智能体：

优势：

• 上下文隔离：每个子智能体拥有独立的上下文，避免干扰
• 专业化指令：为不同任务定制专门的系统提示词
• 灵活配置：可选择不同的模型和工具集

research_subagent = {
    "name": "research-agent",
    "description": "用于深入研究问题的专家研究员",
    "system_prompt": "你是专业的研究员，擅长信息收集和分析",
    "tools": [internet_search],
    "model": "openai:gpt-4o"  # 可选，默认使用主智能体模型
}

agent = create_deep_agent(
    subagents=[research_subagent]
)

高级用法：对于更复杂的场景，可以直接传入预编译的 LangGraph 图：

from deepagents import CompiledSubAgent

custom_graph = create_agent(
    model=...,
    tools=...,
    system_prompt=...
)

agent = create_deep_agent(
    subagents=[CompiledSubAgent(
        name="data-analyzer",
        description="专门的数据分析智能体",
        runnable=custom_graph
    )]
)

特性三：人机协同（Human-in-the-loop）

某些敏感操作（如文件删除、API 调用）可能需要人工审批。DeepAgents 通过 LangGraph 的 interrupt 能力实现 HITL 工作流：

from deepagents import create_deep_agent

@tool
def get_weather(city: str) -> str:
    """获取城市的天气信息"""
    return f"{city}的天气是晴天"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-20250514",
    tools=[get_weather],
    interrupt_on={
        "get_weather": {
            "allowed_decisions": ["approve", "edit", "reject"]
        }
    }
)

配置选项：

• approve：直接批准执行
• edit：修改参数后执行
• reject：拒绝执行

特性四：长期记忆（Long-term Memory）

DeepAgents 支持跨对话的持久化记忆，通过 CompositeBackend 路由特定路径到持久化存储：

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # 默认临时存储
        routes={
            "/memories/": StoreBackend(store=InMemoryStore())  # 持久化存储
        }
    )
)

使用场景：

• 保存用户偏好设置
• 构建跨对话的知识库
• 基于反馈自我改进指令
• 维护研究进度

实战案例：构建研究助手

让我们通过一个完整的例子，展示如何使用 DeepAgents 构建一个能够进行深度研究的智能体。

步骤 1：安装依赖

pip install deepagents tavily-python

步骤 2：配置环境变量

export TAVILY_API_KEY="your-tavily-api-key"

步骤 3：创建智能体

import os
from deepagents import create_deep_agent
from tavily import TavilyClient

# 初始化搜索工具
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(query: str, max_results: int = 5):
    """运行网络搜索"""
    return tavily_client.search(query, max_results=max_results)

# 定义研究工作流程
research_instructions = """
你是一个专业的研究助手，任务流程如下：

## 研究方法论
1. **信息收集**：使用搜索工具收集至少 5 个可靠来源
2. **交叉验证**：对比不同来源的信息，识别一致性
3. **深度分析**：提取关键洞察和数据支撑
4. **结构化输出**：撰写包含以下部分的报告：
   - 执行摘要
   - 背景介绍
   - 核心发现
   - 数据支撑
   - 结论和建议

## 质量标准
- 信息来源必须权威可靠
- 数据必须注明出处
- 避免主观臆断，基于事实分析
- 报告篇幅 2000-3000 字

## 停止条件
- 收集到 5 个以上可靠来源
- 报告达到 2000 字
- 或用户主动要求停止
"""

# 创建智能体
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 执行任务
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "研究 LangChain DeepAgents 框架的核心特性和最佳实践"
    }]
})

print(result["messages"][-1].content)

与其他框架的对比

最佳实践建议

1. 系统提示词设计

应该做：

• ✅ 定义领域特定的工作流程
• ✅ 提供具体示例和完成标准
• ✅ 明确停止条件和资源限制
• ✅ 解释工具如何协作

避免做：

• ❌ 重复解释标准工具（中间件已覆盖）
• ❌ 与默认指令冲突
• ❌ 过于冗长，影响推理效率

2. 工具设计原则

• 单一职责：每个工具只做一件事
• 清晰描述：工具的描述要能让模型理解何时使用
• 错误处理：返回有用的错误信息
• 类型注解：使用 Python 类型提示提高可维护性

from langchain_core.tools import tool

@tool
def analyze_data(file_path: str) -> str:
    """
    分析 CSV 文件中的数据

    Args:
        file_path: CSV 文件的路径

    Returns:
        分析结果的 JSON 字符串，包含统计摘要和关键发现
    """
    # 实现细节...
    pass

3. 性能优化

• 批量操作：将相似任务合并处理
• 缓存结果：避免重复计算
• 流式输出：对于长时间任务，使用流式输出提升用户体验
• 错误重试：实现指数退避的重试机制

生态系统集成

MCP 工具集成

DeepAgents 可以通过 langchain-mcp-adapters 集成 MCP (Model Context Protocol) 工具：

from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agent

async def main():
    mcp_client = MultiServerMCPClient(...)
    mcp_tools = await mcp_client.get_tools()

    agent = create_deep_agent(tools=mcp_tools)

    async for chunk in agent.astream({
        "messages": [{
            "role": "user",
            "content": "..."
        }]
    }):
        chunk["messages"][-1].pretty_print()

CLI 工具

DeepAgents 还提供了命令行界面（CLI），支持交互式会话、技能管理和 HITL 工作流：

pip install deepagents-cli

# 启动交互式 CLI
deepagents-cli

应用场景

1. 自动化研究

收集和分析大量信息，生成结构化报告。

2. 代码审查

自动检查代码质量、安全漏洞和性能问题。

3. 数据分析

处理和分析数据集，生成可视化报告。

4. 内容创作

撰写博客文章、技术文档或营销文案。

5. 自动化测试

生成测试用例、执行测试并分析结果。

未来展望

随着 AI 智能体技术的持续演进，DeepAgents 框架也在不断迭代：

• 更强的规划能力：集成更先进的规划算法
• 多模态支持：处理图像、音频和视频
• 分布式执行：支持多机器并行处理
• 更好的可观测性：提供详细的执行日志和性能指标

总结

LangChain DeepAgents 为构建长期任务智能体提供了一个强大而灵活的开源解决方案。通过借鉴 Claude Code 等成熟产品的设计理念，并结合 LangGraph 的强大能力，DeepAgents 让开发者能够快速构建可靠、高效的 AI 智能体。

核心优势：

• 🚀 开箱即用：内置完整的工具集和最佳实践
• 🔧 高度可定制：灵活扩展工具和指令
• 🛡️ 生产就绪：支持持久化、错误处理和 HITL
• 🌐 生态友好：与 LangChain、MCP 等生态系统无缝集成

无论你是想构建自动化研究助手、代码审查工具，还是复杂的数据分析系统，DeepAgents 都值得你深入探索和尝试。

参考资源

• 官方文档：docs.langchain.com/oss/python/deepagents/overview
• GitHub 仓库：github.com/langchain-ai/deepagents
• 快速开始示例：github.com/langchain-ai/deepagents-quickstarts
• Claude Code 官方文档：code.claude.com/docs