# LangChain Deep Agents 解析：从 LangGraph 运行时到复杂任务编排

> Deep Agents 是基于 LangChain 和 LangGraph 构建的智能体编排框架，解决企业级复杂任务挑战。其核心特性包括虚拟文件系统、代码沙箱执行、通过中间件管理长上下文，以及支持并行处理的子智能体委派机制。

原文：/knowledge/crawler-93f3d840c1841dfb25ad3c9469cb04afcc56b0b399f497203a1b70707ebfcf7b

LangChain 生态中的 Deep Agents 代表了从单一工具调用向复杂多步规划、子智能体委派及文件系统上下文管理的范式转变。Deep Agents 是一个构建在 LangChain 核心构建块之上、利用 LangGraph 运行时进行持久化执行和流式处理的“智能体编排框架”（Agent Harness），旨在解决企业级复杂任务中上下文管理、并行处理和长期记忆的挑战。

## 核心架构：LangGraph 运行时与 SDK 的关系

Deep Agents 并非独立的框架，而是基于 LangChain 和 LangGraph 构建的高级抽象。它复用了 LangGraph 的底层能力，包括持久化执行（Durable Execution）、流式处理（Streaming）以及人机协同（Human-in-the-loop），但通过 `deepagents` 库提供了开箱即用的复杂任务处理能力。

在 LangGraph 基础层面，开发者需要手动定义状态图（StateGraph）、节点（Nodes）和条件边（Conditional Edges）来构建工作流。而在 Deep Agents 中，这种底层图构建被封装为 `create_deep_agent` 或 `create_agent` 函数。Deep Agents 利用 LangGraph 的 `checkpointer` 机制实现状态持久化，并利用其 `interrupts` 机制实现运行时干预，但将这些复杂逻辑隐藏在中间件（Middleware）层之下，使开发者能专注于业务逻辑而非图拓扑。

