> ## 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. # Harness 能力 智能体 Harness 是多种不同能力的组合，使构建长时间运行的智能体更加容易： * [规划能力](#planning-capabilities) * [虚拟文件系统](#virtual-filesystem-access) * [文件系统权限](#filesystem-permissions) * [任务委派（子智能体）](#task-delegation-subagents) * [上下文和 Token 管理](#context-management) * [代码执行](#code-execution) * [人机协作](#human-in-the-loop) * [Harness 配置](#harness-profiles) 除了这些能力，深度智能体还使用[技能](#skills)和[记忆](#memory)来获取额外的上下文和指令。 深度智能体开放 Harness：规划、虚拟文件系统、权限、子智能体、上下文管理、代码执行、人机协作、技能和记忆 ## 规划能力 Harness 提供了一个 `write_todos` 工具，智能体可以用它来维护结构化的任务列表。 **特性：** * 使用状态（`'pending'`、`'in_progress'`、`'completed'`）跟踪多个任务 * 持久化在智能体状态中 * 帮助智能体组织复杂的多步骤工作 * 适用于长时间运行的任务和规划 ## 虚拟文件系统访问 Harness 提供了一个可配置的虚拟文件系统，可以由不同的可插拔后端支撑。后端支持以下文件系统操作： | 工具 | 说明 | | ------------ | --------------------------------------------------------------------------- | | `ls` | 列出目录中的文件及其元数据（大小、修改时间） | | `read_file` | 读取带行号的文件内容，支持 offset/limit 处理大文件。还支持返回非文本文件（图片、视频、音频和文档）的多模态内容块。参见下方支持的扩展名。 | | `write_file` | 创建新文件 | | `edit_file` | 在文件中执行精确的字符串替换（支持全局替换模式） | | `glob` | 查找匹配模式的文件（如 `**/*.py`） | | `grep` | 搜索文件内容，支持多种输出模式（仅文件名、带上下文的内容或计数） | | `execute` | 在环境中运行 Shell 命令（仅在使用[沙箱后端](/oss/python/deepagents/sandboxes)时可用） | | 类型 | 扩展名 | | ----------------------------------------------- | ----------------------------------------------------------------- | | [图片](/oss/python/langchain/messages#multimodal) | `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.heic`、`.heif` | | [视频](/oss/python/langchain/messages#multimodal) | `.mp4`、`.mpeg`、`.mov`、`.avi`、`.flv`、`.mpg`、`.webm`、`.wmv`、`.3gpp` | | [音频](/oss/python/langchain/messages#multimodal) | `.wav`、`.mp3`、`.aiff`、`.aac`、`.ogg`、`.flac` | | [文件](/oss/python/langchain/messages#multimodal) | `.pdf`、`.ppt`、`.pptx` | 要对模型隐藏上面列出的文件系统工具，注册一个带有 `excluded_tools` 的 [Harness 配置](#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/python/deepagents/subagents#running-without-subagents)。 虚拟文件系统被多个其他 Harness 能力使用，如技能、记忆、代码执行和上下文管理。你还可以在为深度智能体构建自定义工具和中间件时使用文件系统。 更多信息请参阅[后端](/oss/python/deepagents/backends)。 ## 文件系统权限 Harness 支持声明式权限规则，控制智能体可以读写的文件和目录。权限适用于上面列出的内置文件系统工具，按声明顺序评估，采用首次匹配生效的语义。 **工作原理：** * 创建智能体时将规则列表传递给 `permissions=` * 每条规则指定 `operations`（`"read"`、`"write"`）、`paths`（glob 模式）和 `mode`（`"allow"` 或 `"deny"`） * 首条匹配的规则生效。如果没有规则匹配，操作被允许。 **为什么有用：** * 限制智能体到特定目录（如 `/workspace/`） * 保护敏感文件（如 `.env`、凭证） * 给子智能体比父智能体更窄的访问权限 权限不适用于[沙箱后端](/oss/python/deepagents/sandboxes)，后者通过 `execute` 工具支持任意命令执行。对于自定义验证逻辑，使用[后端策略钩子](/oss/python/deepagents/backends#add-policy-hooks)。 有关完整的规则结构、示例和子智能体继承，请参阅[权限](/oss/python/deepagents/permissions)。 ## 任务委派（子智能体） Harness 允许主智能体创建临时"子智能体"来处理隔离的多步骤任务。 **为什么有用：** * **上下文隔离** - 子智能体的工作不会使主智能体的上下文混乱 * **并行执行** - 多个子智能体可以并发运行 * **专门化** - 子智能体可以有不同的工具/配置 * **Token 效率** - 大型子任务上下文被压缩为单个结果 **工作原理：** * 主智能体有一个 `task` 工具 * 调用时，它创建一个拥有自己上下文的全新智能体实例 * 子智能体自主执行直到完成 * 向主智能体返回单个最终报告 * 子智能体是无状态的（不能发送多条消息回来） **默认子智能体：** * "通用"子智能体自动可用 * 默认拥有文件系统工具 * 可以用额外的工具/中间件自定义 **自定义子智能体：** * 定义带有特定工具的专门子智能体 * 示例：代码审查员、网络研究员、测试运行器 * 通过 `subagents` 参数配置 要运行没有 `task` 工具的智能体，参见[不使用子智能体运行](/oss/python/deepagents/subagents#running-without-subagents)。不要试图通过 `excluded_middleware` 移除 `SubAgentMiddleware`——这会被故意拒绝。而是通过 [Harness 配置](#harness-profiles)禁用自动添加的子智能体，并通过 `subagents=` 不传递同步子智能体。异步子智能体不受影响。 ## 上下文管理 Harness 管理上下文，使深度智能体能够在 Token 限制内处理长时间运行的任务，同时保留所需的信息。 **工作原理：** * **输入上下文** — 系统提示词、记忆、技能和工具提示词塑造智能体在启动时所知道的内容 * **压缩** — 内置的卸载和摘要在任务进行时保持上下文在窗口限制内 * **隔离** — 子智能体隔离繁重工作并仅返回结果（参见[任务委派](#task-delegation-subagents)） * **长期记忆** — 通过虚拟文件系统实现跨线程的持久存储 **为什么有用：** * 支持超过单个上下文窗口的多步骤任务 * 保持最相关的信息在范围内，无需手动裁剪 * 通过自动摘要和卸载减少 Token 使用 有关配置详情，请参阅[上下文工程](/oss/python/deepagents/context-engineering)。 ## 代码执行 深度智能体以两种方式支持代码执行： * [沙箱后端](/oss/python/deepagents/sandboxes)暴露 `execute` 工具用于在隔离环境中执行 Shell 命令。 * [解释器](/oss/python/deepagents/interpreters)添加 `eval` 工具在限定范围的 QuickJS 运行时中运行 JavaScript。 当智能体需要安装依赖、运行测试、调用 CLI 或使用操作系统文件系统时，使用沙箱后端。沙箱后端实现 `SandboxBackendProtocolV2`；检测到时，Harness 会将 `execute` 工具添加到智能体的可用工具中。 当智能体需要轻量级的可编程层用于循环、批处理、确定性数据转换或程序化工具调用时，使用解释器。解释器不提供 Shell 访问、包安装或文件系统和网络访问。 有关沙箱设置、提供商和文件传输 API，请参阅[沙箱](/oss/python/deepagents/sandboxes)。有关 QuickJS 运行时和程序化工具调用，请参阅[解释器](/oss/python/deepagents/interpreters)。 ## 人机协作 Harness 可以在指定的工具调用处暂停智能体执行，以允许人工批准或修改。此功能通过 `interrupt_on` 参数选择启用。 **配置：** * 将 `interrupt_on` 传递给 `create_deep_agent`，包含工具名称到中断配置的映射 * 示例：`interrupt_on={"edit_file": True}` 在每次编辑前暂停 * 提示时你可以提供批准消息或修改工具输入 **为什么有用：** * 破坏性操作的安全门 * 昂贵 API 调用前的用户验证 * 交互式调试和指导 ## 技能 Harness 支持技能，为深度智能体提供专门的工作流和领域知识。 **工作原理：** * 技能遵循 [Agent Skills 标准](https://agentskills.io/) * 每个技能是一个包含带有指令和元数据的 `SKILL.md` 文件的目录 * 技能可以包含额外的脚本、参考文档、模板和其他资源 * 技能使用渐进式披露——仅在智能体确定它们对当前任务有用时才加载 * 智能体在启动时读取每个 `SKILL.md` 文件的 frontmatter，然后在需要时审查完整的技能内容 **为什么有用：** * 仅在需要时加载相关技能，减少 Token 使用 * 将能力捆绑到具有额外上下文的更大操作中 * 提供专门的专业知识而不使系统提示词混乱 * 实现模块化、可复用的智能体能力 更多信息请参阅[技能](/oss/python/deepagents/skills)。 ## 记忆 Harness 支持持久记忆文件，为深度智能体跨对话提供额外上下文。这些文件通常包含通用编码风格、偏好、约定和指南，帮助智能体理解如何使用你的代码库和遵循你的偏好。 **工作原理：** * 使用 [`AGENTS.md` 文件](https://agents.md/)提供持久上下文 * 记忆文件始终加载（不同于使用渐进式披露的技能） * 创建智能体时将一个或多个文件路径传递给 `memory` 参数 * 文件存储在智能体的后端（StateBackend、StoreBackend 或 FilesystemBackend） * 智能体可以根据你的交互、反馈和识别的模式更新记忆 **为什么有用：** * 提供不需要每次对话重新指定的持久上下文 * 适合存储用户偏好、项目指南或领域知识 * 对智能体始终可用，确保行为一致 有关配置详情和示例，请参阅[记忆](/oss/python/deepagents/customization#memory)。 ## Harness 配置 Harness 可以在选择给定的提供商或模型时应用声明式配置包（`HarnessProfile`）。配置在模型构建后调整运行时行为，无需按智能体的设置代码。 **工作原理：** * 在提供商名称（`"openai"`）或 `provider:model` 键（`"openai:gpt-5.4"`）下注册配置 * `create_deep_agent` 在解析模型时查找并应用配置 * 提供商级别和模型级别的配置在解析时合并 **为什么有用：** * 在一个地方封装按提供商或按模型的默认值（系统提示词调整、工具覆盖、中间件） * 切换模型时保持 `create_deep_agent` 调用处不变 * 通过入口点将可复用的配置作为插件发布 有关完整的字段列表、合并语义和插件打包，请参阅[配置](/oss/python/deepagents/profiles)。 ***
[连接这些文档](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/harness.mdx) 或[提交 Issue](https://github.com/langchain-ai/docs/issues/new/choose)。