Deep Agents：面向复杂任务的智能体执行框架

先看它是什么

Deep Agents 可以理解为一套“已经配好基础能力的智能体执行框架（Agent Harness）”，而不是一个更大的聊天模型。

普通 Agent 往往只有模型、提示词和几个工具；复杂任务真正缺的是一整套能持续工作的外围系统：

• Agent 要能在环境里读写文件、调用工具和执行代码。
• Agent 要能在任务变长后管理上下文，而不是把所有历史一直塞回模型。
• Agent 要能把独立工作拆给子 Agent，隔离上下文并汇总结果。
• Agent 要能在高风险节点暂停，等人确认后再继续。

Deep Agents 的价值，就是把这些能力放到同一个运行模型里，让 Agent 从“会回答”变成“能把事情做完”。

一句话速记

Deep Agents = Agent Loop + 执行环境 + 上下文管理 + 子 Agent 委派 + 人工介入。

先统一几个叫法

很多概念直接看英文容易显得抽象，统一采用下面的说法：

原词	翻译	实际含义
Agent Harness	智能体执行框架	把模型、工具、上下文、权限和运行控制组织起来
Backend	文件系统后端	决定 Agent 的文件存在哪里、能保存多久
Steering	运行控制	在关键节点暂停、审批、纠偏和继续
Subagent	子智能体	在独立上下文里处理一个边界清晰的子任务
Context offloading	上下文卸载	把大结果存到外部，只把索引和结论留给模型
Human-in-the-loop	人工介入	高风险动作执行前，把决定交给人

核心问题

Deep Agents 的核心能力可以归纳为六个动作：

能力	主要作用	解决的问题
在环境中行动	调工具、读写文件、执行代码	让 Agent 能够操作外部环境
连接领域数据	按需加载 Skills、Memory 和检索结果	为当前任务补充领域资料
管理增长中的上下文	摘要、卸载大结果、隔离子任务	避免长任务挤满上下文窗口
并行推进	把独立工作委派给不同子 Agent	让相互独立的任务可以同时推进
保持人在回路	在关键动作前暂停并请求确认	把高风险决策留给人
持续改进	根据反馈更新记忆、Skills 和提示词	把运行经验沉淀为可复用的能力和规则

这六点不是孤立功能，而是一条完整的执行链：Agent 先确定任务，再通过环境行动；过程中按需补充上下文，必要时进行委派；遇到风险则暂停执行，等待人工确认。

整体结构

底层关系可以这样记：

• LangChain 提供模型、工具和 Middleware 等基础构件。
• LangGraph 提供持久执行、状态、流式和人工介入所需的运行时。
• Deep Agents 把这些构件装进一套更适合复杂任务的 Harness。

Deep Agents 的运行链路与四类支撑能力

所以它不是要替代 LangChain 或 LangGraph，而是把常见的 Agent 工程能力提前组合好。

最小运行示例

实际落地时，可以先用查询场景跑通最小闭环，确认模型调用、工具执行和结果返回都稳定后，再逐步接入文件系统、记忆和子 Agent。

下面只保留调用结构，实际使用时把 model 替换成当前 Provider 支持的写法。

from deepagents import create_deep_agent


def query_order(order_no: str) -> str:
    """查询订单的当前状态。"""
    return f"订单 {order_no}：运输中，最近节点为上海分拨中心"


agent = create_deep_agent(
    model="provider:model",
    tools=[query_order],
    system_prompt="你是企业订单助手。先查询事实，再给出处理建议。",
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "查询订单 SO20261004001，并判断是否需要人工跟进",
            }
        ]
    }
)

这个例子只验证三件事：

1. 模型能否正常初始化。
2. Agent 能否识别并调用工具。
3. 工具结果能否回到对话上下文并形成最终回答。

这三步稳定后，再继续接入文件系统、Skills、权限和子 Agent。否则一上来堆很多能力，问题出现时很难判断是哪一层出了错。

四层核心能力

1. 执行环境：智能体在哪里动手

执行环境是 Agent 和真实世界之间的边界，可以拆成五部分：

• 工具（Tools）：自定义函数、API、数据库和 MCP Server。
• 虚拟文件系统（Virtual filesystem）：统一的文件读写接口，后端可以是内存、磁盘、Store 或自定义实现。
• 权限（Permissions）：用路径和操作规则限制哪些文件能读、能写。
• 代码执行（Code execution）：Sandbox 负责 Shell 和操作系统级任务，Interpreter 负责受限的轻量程序逻辑。
• 流式输出（Streaming）：持续输出消息、工具调用、状态和子 Agent 事件。

这里最容易混淆的是文件系统、Sandbox 和 Interpreter：

能力	适用场景	能力边界
虚拟文件系统	保存上下文、读写任务文件	不等于任意 Shell
Sandbox	安装依赖、运行测试、调用 CLI	不应绕过权限和资源限制
Interpreter	循环、批处理、确定性转换	不提供包安装、网络和系统文件访问

更稳妥的接入顺序是：先定义工具，再决定文件后端；需要执行系统命令时才引入 Sandbox；只做数据变换时优先考虑 Interpreter。

2. 上下文管理：Agent 知道什么

上下文管理的重点不是尽量扩大上下文窗口，而是让合适的信息在合适的时机出现。

• 技能（Skills）：按需加载的领域知识、流程、脚本和模板，采用渐进式披露。
• 记忆（Memory）：启动时就加载的稳定偏好、项目约定和长期规则。
• 检索（Retrieval）：任务进行中按需找回外部资料。
• 摘要（Summarization）：历史过长时压缩成更小的工作上下文。
• 上下文卸载（Context offloading）：把大结果放到文件或后端，主上下文只保留索引和结论。
• 提示词缓存（Prompt caching）：缓存重复出现的静态提示、记忆和技能内容，减少重复推理成本。

