约束框架是多种不同功能的组合编排，使构建长时间运行的智能体更加容易： 除了这些功能外，Deep Agents 还使用技能和记忆来提供额外的上下文和指令。

​
规划能力

约束框架提供了一个 write_todos 工具，智能体可以用它来维护结构化的任务列表。 特性：
  • 跟踪具有状态（'pending'、'in_progress'、'completed'）的多个任务
  • 在智能体状态中持久化
  • 帮助智能体组织复杂的多步骤工作任务
  • 对长时间运行的任务和规划很有用

​
虚拟文件系统访问

约束框架提供了一个可配置的虚拟文件系统，由不同的可插拔后端支撑。 后端支持以下文件系统操作：
工具描述
ls列出目录中的文件及其元数据（大小、修改时间）
read_file读取文件内容并显示行号，支持大文件的offset/limit读取。也支持为非文本文件（图像、视频、音频和文档）返回多模态内容块。支持的扩展名请参阅下面
write_file创建新文件
edit_file对文件执行精确的字符串替换（支持全局替换模式）
glob查找匹配模式的文件（例如 **/*.py）
grep搜索文件内容，支持多种输出模式（仅文件、带上下文的内容或计数）
execute在环境中运行 shell 命令（仅在沙盒后端下可用）
类型扩展名
图像.png、.jpg、.jpeg、.gif、.webp、.heic、.heif
视频.mp4、.mpeg、.mov、.avi、.flv、.mpg、.webm、.wmv、.3gpp
音频.wav、.mp3、.aiff、.aac、.ogg、.flac
文件.pdf、.ppt、.pptx
虚拟文件系统也被其他几个框架功能使用，如技能、记忆、代码执行和上下文管理。 在为 Deep Agents 构建自定义工具和中间件时，您也可以使用文件系统。 更多信息，请参阅后端。

​
文件系统权限

约束框架支持声明性权限规则，这些规则控制智能体可以读取或写入的文件和目录。权限适用于上面列出的内置文件系统工具，并按声明顺序评估适配，第一个适配到的规则生效。 工作原理：
  • 创建智能体时将规则列表传递给 permissions=
  • 每个规则指定 operations（"read"、"write"）、paths（glob 模式）和 mode（"allow" 或 "deny"）
  • 第一个匹配到的规则生效。如果没有匹配的规则，操作被允许。
为什么有用：
  • 将智能体限制在特定目录（例如 /workspace/）
  • 保护敏感文件（例如 .env、凭据）
  • 给子智能体比父智能体更窄的访问权限
权限不适用于沙盒后端，沙盒通过 execute 工具支持任意命令执行。对于自定义验证逻辑，请使用后端策略钩子。 有关完整的规则结构、示例和子智能体继承体系，请参阅权限。

​
子智能体任务委托

约束框架允许主智能体为隔离的多步骤任务创建临时”子智能体”。 为什么有用：
  • 上下文隔离 - 子智能体的工作不会使主智能体的上下文混乱
  • 并行执行 - 多个子智能体可以同时运行
  • 专门化 - 子智能体可以有不同的工具/配置
  • Token效率 - 大型子任务上下文被压缩成单个结果
工作原理：
  • 主智能体有一个 task 工具
  • 调用时，它会创建一个继承自己上下文的全新智能体实例
  • 子智能体自主执行直到任务完成
  • 向主智能体返回单个最终结果报告
  • 子智能体是无状态的（不能返回多条消息）
默认子智能体：
  • “general-perpose”通用子智能体自动可用
  • 默认具有文件系统工具
  • 可以添加额外的工具/中间件
自定义子智能体：
  • 定义具有特定工具的专门子智能体
  • 示例：代码审查员、web搜索器、测试运行器
  • 通过 subagents 参数配置

​
上下文管理

约束框架通过对上下文的管理，使deep agent能够在Token限制内处理长时间运行的任务，同时保留所需的信息。 工作原理：
  • 输入上下文 — 系统提示词、记忆、技能和工具提示词决定了智能体在启动时知道的内容
  • 压缩 — 内置的消息卸载和消息总结功能在任务运行时将上下文保持在窗口限额内
  • 隔离 — 子智能体隔离重型工作，仅仅只返回结果（请参阅任务委托）
  • 长期记忆 — 通过虚拟文件系统实现跨线程持久化存储
为什么有用：
  • 使得超出单个上下文窗口限额的多步骤任务能够实现
  • 在不需要手动修剪的情况下保持最相关的信息在窗口范围内
  • 通过自动消息总结和消息卸载减少Token使用
有关配置详情，请参阅上下文工程。

​
代码执行

当您使用沙盒后端时，约束框架会暴露一个 execute 工具，让智能体在隔离环境中运行 shell 命令。这使智能体能够在任务中进行安装依赖、运行脚本和执行代码。 工作原理：
  • 沙盒后端实现了 SandboxBackendProtocolV2 — 当被检测到后，约束框架将 execute 工具添加到智能体的可用工具中
  • 没有沙盒后端，智能体将只有文件系统工具（read_file、write_file 等），不能运行命令
  • execute 工具返回组合的 stdout/stderr输出流、返回码，并截断大输出（保存到文件供智能体逐步读取）
为什么有用：
  • 安全 — 代码在隔离环境中运行，保护您的主机系统免受智能体操作的影响
  • 干净的环境 — 使用特定的依赖项或操作系统配置，而无需本地设置
  • 可重现性 — 跨团队的一致执行环境
有关设置、供应商和文件传输 API，请参阅沙盒。

​
人工中断

约束框架可以在指定的工具调用处暂停智能体执行，以允许人工审核或修改。此功能通过 interrupt_on 参数选择启用。 配置：
  • 创建智能体时将一组需要中断的工具名称传递给 create_deep_agent的interrupt_on 参数
  • 示例：interrupt_on={"edit_file": True} 会在每次编辑前暂停
  • 提示时可以提人工授权消息或修改工具输入
为什么有用：
  • 破坏性操作的安全阀门
  • 昂贵 API 调用前的用户验证
  • 交互式调试和指导

​
技能

约束框架支持为您的deep agent提供专门工作流程和领域知识的技能。 工作原理：
  • 技能遵循 Agent Skills 标准
  • 每个技能是一个目录，目录下包含一个带有指令和元数据的 SKILL.md 文件
  • 技能可以包含附加脚本、参考文档、模板和其他资源
  • 技能使用渐进式加载——它们只在智能体确定对当前任务有用时才加载
  • 智能体在启动时从每个 SKILL.md 文件读取 frontmatter，然后在需要时查看完整技能内容
为什么有用：
  • 通过仅在需要时加载相关技能来减少Token使用
  • 将能力捆绑到具有附加上下文的大操作中
  • 提供专门的专业知识，而不使系统提示混乱
  • 实现模块化、可重用的智能体能力
更多信息，请参阅技能。

​
记忆

约束框架支持持久化记忆文件，为您的deep agent提供跨对话的额外上下文。 这些文件通常包含通用的编码风格、偏好、约定和指南，其中的指南能够帮助智能体了解如何与你的代码库协同工作，并遵循您的偏好。 工作原理：
  • 使用AGENTS.md 文件提供持久化上下文
  • 记忆文件总是加载的（与使用渐进式加载的技能不同）
  • 创建智能体时将一个或多个文件路径传递给 memory 参数
  • 文件存储在智能体的后端（StateBackend、StoreBackend 或 FilesystemBackend）中
  • 智能体可以根据您的交互、反馈和识别的模式更新记忆
为什么有用：
  • 提供不需要在每次对话中重新指定的持久化上下文
  • 存储用户偏好、项目指南或领域知识很有用
  • 始终对智能体可用，确保一致的行为
有关配置详情和示例，请参阅记忆。
在 GitHub 上编辑此页面 或提交问题。
通过 MCP 将这些文档 连接到 Claude、VSCode 等，获取实时答案。