摘要

DeepAgents 是 LangChain 生态中用于构建 LLM 驱动智能代理的核心框架，提供任务规划、文件系统管理、子代理生成和长期记忆等能力。本文从快速创建代理的实操步骤入手，系统梳理 Backends、Subagents、Human-in-the-loop、Permissions、Memory、Skills、Sandboxes、Streaming、Profiles 九大核心功能模块，帮助开发者快速掌握 DeepAgents 的完整技术栈。

目录

• 1. DeepAgents 简介
• 2. 快速创建 DeepAgents
  • 2.1 创建一个工具
  • 2.2 创建一个 Deep Agent
  • 2.3 运行 Deep Agent
• 3. 核心功能
  • 3.1 Backends
  • 3.2 Subagents & Async Subagents
  • 3.3 Human-in-the-loop
  • 3.4 Permissions
  • 3.5 Memory
  • 3.6 Skills
  • 3.7 Sandboxes
  • 3.8 Streaming
  • 3.9 Profiles
• 4. 总结

---

1. DeepAgents介绍

1.1 什么是 DeepAgents？

DeepAgents 是 LangChain 生态中用于构建由大型语言模型（LLM）驱动的智能体和应用程序的最简单方法。它基于 LangGraph 框架构建，充分利用了图计算的思想来编排智能体的执行流程，让开发者能够以最少的代码量创建功能强大的 AI 代理。

与传统的 AI 应用开发方式不同，DeepAgents 将智能体视为一个自主决策系统——它不仅能理解用户的自然语言指令，还能自主规划任务、调用工具、管理上下文，并在执行过程中动态调整策略。这种设计理念使得 DeepAgents 特别适合构建复杂的多步骤自动化工作流。

1.2 核心设计思想

DeepAgents 的设计围绕以下几个核心理念展开：

• Agentic 架构：每个 DeepAgent 都是一个独立的智能体，拥有自己的 LLM 实例、工具集和记忆系统。它能够自主理解任务目标，制定执行计划，并在执行过程中根据反馈动态调整。
• 模块化与可组合：DeepAgents 采用高度模块化的设计，开发者可以像搭积木一样组合不同的后端、工具、记忆策略和权限控制，快速构建出满足特定需求的智能体。
• 生产就绪：内置了流式输出、沙箱安全执行、权限管理、人机协作等企业级特性，让智能体应用从原型到生产部署的路径更加平滑。

1.3 核心特性

DeepAgents 提供了丰富的内置功能，覆盖了智能体开发的各个关键环节：

• 任务规划：自动将复杂任务分解为可执行的子步骤，支持动态调整执行顺序
• 文件系统管理：内置虚拟文件系统，支持多种后端存储（本地文件系统、AWS S3、Google Cloud Storage 等）
• 子智能体生成：动态创建和管理子代理，实现任务并行处理与分工协作
• 长期记忆：支持短期（会话内）和长期（跨会话）记忆，让代理具备持续学习和知识积累能力
• 安全沙箱：在隔离环境中安全执行代码，支持 Docker 沙箱和本地沙箱两种模式
• 流式输出：实时查看代理的思考过程、工具调用和最终执行结果，提升调试体验
• 权限控制：细粒度的权限管理，支持对工具调用、文件访问、网络请求等进行精确控制
• 人机协作（Human-in-the-loop）：在关键决策点暂停执行，等待人工审核或输入，确保关键操作的安全性

1.4 典型应用场景

DeepAgents 的灵活性和强大能力使其适用于广泛的业务场景：

场景	说明	示例
自动化工作流	将多步骤业务流程自动化	数据采集→清洗→分析→报告生成
智能客服	构建能够理解上下文、调用知识库的对话机器人	产品咨询、故障排查、工单处理
代码开发助手	辅助开发者完成代码编写、调试和审查	自动生成单元测试、代码重构建议
数据分析	自动完成数据探索、可视化和洞察提取	CSV 数据分析、SQL 查询生成
内容创作	辅助完成文章撰写、翻译、摘要生成等任务	博客自动生成、多语言翻译
研究助手	帮助研究人员进行文献检索、信息整合	论文摘要提取、相关研究综述

