Deep Agents框架详解：如何构建企业级LLM智能体？

在大模型应用快速发展的今天，单纯的对话交互已无法满足复杂业务需求，具备自主规划、多步骤执行、长期记忆的智能体（Agent） 成为新的技术趋势。本文将详细介绍 Deep Agents 框架，帮助开发者快速上手构建企业级、高可用的 LLM 智能体应用。

一、Deep Agents 是什么？

Deep Agents 是一款开箱即用的 LLM 智能体开发库，基于 LangChain 核心能力构建，依托 LangGraph 运行时提供稳定执行、流式输出、人机协同等特性。

官方将其定位为 Agent Harness（智能体 “harness”）：

• 保留主流智能体框架的工具调用循环核心逻辑 (Retains the core logic of the tool-calling loop from mainstream agent frameworks)
• 内置规划、文件系统、子智能体、长期记忆等能力 (Features built-in capabilities for planning, file systems, sub-agents, long-term memory, etc.)
• 无需从零搭建 Agent 架构，大幅降低开发门槛 (Eliminates the need to build an Agent architecture from scratch, significantly lowering the development barrier)

简单来说：Deep Agents = 开箱即用的智能体脚手架 + LangChain 核心 + LangGraph 运行时。

二、核心定位与技术栈

Deep Agents 并非重复造轮子，而是在成熟生态之上做上层封装与能力增强：

• LangChain：提供智能体底层基础组件 (Provides the foundational components for agents)
• LangGraph：负责持久化执行、流式响应、人机介入等运行时能力 (Handles runtime capabilities such as persistent execution, streaming responses, and human-in-the-loop intervention)
• Deep Agents：在二者之上封装成独立、易用的智能体开发库 (Encapsulates the above two into an independent, easy-to-use agent development library)

三者关系清晰：

• LangChain：基础框架 (Foundation Framework)
• LangGraph：运行时 (Runtime)
• Deep Agents：上层智能体 harness（一站式开发套件） (Upper-layer Agent Harness (All-in-one Development Kit))

三、快速上手：1 分钟创建你的第一个 Deep Agent

1. 安装依赖

pip install -qU deepagents

2. 最简示例：带工具的智能体

from deepagents import create_deep_agent

# 自定义工具 (Custom Tool)
def get_weather(city: str) -> str:
    """获取指定城市天气 (Get the weather for a specified city)"""
    return f"It's always sunny in {city}!"

# 创建智能体 (Create the Agent)
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 执行调用 (Execute the Invocation)
agent.invoke({
    "messages": [{
        "role": "user", 
        "content": "what is the weather in sf"
    }]
})

3. 调试与追踪

配合 LangSmith 实现请求追踪、行为调试与效果评估：

