Deep Agents

Deep Agents 是 LangChain 提供的开源 Python Agent harness。它没有发明另一套模型调用循环，而是在 LangChain 的 Agent 原语和 LangGraph 运行时之上，预装真实多步任务常用的执行、上下文、委派与人工控制能力。LangGraph 为它提供持久执行、流式事件与中断等运行时基础。

它是具体项目与库名，不是“更深度的 Agent”这一通用分类，因此本页按实体记录，也不自行创造中文译名。

Harness 结构

官方概览把 Deep Agents 的能力分成四组：

flowchart TB
    D["Deep Agents harness"] --> E["执行环境"]
    D --> C["上下文管理"]
    D --> G["委派"]
    D --> S["人工控制"]
    E --> E1["Tools / MCP"]
    E --> E2["虚拟文件系统与权限"]
    E --> E3["Sandbox / JavaScript interpreter"]
    C --> C1["Skills / Memory"]
    C --> C2["摘要与上下文卸载"]
    C --> C3["Prompt caching"]
    G --> G1["write_todos 任务规划"]
    G --> G2["task 子智能体"]
    S --> S1["interrupt_on 人工审批"]

这张结构图说明了 Harness Engineering（驾驭工程）与框架的边界：底层 tool-calling loop 只负责反复调用模型和工具；harness 还要决定工具在哪执行、状态放在哪里、上下文何时压缩、任务如何拆分，以及敏感动作何时暂停。

执行环境

工具与文件系统

应用可通过 tools= 传入普通 Python 函数、LangChain tool 或 Model Context Protocol（模型上下文协议）工具。内置虚拟文件系统向模型暴露一组稳定原语：ls、read_file、write_file、edit_file、delete、glob 和 grep；支持 shell 的 sandbox backend 还会增加 execute。

文件系统并不固定对应本机磁盘。backend 可以是单次运行的内存状态、LangGraph store、本地文件系统、按路径路由的组合存储，或自定义实现。因此同一套文件工具既能充当工作区，也能充当跨 thread 的持久介质。

文件权限使用声明式规则控制 read / write，按声明顺序采用 first-match-wins；没有规则命中时默认允许。这一点容易误配：单独写一条“允许 /workspace/**”不会自动拒绝其他路径，仍需后续拒绝规则。权限只约束内置文件工具，不约束能执行任意 shell 命令的 sandbox backend；后者必须依赖 Agent Sandbox（Agent 沙箱）自身的隔离与策略。

两种代码执行

Deep Agents 把代码执行分成两类：

方式	能做什么	不能做什么
Sandbox backend 的 `execute`	Shell、CLI、依赖安装、测试、操作系统文件	受具体 sandbox 隔离与生命周期约束
QuickJS interpreter 的 `eval`	循环、批处理、确定性转换、程序化工具调用	无 shell、包安装、文件系统和网络访问

这个区分把“需要完整计算环境”和“只需要一个轻量可编程控制层”分开，避免为了批量转换就给 Agent 过宽的系统权限。

上下文管理

Deep Agents 用四层机制把长任务控制在 token 限制内：

输入上下文：系统提示、memory、Skill 元数据与工具提示定义启动视野。
压缩：自动摘要对话历史，并把大体积工具结果卸载出活跃上下文。
隔离：Subagent（子智能体）在独立窗口处理高噪声子任务，只交回最终报告。
长期状态：虚拟文件系统让信息跨 thread 保存。

Agent Skills遵循开放的 Agent Skills 格式：启动时只读取 SKILL.md frontmatter，需要时才加载正文和支持文件。Agent Memory（Agent 记忆）则通过创建 Agent 时传入的 AGENTS.md 提供长期指令与偏好；它与 Skill 的区别是始终加载，并且 Agent 可以根据交互和反馈更新它。

对于 Anthropic 和 Amazon Bedrock 的 Claude / Nova 模型，create_deep_agent 默认把基础指令、memory 和 Skill 内容等静态 prompt 区段纳入提示缓存，减少长任务中重复处理相同前缀的延迟与成本。其他 provider 是否支持，需要由对应中间件决定，不能把这项默认行为泛化到所有模型。

规划与委派

write_todos 提供轻量任务规划，todo 状态为 pending、in_progress 或 completed，并保存在 Agent state 中。它适合维护多步任务的操作进度，但不等于执行恢复；崩溃后能否从正确节点续跑仍取决于 LangGraph 的 durable execution 配置。

task 工具让主 Agent 启动临时子智能体。每次调用都会获得新上下文，自主运行到结束，只返回一份最终报告；它不支持与主 Agent 多轮往返，因此是无状态、单次 handoff。默认提供 general-purpose 子智能体，也可以定义专项角色。高噪声过程留在子上下文确实能减少主线程 token，但不会消除子任务本身的推理成本。

事件流不仅能观察主 Agent 的消息、工具调用与状态，也为每个委派任务提供独立 handle，可继续查看该子智能体的消息、工具调用和嵌套委派流。这让上下文隔离不等于可观测性丢失。

人在回路中的控制

create_deep_agent(..., interrupt_on=...) 可在指定工具执行前触发 LangGraph interrupt。例如 interrupt_on={"edit_file": True} 会在每次编辑前暂停，人可以批准、补充指导或修改工具参数。

这是一层运行时动作 gate，适合破坏性操作、昂贵 API 和交互式调试。它与文件权限互补：权限定义某类动作能否执行，interrupt 决定一次具体动作是否需要人在当下确认。

定位与取舍

如果只需要自定义工具和基础 Agent loop，可直接使用 LangChain create_agent；如果需要完全自定义状态图和工作流，可直接构建 LangGraph。Deep Agents 的价值在于把常见 harness 能力组合成默认栈，减少自行拼装的工作。

代价是默认能力之间存在耦合：文件系统同时服务 Skill、memory、代码执行和上下文卸载；通用子智能体也会继承主 Agent 的部分文件系统配置。修改默认中间件或隐藏工具时，需要理解整套栈，而不能把每个组件当成完全独立的插件。