1.5 架构概览

DeepAgents 的整体架构可以分为以下几个层次：

1. 用户交互层：通过 API 或 Web 界面与用户交互，接收任务指令并返回执行结果
2. 智能体核心层：包含 LLM 推理引擎、任务规划器、工具调度器和上下文管理器
3. 能力扩展层：包括工具集、技能库、记忆系统和子智能体管理器
4. 基础设施层：提供文件系统、沙箱环境、权限控制和流式传输等底层支持

这种分层架构使得 DeepAgents 既保持了核心的简洁性，又具备了强大的扩展能力。开发者可以根据实际需求，在任意层次上进行定制和扩展。

---

下面是 DeepAgents 分层架构的流程图：

2. 快速创建 DeepAgents

2.1 创建一个工具

工具是 Agent 与外部世界交互的桥梁。通过定义 Python 函数并添加类型注解和文档字符串，即可创建一个可被 Agent 调用的工具。以下示例使用 Tavily 搜索引擎创建一个网络搜索工具：

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"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

2.2 创建一个 Deep Agent

创建 Agent 时，需要指定底层模型、可用的工具集以及系统提示词。系统提示词定义了 Agent 的角色和行为准则：

research_instructions = "You are an expert researcher. Your job is to conduct thorough research and then write a polished report." 

agent = create_deep_agent(
    model="openai:gpt-5.4",
    tools=[internet_search],
    system_prompt=research_instructions,
)

2.3 运行 Deep Agent

通过 invoke 方法传入用户消息即可启动 Agent 执行。Agent 会自动规划任务、调用工具并生成最终回复：

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

# Print the agent's response
print(result["messages"][-1].content)

---

3. 核心功能

DeepAgents 提供了丰富的核心功能模块，下面逐一介绍各模块的核心能力与参考文档。

3.1 Backends

为 Agent 提供统一的虚拟文件系统抽象层，支持八种存储后端，开发者只需切换配置即可适配不同运行环境。所有后端遵循同一套 API 规范，切换后端只需修改配置参数，无需改动业务代码；支持文件的创建、读取、写入、删除、移动、复制以及目录遍历管理，部分后端还支持文件权限控制和元数据附加，大文件可进行分块流式读写避免内存溢出。典型场景包括本地开发调试时使用 LocalFileSystem 后端快速验证、云原生部署时使用 S3 或 GCS 后端实现弹性伸缩、多区域数据同步以及合规审计场景下的元数据追踪。

Deep Agents Backends：八种虚拟文件系统后端全解析

3.2 Subagents & Async Subagents

支持将复杂任务拆解为多个子代理并行或异步执行，每个子代理拥有独立的工具集和提示词，实现专业化分工与高效协同。主 Agent 自动分析任务结构并将子任务委派给专门的 Subagent 处理，每个 Subagent 拥有独立的对话历史和状态互不干扰，主 Agent 自动收集各 Subagent 的执行结果合并为统一输出；Async Subagents 还允许主 Agent 在等待子任务结果的同时继续处理其他逻辑。典型场景包括多源信息检索时同时创建多个 Subagent 分别检索数据库和搜索引擎并汇总报告、并行代码审查、多语言翻译任务以及复杂工作流编排。

Deep Agents：SubAgent 与 Async SubAgent 实战解析

3.3 Human-in-the-loop

在关键决策节点引入人工审核机制，Agent 执行敏感操作前暂停并等待人工确认，确保 AI 行为可控、安全。支持在工具调用、数据写入、外部请求等关键环节设置审批断点，可配置单人或多人审批以及审批超时和自动降级策略；审批时向审批人展示完整的决策上下文（包括 Agent 的推理过程、输入参数和预期影响），审批结果（批准/拒绝/修改参数）会反馈给 Agent 使其据此继续执行或调整策略。典型场景包括金融交易审批、内容审核发布、数据库写操作审批以及敏感数据访问的合规管控。

