> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 框架能力

智能体框架是多种能力的组合，使构建长时间运行的智能体变得更加容易：

* [规划能力](#planning-capabilities)
* [虚拟文件系统](#virtual-filesystem-access)
* [文件系统权限](#filesystem-permissions)
* [任务委托（子智能体）](#task-delegation-subagents)
* [上下文和 Token 管理](#context-management)
* [代码执行](#code-execution)
* [人机协作](#human-in-the-loop)
* [框架配置文件](#harness-profiles)

除了这些能力之外，深度智能体还使用[技能](#skills)和[记忆](#memory)来提供额外的上下文和指令。

<img src="https://mintcdn.com/nvd-54/u9mURd9IHXggg6bM/oss/images/deepagents/production/open-harness.png?fit=max&auto=format&n=u9mURd9IHXggg6bM&q=85&s=cbb40beb074755d0436ec5824c8bbccf" alt="深度智能体开放框架：规划、虚拟文件系统、权限、子智能体、上下文管理、代码执行、人机协作、技能和记忆" width="673" height="424" data-path="oss/images/deepagents/production/open-harness.png" />

## 规划能力

框架提供了 `write_todos` 工具，智能体可以使用它来维护结构化的任务列表。

**功能特性：**

* 跟踪多个任务及其状态（`'pending'`、`'in_progress'`、`'completed'`）
* 持久化在智能体状态中
* 帮助智能体组织复杂的多步骤工作
* 适用于长时间运行的任务和规划

## 虚拟文件系统访问

框架提供可配置的虚拟文件系统，可以由不同的可插拔后端支持。
后端支持以下文件系统操作：

| 工具           | 描述                                                                    |
| ------------ | --------------------------------------------------------------------- |
| `ls`         | 列出目录中的文件及元数据（大小、修改时间）                                                 |
| `read_file`  | 读取文件内容（带行号），支持大文件的偏移/限制。还支持返回非文本文件（图片、视频、音频和文档）的多模态内容块。请参阅下方支持的扩展名列表。 |
| `write_file` | 创建新文件                                                                 |
| `edit_file`  | 在文件中执行精确的字符串替换（支持全局替换模式）                                              |
| `glob`       | 查找匹配模式的文件（例如 `**/*.py`）                                               |
| `grep`       | 搜索文件内容，支持多种输出模式（仅文件名、带上下文的内容、或计数）                                     |
| `execute`    | 在环境中运行 shell 命令（仅在[沙箱后端](/oss/javascript/deepagents/sandboxes)中可用）    |

<Accordion title="支持的多模态文件扩展名">
  | 类型                                                  | 扩展名                                                               |
  | --------------------------------------------------- | ----------------------------------------------------------------- |
  | [图片](/oss/javascript/langchain/messages#multimodal) | `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.heic`、`.heif`              |
  | [视频](/oss/javascript/langchain/messages#multimodal) | `.mp4`、`.mpeg`、`.mov`、`.avi`、`.flv`、`.mpg`、`.webm`、`.wmv`、`.3gpp` |
  | [音频](/oss/javascript/langchain/messages#multimodal) | `.wav`、`.mp3`、`.aiff`、`.aac`、`.ogg`、`.flac`                       |
  | [文件](/oss/javascript/langchain/messages#multimodal) | `.pdf`、`.ppt`、`.pptx`                                             |
</Accordion>

<Accordion title="不使用默认文件系统工具运行" icon="ban">
  要对模型隐藏上述文件系统工具，请注册一个带有 `excluded_tools` 的[框架配置文件](#harness-profiles)：

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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` 工具，请参阅[不使用子智能体运行](/oss/javascript/deepagents/subagents#running-without-subagents)。
</Accordion>

虚拟文件系统被多个其他框架能力使用，如技能、记忆、代码执行和上下文管理。
你还可以在为深度智能体构建自定义工具和中间件时使用文件系统。

更多信息请参阅[后端](/oss/javascript/deepagents/backends)。

## 文件系统权限

框架支持声明式权限规则，控制智能体可以读写哪些文件和目录。权限适用于上述列出的内置文件系统工具，并按声明顺序以先匹配优先的语义进行评估。

**工作原理：**

* 创建智能体时传入 `permissions=` 规则列表
* 每条规则指定 `operations`（`"read"`、`"write"`）、`paths`（glob 模式）和 `mode`（`"allow"` 或 `"deny"`）
* 第一条匹配的规则生效。如果没有规则匹配，则允许操作。

**实用场景：**

* 将智能体限制在特定目录（例如 `/workspace/`）
* 保护敏感文件（例如 `.env`、凭据）
* 给子智能体比父智能体更窄的访问权限

权限不适用于[沙箱后端](/oss/javascript/deepagents/sandboxes)，因为沙箱通过 `execute` 工具支持任意命令执行。有关自定义验证逻辑，请使用[后端策略钩子](/oss/javascript/deepagents/backends#add-policy-hooks)。

完整规则结构、示例和子智能体继承请参阅[权限](/oss/javascript/deepagents/permissions)。

## 任务委托（子智能体）

框架允许主智能体为隔离的多步骤任务创建临时"子智能体"。

**实用场景：**

* **上下文隔离** - 子智能体的工作不会干扰主智能体的上下文
* **并行执行** - 多个子智能体可以同时运行
* **专业化** - 子智能体可以有不同的工具/配置
* **Token 效率** - 大型子任务上下文被压缩为单个结果

**工作原理：**

* 主智能体有一个 `task` 工具
* 调用时，创建一个拥有自己上下文的新智能体实例
* 子智能体自主执行直到完成
* 向主智能体返回单个最终报告
* 子智能体是无状态的（不能发送多条消息回去）

**默认子智能体：**

* "general-purpose"子智能体自动可用
* 默认拥有文件系统工具
* 可以使用额外的工具/中间件进行自定义

**自定义子智能体：**

* 定义具有特定工具的专业子智能体
* 示例：代码审查器、网络研究员、测试运行器
* 通过 `subagents` 参数配置

<Accordion title="不使用子智能体运行（无 `task` 工具）" icon="ban">
  要不使用 `task` 工具运行智能体，请参阅[不使用子智能体运行](/oss/javascript/deepagents/subagents#running-without-subagents)。不要尝试通过 `excluded_middleware` 移除 `SubAgentMiddleware`——这会被故意拒绝。相反，通过[框架配置文件](#harness-profiles)禁用自动添加的子智能体，并且不要通过 `subagents=` 传入同步子智能体。异步子智能体不受影响。
</Accordion>

## 上下文管理

框架管理上下文，使深度智能体能够在 Token 限制内处理长时间运行的任务，同时保留所需信息。

**工作原理：**

* **输入上下文** — 系统提示、记忆、技能和工具提示塑造智能体启动时的认知
* **压缩** — 内置的卸载和摘要功能在任务推进时将上下文保持在窗口限制内
* **隔离** — 子智能体隔离繁重工作并仅返回结果（参见[任务委托](#task-delegation-subagents)）
* **长期记忆** — 通过虚拟文件系统实现跨线程的持久化存储

**实用场景：**

* 支持超出单个上下文窗口的多步骤任务
* 在不需要手动裁剪的情况下保留最相关的信息
* 通过自动摘要和卸载减少 Token 使用量

配置详情请参阅[上下文工程](/oss/javascript/deepagents/context-engineering)。

## 代码执行

深度智能体以两种方式支持代码执行：

* [沙箱后端](/oss/javascript/deepagents/sandboxes)暴露一个 `execute` 工具，用于在隔离环境中运行 shell 命令。
* [解释器](/oss/javascript/deepagents/interpreters)添加一个 `eval` 工具，在受限的 QuickJS 运行时中运行 JavaScript。

当智能体需要安装依赖、运行测试、调用 CLI 或使用操作系统文件系统时，请使用沙箱后端。沙箱后端实现了 `SandboxBackendProtocolV2`；当检测到时，框架会将 `execute` 工具添加到智能体的可用工具中。

当智能体需要轻量级的可编程层来处理循环、批量操作、确定性数据转换或程序化工具调用时，请使用解释器。解释器不提供 shell 访问、包安装或文件系统和网络访问。

有关沙箱设置、提供商和文件传输 API，请参阅[沙箱](/oss/javascript/deepagents/sandboxes)。有关 QuickJS 运行时和程序化工具调用，请参阅[解释器](/oss/javascript/deepagents/interpreters)。

## 人机协作

框架可以在指定的工具调用处暂停智能体执行，以允许人工审批或修改。此功能通过 `interrupt_on` 参数选择性启用。

**配置：**

* 将 `interrupt_on` 传入 `create_deep_agent`，包含工具名称到中断配置的映射
* 示例：`interrupt_on={"edit_file": True}` 在每次编辑前暂停
* 你可以在提示时提供审批消息或修改工具输入

**实用场景：**

* 破坏性操作的安全门
* 昂贵 API 调用前的用户验证
* 交互式调试和指导

## 技能

框架支持为深度智能体提供专业工作流和领域知识的技能。

**工作原理：**

* 技能遵循 [Agent Skills 标准](https://agentskills.io/)
* 每个技能是一个包含 `SKILL.md` 文件的目录，其中有指令和元数据
* 技能可以包含额外的脚本、参考文档、模板和其他资源
* 技能使用渐进式披露——只在智能体确定它们对当前任务有用时才加载
* 智能体在启动时读取每个 `SKILL.md` 文件的 frontmatter，然后在需要时查看完整技能内容

**实用场景：**

* 通过仅在需要时加载相关技能来减少 Token 使用量
* 将能力捆绑在一起形成更大的操作，并带有额外上下文
* 提供专业知识而不干扰系统提示
* 支持模块化、可复用的智能体能力

更多信息请参阅[技能](/oss/javascript/deepagents/skills)。

## 记忆

框架支持持久化记忆文件，为你的深度智能体跨对话提供额外上下文。
这些文件通常包含通用的编码风格、偏好、约定和指南，帮助智能体了解如何使用你的代码库并遵循你的偏好。

**工作原理：**

* 使用 [`AGENTS.md` 文件](https://agents.md/)提供持久化上下文
* 记忆文件始终被加载（不像技能那样使用渐进式披露）
* 创建智能体时将一个或多个文件路径传入 `memory` 参数
* 文件存储在智能体的后端（StateBackend、StoreBackend 或 FilesystemBackend）
* 智能体可以根据你的交互、反馈和识别的模式来更新记忆

**实用场景：**

* 提供不需要每次对话重新指定的持久化上下文
* 适用于存储用户偏好、项目指南或领域知识
* 始终对智能体可用，确保一致的行为

配置详情和示例请参阅[记忆](/oss/javascript/deepagents/customization#memory)。

## 框架配置文件

框架可以在选择给定提供商或模型时应用声明式配置包（`HarnessProfile`）。配置文件在模型构建完成后调整运行时行为，无需每个智能体单独的设置代码。

**工作原理：**

* 在提供商名称（`"openai"`）或 `provider:model` 键（`"openai:gpt-5.4"`）下注册配置文件
* `create_deep_agent` 在解析模型时查找并应用配置文件
* 提供商级别和模型级别的配置文件在解析时合并

**实用场景：**

* 将每个提供商或每个模型的默认设置（系统提示调整、工具覆盖、中间件）打包在一个地方
* 切换模型时保持 `create_deep_agent` 调用处不变
* 通过入口点将可复用的配置文件作为插件发布

完整字段列表、合并语义和插件打包请参阅[配置文件](/oss/javascript/deepagents/profiles)。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时解答。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/harness.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>