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.

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

​
规划能力

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

​
虚拟文件系统访问

Harness 提供了一个可配置的虚拟文件系统，可以由不同的可插拔后端支撑。后端支持以下文件系统操作：
工具说明
ls列出目录中的文件及其元数据（大小、修改时间）
read_file读取带行号的文件内容，支持 offset/limit 处理大文件。还支持返回非文本文件（图片、视频、音频和文档）的多模态内容块。参见下方支持的扩展名。
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 的 Harness 配置：
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 工具，参见不使用子智能体运行。
虚拟文件系统被多个其他 Harness 能力使用，如技能、记忆、代码执行和上下文管理。你还可以在为深度智能体构建自定义工具和中间件时使用文件系统。 更多信息请参阅后端。

​
文件系统权限

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

​
任务委派（子智能体）

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

​
上下文管理

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

​
代码执行

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

​
人机协作

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

​
技能

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

​
记忆

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

​
Harness 配置

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