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

​
规划能力

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

​
虚拟文件系统访问

框架提供了一个可配置的虚拟文件系统，可以由不同的可插拔后端支持。 后端支持以下文件系统操作：
工具描述
ls列出目录中的文件及其元数据（大小、修改时间）
read_file读取文件内容并显示行号，支持偏移量/限制以处理大文件。还支持为非文本文件（图像、视频、音频和文档）返回多模态内容块。请参阅下方支持的扩展名。
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 工具执行任意命令。对于自定义验证逻辑，请使用后端策略钩子。 有关完整的规则结构、示例和子代理继承，请参阅权限。

​
任务委派（子代理）

框架允许主代理创建临时的“子代理”来处理隔离的多步骤任务。 为何有用：
  • 上下文隔离 - 子代理的工作不会使主代理的上下文变得混乱
  • 并行执行 - 多个子代理可以并发运行
  • 专业化 - 子代理可以拥有不同的工具/配置
  • 令牌效率 - 大型子任务上下文被压缩为单个结果
工作原理：
  • 主代理有一个 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 上编辑此页面 或 提交问题。