• 设置环境变量 LANGSMITH_TRACING=true (Set the environment variable LANGSMITH_TRACING=true)
• 配置 LangSmith API Key即可可视化观测智能体执行链路。 (Configure the LangSmith API Key to visually observe the agent's execution chain.)

四、什么时候该用 Deep Agents？

1. 适合使用 Deep Agents SDK 的场景

• 需要处理复杂多步骤任务，具备任务规划与拆解能力 (Need to handle complex multi-step tasks with task planning and decomposition capabilities)
• 上下文量大，需要文件系统管理上下文，防止窗口溢出 (Large context volume, requiring file system management for context to prevent window overflow)
• 需要灵活切换存储后端：内存、本地磁盘、持久化存储、沙箱等 (Need flexible switching of storage backends: memory, local disk, persistent storage, sandbox, etc.)
• 希望主智能体派发任务给专用子智能体，实现上下文隔离 (Want the main agent to delegate tasks to specialized sub-agents for context isolation)
• 需要跨会话持久化记忆 (Require persistent memory across sessions)

2. 不适合的场景

• 简单智能体：优先使用 LangChain 原生 create_agent (Simple agents: Prefer using LangChain's native create_agent)
• 高度自定义工作流：可直接基于 LangGraph 从零搭建 (Highly customized workflows: Can build directly from scratch based on LangGraph)

3. Deep Agents CLI 使用场景

• 命令行内需要编码智能体辅助开发 (Need a coding agent within the command line to assist development)
• 支持交互式 / 非交互式运行 (Supports interactive / non-interactive execution)
• 可自定义技能与记忆，适配项目规范 (Customizable skills and memory to adapt to project specifications)
• 支持本地 / 沙箱环境执行代码 (Supports code execution in local / sandboxed environments)

五、Deep Agents 核心能力详解

1. 任务规划与拆解

内置 write_todos 工具，智能体可自动：

• 将复杂任务拆分为离散步骤 (Decompose complex tasks into discrete steps)
• 跟踪任务进度 (Track task progress)
• 根据新信息动态调整计划 (Dynamically adjust plans based on new information)

2. 上下文管理（文件系统工具）

提供类操作系统文件操作工具：

• ls, read_file, write_file, edit_file
• 将大上下文外置存储，避免上下文窗口溢出 (Store large contexts externally to avoid context window overflow)
• 支持变长工具结果的持久化读写 (Supports persistent read/write of variable-length tool results)

3. 可插拔文件系统后端

虚拟文件系统支持灵活切换后端：

• 内存状态 (In-memory state)
• 本地磁盘 (Local disk)
• LangGraph Store（跨线程持久化） (LangGraph Store (persistent across threads))
• 隔离沙箱（Modal、Daytona、Denno） (Isolated sandboxes (Modal, Daytona, Denno))
• 支持自定义后端与组合路由 (Supports custom backends and composite routing)

4. 子智能体生成（Subagent Spawning）

内置任务工具，支持：

• 主智能体派生子智能体处理专项任务 (The main agent spawns sub-agents to handle specialized tasks)
• 上下文隔离，避免主智能体上下文污染 (Context isolation to avoid polluting the main agent's context)
• 专注深度执行子任务 (Focus on deep execution of sub-tasks)

5. 长期记忆

依托 LangGraph Memory Store 实现：

• 跨线程、跨会话持久记忆 (Persistent memory across threads and sessions)
• 智能体可读取历史对话信息 (Agents can read historical conversation information)
• 适用于客服、助手、个人助理等场景 (Suitable for scenarios like customer service, assistants, personal aides)

六、官方学习路径

官方提供完整学习链路，快速落地项目：

1. SDK Quickstart：构建第一个智能体 (Build your first agent)
2. Customization：SDK 自定义配置 (SDK customization configuration)
3. Backends：文件系统后端选择与配置 (File system backend selection and configuration)
4. Sandboxes：隔离环境代码执行 (Isolated environment code execution)
5. CLI：命令行智能体使用 (Command-line agent usage)
6. Reference：API 参考文档 (API reference documentation)

七、总结

Deep Agents 是面向生产级智能体的轻量化框架，它在 LangChain + LangGraph 生态基础上，封装了任务规划、文件系统、子智能体、长期记忆等刚需能力，让开发者从繁琐的底层架构中解放，专注业务逻辑实现。

如果你正在开发：

• 多步骤自动化智能体 (Multi-step automated agents)
• 需要处理大量上下文的应用 (Applications that need to handle large amounts of context)
• 要做代码生成、数据分析、文档处理等复杂场景Deep Agents 会是非常高效的选择。 (Complex scenarios like code generation, data analysis, document processing, etc., Deep Agents would be a highly efficient choice.)

常见问题（FAQ）

Deep Agents 是什么？它和 LangChain 有什么区别？

Deep Agents 是一款基于 LangChain 和 LangGraph 构建的开箱即用 LLM 智能体开发库。它并非替代 LangChain，而是在其基础上进行上层封装，提供任务规划、文件系统管理等企业级智能体所需的高级功能，大幅降低开发门槛。

如何快速开始使用 Deep Agents 创建我的第一个智能体？

只需安装 deepagents 库，使用 create_deep_agent 函数并传入自定义工具和系统提示即可。官方示例展示了如何创建一个带天气查询工具的智能体，整个过程可在 1 分钟内完成。

在什么业务场景下应该选择使用 Deep Agents？

当您需要处理复杂的多步骤任务、构建具备自主规划和长期记忆的企业级智能体应用时，Deep Agents 是理想选择。它提供了现成的脚手架，特别适合需要高可用性和快速开发的场景。