Skip to main content
代理框架是多种不同能力的组合，使构建长时间运行的代理更加容易： 除了这些能力，Deep Agents 还使用技能和记忆来获取额外的上下文和指令。 Deep Agents 开放框架：规划、虚拟文件系统、权限、子代理、上下文管理、代码执行、Human in the Loop、技能和记忆

​
规划能力

框架提供了一个 write_todos 工具，代理可以使用它来维护结构化的任务列表。 功能：
  • 跟踪多个任务及其状态（'pending'、'in_progress'、'completed'）
  • 持久化存储在代理状态中
  • 帮助代理组织复杂的多步骤工作
  • 适用于长时间运行的任务和规划

​
虚拟文件系统访问

框架提供了一个可配置的虚拟文件系统，可以由不同的可插拔后端支持。 后端支持以下文件系统操作：
虚拟文件系统被其他几个框架能力使用，例如技能、记忆、代码执行和上下文管理。 在为 Deep Agents 构建自定义工具和中间件时，您也可以使用文件系统。 更多信息，请参阅后端。

​
文件系统权限

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

​
任务委派（子代理）

框架允许主代理创建临时的“子代理”来处理隔离的多步骤任务。 为何有用：
  • 上下文隔离 - 子代理的工作不会使主代理的上下文变得混乱
  • 并行执行 - 多个子代理可以并发运行
  • 专业化 - 子代理可以拥有不同的工具/配置
  • 令牌效率 - 大型子任务上下文被压缩为单个结果
工作原理：
  • 主代理有一个 task 工具
  • 调用时，它会创建一个具有自己上下文的新代理实例
  • 子代理自主执行直到完成
  • 向主代理返回单个最终报告
  • 子代理是无状态的（无法发回多条消息）
默认子代理：
  • “通用”子代理自动可用
  • 默认具有文件系统工具
  • 可以通过额外的工具/中间件进行自定义
自定义子代理：
  • 使用特定工具定义专门的子代理
  • 示例：代码审查员、网络研究员、测试运行器
  • 通过 subagents 参数进行配置
要在不使用 task 工具的情况下运行代理，请参阅不使用子代理运行。不要尝试通过 excluded_middleware 移除 SubAgentMiddleware——这会被有意拒绝。相反，请通过框架配置文件禁用自动添加的子代理，并且不要通过 subagents= 传递同步子代理。异步子代理不受影响。

​
上下文管理

框架管理上下文，使 Deep Agents 能够在令牌限制内处理长时间运行的任务，同时保留所需的信息。 工作原理：
  • 输入上下文 — 系统提示、记忆、技能和工具提示塑造了代理在启动时所知的内容
  • 压缩 — 内置的卸载和摘要功能在任务进行时将上下文保持在窗口限制内
  • 隔离 — 子代理隔离繁重的工作并仅返回结果（参见任务委派）
  • 长期记忆 — 通过虚拟文件系统跨线程持久存储
为何有用：
  • 支持超出单个上下文窗口的多步骤任务
  • 无需手动修剪即可将最相关的信息保留在范围内
  • 通过自动摘要和卸载减少令牌使用量
有关配置详情，请参阅上下文工程。

​
代码执行

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

​
Human in the Loop

框架可以在指定的工具调用处暂停代理执行，以允许人工批准或修改。此功能通过 interrupt_on 参数选择启用。 配置：
  • 将 interrupt_on 传递给 create_deep_agent，其中包含工具名称到中断配置的映射
  • 示例：interrupt_on={"edit_file": True} 会在每次编辑前暂停
  • 在提示时，您可以提供批准消息或修改工具输入
为何有用：
  • 破坏性操作的安全门
  • 在昂贵的 API 调用前进行用户验证
  • 交互式调试和指导

​
技能

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

​
记忆

框架支持持久化记忆文件，为您的 Deep Agent 在对话中提供额外的上下文。 这些文件通常包含通用的编码风格、偏好、约定和指南，帮助代理了解如何与您的代码库协作并遵循您的偏好。 工作原理：
  • 使用 AGENTS.md 文件提供持久化上下文
  • 记忆文件始终加载（与使用渐进式披露的技能不同）
  • 创建代理时，将一个或多个文件路径传递给 memory 参数
  • 文件存储在代理的后端（StateBackend、StoreBackend 或 FilesystemBackend）
  • 代理可以根据您的交互、反馈和识别的模式更新记忆
为何有用：
  • 提供无需在每次对话中重新指定的持久化上下文
  • 适用于存储用户偏好、项目指南或领域知识
  • 始终可供代理使用，确保行为一致
有关配置详情和示例，请参阅记忆。

​
框架配置文件

当选择给定的提供者或模型时，框架可以应用声明式配置包（HarnessProfile）。配置文件在模型构建后调整运行时行为，无需每个代理的设置代码。 工作原理：
  • 在提供者名称（"openai"）或 provider:model 键（"openai:gpt-5.4"）下注册配置文件
  • create_deep_agent 在解析模型时查找并应用配置文件
  • 提供者级别和模型级别的配置文件在解析时合并
为何有用：
  • 将每个提供者或每个模型的默认值（系统提示调整、工具覆盖、中间件）打包在一个地方
  • 切换模型时保持 create_deep_agent 调用点不变
  • 通过入口点将可重用的配置文件作为插件发布
有关完整的字段列表、合并语义和插件打包，请参阅配置文件。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。