Deep Agents Human-in-the-loop：深度解析实现原理与实战指南

3.4 Permissions

构建企业级细粒度权限系统，基于 RBAC 模型精确控制 Agent 能调用的工具和操作的资源范围。支持定义管理员、操作员、只读用户等角色，可精确控制 Agent 能否调用某个具体工具以及工具内哪些参数可用，还能限制 Agent 只能操作特定路径、特定数据库表或特定 API 端点；每次工具调用时实时评估权限，支持基于上下文的条件授权。典型场景包括多租户 SaaS 平台的租户数据隔离、企业内部工具治理、分级运维以及临时授权机制。

Deep Agents Permissions：构建企业级安全可控的AI代理权限系统

3.5 Memory

同时支持短期记忆与长期记忆，短期记忆维护当前会话上下文，长期记忆实现跨会话的知识持久化与检索。短期记忆自动维护当前对话的上下文窗口，支持滑动窗口和摘要压缩两种策略；长期记忆将重要信息存储到外部数据库，跨会话可基于语义相似度检索相关记忆并按相关性排序，还支持手动或自动清理过期记忆避免记忆库膨胀。典型场景包括长期对话助手跨多天记住用户偏好、个性化推荐系统、知识管理助手以及多轮任务跟踪。

Deep Agents Memory：短期记忆与长期记忆的全面解析与实践指南

3.6 Skills

实现模块化技能设计，将工具、提示词和逻辑封装为独立技能，Agent 可根据任务需求动态加载和组合不同能力。支持技能注册与发现，Agent 运行时自动发现可用技能；支持动态技能加载，Agent 根据当前任务上下文自动判断需要激活哪些技能，避免加载无关能力；多个技能可以组合成复合技能，实现更复杂的工作流；每个技能支持版本控制，方便回滚和 A/B 测试。典型场景包括为金融、医疗、法律等不同领域预置技能包，Agent 按需加载对应领域的专业技能；第三方开发者可以开发独立技能插件，通过技能市场分发，用户按需安装；同一个 Agent 在客服场景下加载「订单查询」「退换货处理」技能，在营销场景下加载「用户画像分析」「活动策划」技能；Agent 在使用过程中不断学习新技能，技能库持续扩充，Agent 能力随之增长。

DeepAgents Skills：从模块化设计到实战应用

3.7 Sandboxes

提供安全的代码执行沙箱环境，Agent 可在隔离环境中执行多语言代码，避免对宿主系统造成影响。支持 Python、JavaScript、Java、Go 等多种编程语言的代码执行；对 CPU、内存、网络、文件系统进行严格隔离，防止恶意代码逃逸；自动检测代码执行超时和异常，优雅终止并返回错误信息；支持在沙箱内安装和管理第三方依赖包，满足不同代码的运行需求。典型场景包括 Agent 在沙箱中执行数据分析脚本，生成图表和统计结果，不污染宿主环境；Agent 生成的代码先放入沙箱执行验证，确保语法正确且无安全隐患后再交付；为不同用户提供隔离的代码执行环境，防止用户之间的代码相互干扰；Agent 在沙箱中运行测试用例，验证代码质量，测试环境与生产环境完全隔离。

Deep Agents Sandbox：从主流方案到企业级自定义实践技术全解析

3.8 Streaming

