Skip to main content

Documentation Index

Fetch the complete documentation index at: https://nvd-54.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

智能体框架是多种能力的组合，使构建长时间运行的智能体变得更加容易： 除了这些能力之外，深度智能体还使用技能和记忆来提供额外的上下文和指令。 深度智能体开放框架：规划、虚拟文件系统、权限、子智能体、上下文管理、代码执行、人机协作、技能和记忆

​
规划能力

框架提供了 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
要对模型隐藏上述文件系统工具，请注册一个带有 excluded_tools 的框架配置文件：
from deepagents import HarnessProfile, register_harness_profile

register_harness_profile(
    "anthropic:claude-sonnet-4-6",
    HarnessProfile(
        excluded_tools=frozenset(
            {"ls", "read_file", "write_file", "edit_file", "glob", "grep"}
        ),
    ),
)
通过 excluded_middleware 移除 FilesystemMiddleware 本身会被故意拒绝——使用 excluded_tools 仅隐藏模型可见的工具表面，同时保留中间件不变。要移除 task 工具，请参阅不使用子智能体运行。
虚拟文件系统被多个其他框架能力使用，如技能、记忆、代码执行和上下文管理。 你还可以在为深度智能体构建自定义工具和中间件时使用文件系统。 更多信息请参阅后端。

​
文件系统权限

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

​
任务委托（子智能体）

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

​
上下文管理

框架管理上下文，使深度智能体能够在 Token 限制内处理长时间运行的任务，同时保留所需信息。 工作原理：
  • 输入上下文 — 系统提示、记忆、技能和工具提示塑造智能体启动时的认知
  • 压缩 — 内置的卸载和摘要功能在任务推进时将上下文保持在窗口限制内
  • 隔离 — 子智能体隔离繁重工作并仅返回结果（参见任务委托）
  • 长期记忆 — 通过虚拟文件系统实现跨线程的持久化存储
实用场景：
  • 支持超出单个上下文窗口的多步骤任务
  • 在不需要手动裁剪的情况下保留最相关的信息
  • 通过自动摘要和卸载减少 Token 使用量
配置详情请参阅上下文工程。

​
代码执行

深度智能体以两种方式支持代码执行：
  • 沙箱后端暴露一个 execute 工具，用于在隔离环境中运行 shell 命令。
  • 解释器添加一个 eval 工具，在受限的 QuickJS 运行时中运行 JavaScript。
当智能体需要安装依赖、运行测试、调用 CLI 或使用操作系统文件系统时，请使用沙箱后端。沙箱后端实现了 SandboxBackendProtocolV2；当检测到时，框架会将 execute 工具添加到智能体的可用工具中。 当智能体需要轻量级的可编程层来处理循环、批量操作、确定性数据转换或程序化工具调用时，请使用解释器。解释器不提供 shell 访问、包安装或文件系统和网络访问。 有关沙箱设置、提供商和文件传输 API，请参阅沙箱。有关 QuickJS 运行时和程序化工具调用，请参阅解释器。

​
人机协作

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

​
技能

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

​
记忆

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

​
框架配置文件

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