[来源1](https://docs.langchain.com/oss/python/deepagents/overview) · [来源2](https://docs.langchain.com/oss/python/langchain/agents) · [来源3](https://docs.langchain.com/oss/python/langgraph/workflows-agents)

## 执行环境：虚拟文件系统与代码执行

Deep Agents 引入了虚拟文件系统（Virtual Filesystem）和代码执行沙箱，使智能体能够像人类开发者一样在环境中“工作”。

### 虚拟文件系统

Deep Agents 提供可配置的虚拟文件系统，支持多种后端（如内存状态、本地磁盘、LangGraph Store）。智能体可以通过工具读取和写入文件，系统支持声明式的权限规则（Permissions），通过 Glob 模式控制智能体对特定路径的读写访问。这种机制允许父智能体为子智能体分配更狭窄的文件访问权限，实现隔离与安全控制。

### 代码执行

为了处理需要编程逻辑的任务，Deep Agents 支持两种代码执行模式：
1. **沙箱后端（Sandbox Backends）**：暴露 `execute` 工具，允许在隔离环境中运行 Shell 命令、安装依赖或调用 CLI 工具。适用于需要操作系统级交互的场景。
2. **解释器（Interpreters）**：在 QuickJS 运行时中运行 JavaScript 代码。适用于轻量级的数据处理、循环逻辑或程序化工具调用，但不提供 Shell 或文件系统访问。

这种分层执行环境使 Deep Agents 能够处理从简单查询到复杂代码生成的广泛任务。

[来源1](https://docs.langchain.com/oss/python/deepagents/overview)

## 上下文管理：中间件驱动的长期记忆

随着智能体运行时间的延长，上下文窗口会迅速填满。Deep Agents 通过中间件（Middleware）架构管理上下文，确保智能体在长运行任务中保持高效和准确。

### 核心中间件组件

*   **SummarizationMiddleware**：自动压缩对话历史和大型工具结果，防止上下文溢出。它将冗长的历史压缩为紧凑的摘要，保留关键信息。
*   **MemoryMiddleware**：从 `AGENTS.md` 等文件加载持久化指令和偏好设置。这些记忆在每次会话启动时加载，并可根据交互反馈更新，实现跨会话的知识保留。
*   **SkillsMiddleware**：采用渐进式披露（Progressive Disclosure）机制加载领域知识。智能体仅在任务需要时读取特定的 `SKILL.md` 文件，避免启动时加载过多无关信息，保持上下文紧凑。
*   **FilesystemMiddleware**：管理虚拟文件系统的访问，将文件操作整合到智能体的状态中。

### 上下文工程

Deep Agents 强调“上下文工程”，即通过结构化方式管理智能体的知识输入。通过将静态提示（如系统指令）与动态上下文（如对话历史）分离，并利用 Prompt Caching 技术，Deep Agents 能够优化推理成本并提高响应速度。

[来源1](https://docs.langchain.com/oss/python/langchain/agents) · [来源2](https://docs.langchain.com/oss/python/deepagents/overview)

## 子智能体（Subagents）与并行委派

Deep Agents 的核心优势在于其子智能体委派机制，允许主智能体将复杂任务分解并并行处理。

### 子智能体机制

*   **隔离上下文**：默认情况下，每个子智能体拥有独立的上下文窗口（`mode: "isolated"`），确保任务隔离。也可以配置为继承父智能体的完整历史（`mode: "fork"`）。
*   **并行执行**：主智能体可以同时创建多个子智能体，每个子智能体负责一个子任务。子智能体在隔离环境中运行，互不干扰。
*   **单一交接**：子智能体完成后，将最终报告返回给主智能体。这种“单一交接”模式简化了结果聚合，避免了多消息传递的复杂性。
*   **无状态消息**：子智能体是无状态的，不能向主智能体发送多条消息。这种设计提高了效率，将重型子任务压缩为紧凑结果。

### 任务规划

Deep Agents 支持可选的任务规划（Task Planning），主智能体可以生成待办事项列表（Todo List），并将任务分配给专门的子智能体。这种规划-委派-聚合的模式使 Deep Agents 能够处理需要多步骤协调的复杂工作流。

```python
from deepagents.middleware import SubAgentMiddleware

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    middleware=[
        SubAgentMiddleware(
            backend=backend,
            subagents=[
                {
                    "name": "researcher",
                    "description": "Searches and returns a structured summary.",
                    "system_prompt": "Use the search tool to research the question and summarize key points.",
                    "tools": [search],
                    "model": "anthropic:claude-sonnet-4-6",
                }
            ],
        ),
    ],
)
```


[来源1](https://docs.langchain.com/oss/python/deepagents/overview) · [来源2](https://docs.langchain.com/oss/python/langchain/agents)

## 部署模式：Managed vs SDK

Deep Agents 提供两种部署模式，适应不同的生产需求：

### Managed Deep Agents

*   **托管基础设施**：由 LangSmith 运行智能体编排、Agent Server、沙箱和调度器。
*   **零运维**：开发者无需管理基础设施，专注于智能体逻辑。
*   **适用场景**：快速原型验证、生产级复杂任务，且希望最小化运维负担的团队。

### Deep Agents SDK

*   **自托管**：开发者在自有进程或容器中运行智能体。
*   **高度灵活**：支持自定义后端（Backend）、存储（Store）和检查点器（Checkpointer）。
*   **Agent Server**：可运行自定义 Agent Server，实现更精细的运行时控制。
*   **适用场景**：需要完全控制运行时环境、集成内部系统或满足特定合规要求的场景。

两种模式共享相同的 `deepagents` 库和核心能力，开发者可以根据需求灵活选择。

[来源1](https://docs.langchain.com/oss/python/deepagents/overview)

## 人机协同与可观测性

### 运行时干预（Human-in-the-loop）

Deep Agents 集成 LangGraph 的 `interrupts` 机制，允许在关键决策点暂停智能体执行。通过 `interrupt_on` 参数，开发者可以指定在特定工具调用（如文件编辑、API 调用）前请求人工批准。这为高风险操作提供了安全层，支持人工干预、添加指导或修改工具输入。

### 流式处理与可观测性

*   **事件流（Event Streaming）**：Deep Agents 暴露类型化的事件流，包括消息、工具调用、值更新和子智能体任务。`stream.subagents` 允许监控每个子智能体的独立流。
*   **LangSmith 集成**：所有智能体运行均可通过 LangSmith 进行追踪、调试和评估。LangSmith Engine 可自动监控追踪数据，检测问题并提出修复建议。

这种可观测性使开发者能够深入理解智能体的决策过程，优化性能并排查错误。

[来源1](https://docs.langchain.com/oss/python/deepagents/overview) · [来源2](https://docs.langchain.com/oss/python/langchain/agents) · [来源3](https://docs.langchain.com/oss/python/langgraph/workflows-agents)