深入实现 LangChain 流式架构，支持逐 token 实时输出 Agent 的推理过程和最终结果，提升交互体验与可解释性。实时推送 LLM 生成的每个 token，用户无需等待完整响应即可看到内容；将 Agent 的推理步骤、工具调用过程和中间结果以流式方式展示，提升可解释性；基于事件流设计，支持对 Agent 执行过程中的各类事件（思考、工具调用、错误等）进行监听和处理；开发者可以注册自定义回调函数，在流式输出的各个阶段插入自定义逻辑。典型场景包括聊天机器人逐字显示回复内容，提升用户交互体验，减少等待焦虑；Agent 生成报告或文章时，用户可实时看到生成进度，随时中断或调整；开发者在调试 Agent 时，通过流式输出观察每一步的推理过程和工具调用结果，快速定位问题；在自动化工作流中，通过流式事件实时更新任务进度条和状态面板。

Deep Agents Streaming：深入理解 LangChain 流式架构与实战

3.9 Profiles

提供深度智能体配置文件体系，通过配置文件定义 Agent 的身份、偏好和行为约束，实现快速切换不同场景下的 Agent 行为。为 Agent 设定身份角色（如客服、数据分析师、代码审查员），影响其语言风格和决策倾向；配置 Agent 的行为边界，包括允许/禁止的操作、输出格式要求、安全策略等；定义 Agent 运行所需的模型参数、后端连接、工具列表等环境信息；支持 Profile 的继承机制，基础配置可被特定场景的配置覆盖，实现灵活复用。典型场景包括同一个 Agent 在不同对话中加载不同 Profile，上午作为「技术支持」处理工单，下午作为「内容编辑」撰写文章；开发环境、测试环境、生产环境使用不同的 Profile，避免配置混淆导致事故；为不同用户创建专属 Profile，记录用户的偏好设置和常用工具，提供个性化服务；在金融、医疗等强监管行业，通过 Profile 强制约束 Agent 的行为，确保符合行业规范。

Deep Agents Profiles：LangChain 深度智能体配置文件体系详解

4. 总结

回顾 DeepAgents 的设计，其核心价值不在于提供了多少功能模块，而在于对「智能代理系统」这一复杂命题做出了清晰的架构取舍。九大模块并非随意堆砌，而是围绕三个根本问题展开：Agent 如何感知与行动（Backends、Permissions、Sandboxes）、Agent 如何推理与记忆（Memory、Skills、Streaming）、Agent 如何协作与受控（Subagents、Human-in-the-loop、Profiles）。这种分层设计让开发者不必在每一层都重复造轮子，而是可以像搭积木一样按需组合。

值得深入思考的是，DeepAgents 的「智能」并非来自某个单一算法，而是来自系统级的编排能力。以 Human-in-the-loop 为例，它看似只是「加了个审批步骤」，实则解决了 AI 应用落地中最棘手的信任问题——当 Agent 自主决策时，关键节点的人工介入不是对效率的妥协，而是对责任的明确划分。同样，Sandboxes 模块表面上是安全隔离，深层意义在于它允许 Agent 执行任意代码而不污染宿主环境，这为 Agent 从「对话工具」进化为「执行引擎」扫清了障碍。

从实践角度看，DeepAgents 的模块化设计也暗含了性能与灵活性的权衡。例如，Memory 的短期/长期记忆分离，本质是在响应速度与上下文容量之间做取舍；Subagents 的并行处理能力虽好，但引入异步协调也增加了调试复杂度。开发者不应盲目堆砌所有功能，而应根据场景做减法：一个简单的问答 Agent 可能只需要 Backends + Skills，而一个自动化运维 Agent 则需要 Sandboxes + Permissions + Human-in-the-loop 的完整组合。

展望未来，Agent 框架的竞争将从「功能多少」转向「生态厚度」与「生产级稳定性」。DeepAgents 当前的设计已经为这种演进预留了空间——Profiles 模块让行为可配置，Skills 模块让能力可扩展，Streaming 模块让过程可观测。真正有挑战的，是如何在保持灵活性的同时降低心智负担，让开发者能像写普通函数一样自然地编排 Agent 行为。这或许是所有 Agent 框架下一阶段需要回答的问题。