Deep Agents介绍 - 技术栈

Deep Agents 介绍

Deep Agents 是一个 agent harness，它的核心机制和其他 Agent 框架完全一样------就是那个"调模型 → 模型请求工具 → 执行工具 → 结果塞回上下文 → 再调模型"的循环。虽然循环本身不新，但真实任务里光有一个裸循环是不够的------上下文会爆、工具结果会丢、长任务会迷路、危险操作没人拦。Deep Agents 把这些工程问题提前解决了，做成内置能力，而不是让每个使用者自己搭。四个内置能力包括：执行环境（Execution environment）、上下文管理（Context management）、委派（Delegation）、操控（Steering）。

[一、执行环境（Execution environment）](#一、执行环境（Execution environment）)
- [1.1 Tools（工具）](#1.1 Tools（工具）)
- [1.2 Virtual filesystem（虚拟文件系统）](#1.2 Virtual filesystem（虚拟文件系统）)
- [1.3 Filesystem permissions（文件系统权限）](#1.3 Filesystem permissions（文件系统权限）)
- [1.4 Code execution（代码执行）](#1.4 Code execution（代码执行）)
[二、上下文管理（Context management）](#二、上下文管理（Context management）)
- [2.1 Skills（技能）](#2.1 Skills（技能）)
- [2.2 Memory（记忆）](#2.2 Memory（记忆）)
- [2.3 Summarization and context offloading（摘要和上下文卸载）](#2.3 Summarization and context offloading（摘要和上下文卸载）)
- [2.4 Prompt caching（提示缓存）](#2.4 Prompt caching（提示缓存）)
三、委派（Delegation）
- [3.1 任务规划（Task planning）](#3.1 任务规划（Task planning）)
- [3.2 子智能体（Subagents）](#3.2 子智能体（Subagents）)
四、操控（Steering）
- [4.1 人类介入（Human-in-the-loop）](#4.1 人类介入（Human-in-the-loop）)

一、执行环境（Execution environment）

执行环境是 Agent 运行的环境，让你能够通过类型化事件流，实时跟进正在发生的一切------包括消息、工具调用、值和委派任务。它有四层：

1.1 Tools（工具）

Tools（工具）是最外层，也是基础循环直接打交道的东西。它支持自定义函数、LangChain 工具，以及任何 MCP 服务器提供的工具。这一层不新鲜，就是"模型能调什么"的清单。具体分三种来源：自定义工具、LangChain 工具、MCP 工具。

1.2 Virtual filesystem（虚拟文件系统）

Virtual filesystem（虚拟文件系统）不是一个真实磁盘，而是可插拔后端：内存状态、本地磁盘、LangGraph store、复合路由，或带权限规则的自定义后端。暴露给模型的操作包括 ls、read_file、write_file、edit_file、delete、glob、grep，以及沙箱后端才有的 execute。关键设计是：文件系统是其他多个能力的基础设施------skills、memory、代码执行、上下文管理都建立在它之上。

1.3 Filesystem permissions（文件系统权限）

Filesystem permissions（文件系统权限）是声明式访问控制。规则按声明顺序求值，首次匹配即生效，无匹配则默认允许。每条规则包含 operations（读/写）、paths（用于匹配文件或目录的 Glob 模式）、mode（allow/deny）。这让你能把 Agent 限制在 /workspace/ 内、保护 .env 或凭据文件、给子 Agent 比父 Agent 更窄的权限。一个重要的边界说明：权限不适用于沙箱后端，因为沙箱支持任意命令执行------权限管的是文件工具，管不住 shell 里的 cat。

1.4 Code execution（代码执行）

Code execution（代码执行）分两条路径，对应两种不同需求：沙箱后端提供 execute 工具跑 shell 命令，适合装依赖、跑测试、调 CLI、操作真实文件系统；解释器提供 eval 工具在 QuickJS 运行时里跑 JavaScript，适合循环、批处理、确定性数据转换、程序化工具调用，但没有 shell、不能装包、无文件系统和网络访问。选型逻辑很清晰：需要真实系统能力用沙箱，只需要轻量编程层用解释器。

二、上下文管理（Context management）

上下文管理（Context management）控制 Agent 知道什么、它能在 token 限制内运行多久，以及它在不同会话之间保留什么。它包含四个层级：

2.1 Skills（技能）

技能为 Deep Agent 打包了专业的工作流、领域知识和自定义指令。

每个技能都遵循 Agent Skills 标准，存放在一个包含 SKILL.md 文件的目录中。技能还可以包含脚本、模板、参考文档和其他支持性资源。

Deep Agents 通过渐进式披露（progressive disclosure）来加载技能：智能体在启动时读取 SKILL.md 的头部元数据（frontmatter），只有当任务需要时，才读取完整的技能内容。这保持了启动上下文的紧凑，同时又能按需提供丰富的能力。

2.2 Memory（记忆）

记忆为 Deep Agent 提供了跨对话的持久化上下文，例如编码风格、偏好设置、约定规范和项目指南。

记忆使用 AGENTS.md 文件，创建智能体时通过 memory 参数传入。与技能不同，记忆文件总是被加载的，并且内容存储在配置的后端中（StateBackend、StoreBackend 或 FilesystemBackend）。

智能体还可以根据交互和反馈更新记忆，这样偏好和模式就能延续下去，无需在每个对话线程中重新说明。

2.3 Summarization and context offloading（摘要和上下文卸载）

Harness 负责管理上下文，以便 Deep Agent 能够在 token 限制内处理长时间运行的工作，同时将最相关的信息保持在视野范围内。这个上下文流转过程包含四个部分：

输入上下文：系统提示词、记忆、技能和工具提示词定义了智能体启动时所拥有的内容。
压缩：内置的卸载（offloading）和摘要（summarization）机制会压缩对话历史和大型中间结果。
隔离：子智能体（Subagents）将繁重的子任务隔离出去，只返回最终结果（见"委派"部分）。
长期记忆：虚拟文件系统中的持久化存储让信息能够跨线程传递。

这些机制共同支持了超出单个上下文窗口的多步任务，同时减少了手动修剪上下文的工作和 token 消耗。

2.4 Prompt caching（提示缓存）

对于 Anthropic 和 Amazon Bedrock 的模型，create_deep_agent 会自动对系统提示词中的静态部分（基础智能体指令、记忆和每轮重复的技能内容）应用提示词缓存。这避免了对相同 token 的跨调用重复处理，从而降低了长时间运行智能体的延迟和成本。当使用 Anthropic 模型，或 Bedrock 模型（Claude 或 Nova）时，提示词缓存默认启用。

三、委派（Delegation）

委派（Delegation）组件使智能体能够将大型问题拆解为更小、可并行处理的工作单元。它包含两个层级：

3.1 任务规划（Task planning）

任务规划是一项可选启用的 Harness 能力，让智能体在执行期间维护一个结构化的任务列表。规划通常对以下场景有用：

漫长或复杂的多步骤任务
能力较弱的模型，它们能从明确的问责/记账工具中获益
从智能体状态流式输出进度的 UI（见 Todo 列表）

将 TodoListMiddleware 传给 middleware 参数，即可为智能体提供一个 write_todos 工具，用于在执行期间维护结构化的任务列表。任务支持状态追踪（pending 待处理、in_progress 进行中、completed 已完成），并持久化在智能体状态中。这为智能体提供了一个轻量级的规划层，用于组织长时间运行和多步骤的工作。

3.2 子智能体（Subagents）

Harness 包含一个内置的 task 工具，允许主智能体为隔离的、长时间运行的、多步骤的或并行的任务创建临时的子智能体。可用的子智能体类型有两种：

同步子智能体（默认）会阻塞监督者，直到它们返回一份单一的报告。
异步子智能体 并行运行，并支持通过 launch（启动）、check（检查）、update（更新）和 cancel（取消）工具进行飞行中的中途操控。

子智能体执行提供以下特性：

隔离或继承的上下文 ：默认情况下，每次调用都会创建一个带有自己上下文的新智能体实例（mode: "isolated"）。使用 mode: "fork" 可以改为继承父级的完整对话历史。见 Forked subagents（分叉子智能体）。
自主执行：子智能体独立运行直至完成。
单一交接：它向主智能体返回一份最终报告。
可配置策略：使用默认的通用子智能体（默认启用），或定义自定义子智能体。
无状态消息：子智能体是无状态的，无法发回多条消息。
上下文与 token 效率：繁重的子任务工作保持隔离，并被压缩成一个紧凑的结果。

四、操控（Steering）

操控组件赋予了人类在运行时控制智能体行为的能力，并为智能体的工作设定文件系统权限。

4.1 人类介入（Human-in-the-loop）

Deep Agents 与 LangGraph 的中断（interrupts）机制集成，可以在敏感的工具调用前暂停流程，等待人工批准。通过在 create_deep_agent 中设置 interrupt_on 参数即可启用此行为。

interrupt_on 接受一个将工具名称映射到中断配置的字典。例如，interrupt_on={"edit_file": True} 会在每次编辑前暂停，允许你在执行前批准调用、添加指导或修改工具输入参数。这提供了一个运行时安全与控制层，适用于破坏性操作、昂贵的 API 调用以及交互式调试。