Skills 和 Memory 应分开治理：Skills 是“需要时才加载的能力包”，Memory 是“每次启动都要遵守的稳定约定”。

3. 委派：Agent 如何拆工作

委派的重点不是让系统里 Agent 越多越好，而是隔离上下文和职责。

• 任务规划（Task planning）：先把大任务拆成可检查的步骤。
• 子智能体（Subagents）：把专业或沉重的子任务放到独立上下文中执行。
• 动态子智能体（Dynamic subagents）：根据任务在运行时决定要创建哪些专家。
• 异步子智能体（Async subagents）：把互不依赖的工作并行执行，再汇总结果。

同时满足以下条件时，再考虑进行委派：

1. 子任务边界清楚。
2. 子任务可以用较短的结果回传。
3. 隔离上下文能明显降低主 Agent 的负担。

如果只是把一句简单问题再转给一个子 Agent，通常只会增加延迟和成本。

4. 运行控制：在关键节点保留人工决策

运行控制（Steering）解决的是“Agent 可以做，但不应该无条件自己做”的问题。

适合设置人工介入的节点包括：

• 删除、覆盖、发布等不可逆操作。
• 修改权限、访问敏感数据或执行高风险命令。
• 多个方案都合理但需要业务判断的决策。
• Agent 无法确认意图，继续执行可能造成较大返工的节点。

人工介入应该落在明确的动作前，而不是等 Agent 已经做完以后再补救。恢复时要带上原任务状态、待确认动作和人的决定，避免重复执行。

业务中的典型场景

判断这套框架是否有价值，关键不在于概念是否完整，而在于能否解决真实业务问题。下面几类场景比较容易体现 Deep Agents 的作用：

业务场景	Agent 的任务	使用 Deep Agents 的原因
订单异常排查	查订单、运单、轨迹和接口日志，再给出处置建议	跨系统、多步骤，部分动作需要审批
企业知识助手	检索制度、合同、产品资料，整理依据并生成答复	资料量大，需要检索、引用和上下文压缩
研发助手	阅读仓库、修改代码、运行测试、总结变更	需要文件系统、命令执行和长任务恢复
数据分析助手	取数、清洗、计算、生成结论和图表	需要工具调用、代码执行和结果卸载
客服工单处理	判断问题类型、查业务数据、生成方案、必要时升级	需要路由、人工介入和操作审计

这些场景有一个共同点：最后的结果不是模型“想出来”的，而是 Agent 调用真实工具、拿到业务事实后做出的。

落地的重点检查项

关注点	检查内容
模型可用性	当前网络能否稳定访问，工具调用和结构化输出是否可靠
数据边界	敏感字段能否脱敏，业务数据是否允许离开内网
身份与权限	Agent 使用谁的身份，读写范围是否遵循最小权限
审批与审计	高风险动作是否先审批，整条工具调用链能否追踪
成本与性能	长上下文、并发子 Agent 和重复检索是否造成浪费
中文体验	业务术语、时间、金额、地址和错误提示是否符合使用习惯

企业落地不能只看 Demo

Demo 能回答，不代表系统能上线。企业场景通常还要同时解决内网访问、统一身份、数据脱敏、操作审计、模型稳定性和成本控制。

适用边界

适合的任务

• 需要多步规划和持续执行。
• 需要读写大量文件或操作代码仓库。
• 需要把工作拆给多个专业角色。
• 需要长时间运行、持久化、恢复和流式观察。
• 需要在关键节点加入人工审批。

不适合的任务

• 一次问答就能结束的任务。
• 只有一个模型调用和一个简单工具的流程。
• 所有步骤都固定、可预测、无需动态决策的工作流。

简单任务

先用普通的 Agent 创建方式，保持调用链短、状态少、调试简单。

复杂任务

再考虑 Deep Agents，把文件系统、上下文管理、子 Agent 和人工介入按需加进来。

强流程任务

如果每一步都必须严格按业务规则执行，可以直接设计 LangGraph 工作流，不必为了“像 Agent”而增加自主决策。

根据任务复杂度、执行跨度和风险边界选择合适的实现方式

工程实践要点

先小后大

先验证模型调用和一个工具，再加文件系统；先把单 Agent 跑稳，再引入子 Agent。每增加一层能力，都要有独立的验证方式。

权限先于执行

只要 Agent 能读写文件或执行命令，就先把路径、操作和资源边界定下来。权限不是上线前再补的安全配置，而是 Harness 的一部分。

子 Agent 用来隔离，不是用来装饰

如果子任务没有清晰输入和输出，就不要为了架构好看强行拆分。一个职责明确的主 Agent，通常比多个互相转发的 Agent 更容易稳定。

人工介入要有明确触发条件

“遇到不确定就问人”太宽泛。应该明确哪些动作必须暂停、需要展示哪些上下文、拒绝后如何恢复。

结果一定要外部验证

Agent 说“完成了”不等于任务完成。代码要跑测试，文档要检查链接和构建，数据修改要核对行数和幂等性，生产动作要保留审计记录。

最终速记

Deep Agents 不是“更聪明的模型”，而是一套让模型持续完成复杂工作的执行系统。

先管环境，再管上下文；需要并行时做委派，遇到风险时让人介入；每一步都保留可验证、可恢复、可追踪的边界。