Skip to main content
An agent harness 是多种不同能力的组合，使构建长期运行的代理变得更加容易： 除了这些能力之外，Deep Agents 还使用 Skills 和 Memory 来获取额外的上下文和指令。

​
规划能力

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

​
虚拟文件系统访问

Harness 提供了一个可配置的虚拟文件系统，可以由不同的可插拔后端支持。 后端支持以下文件系统操作：
工具描述
ls列出目录中的文件及其元数据（大小、修改时间）
read_file读取文件内容（带行号），支持大文件的偏移/限制。还支持为非文本文件（图像、视频、音频和文档）返回多模态内容块。参见下面支持的扩展名。
write_file创建新文件
edit_file在文件中执行精确的字符串替换（支持全局替换模式）
glob查找匹配模式的文件（例如 **/*.py）
grep搜索文件内容，支持多种输出模式（仅文件、带上下文的内容或计数）
execute在环境中运行 shell 命令（仅在 sandbox 后端 中可用）
类型扩展名
图像.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
虚拟文件系统被 Harness 的其他几个能力使用，例如技能、内存、代码执行和上下文管理。 您也可以在构建 Deep Agents 的自定义工具和中间件时使用文件系统。 更多信息，请参见 后端。

​
文件系统权限

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

​
任务委托（子代理）

Harness 允许主代理创建临时的“子代理”用于隔离的多步骤任务。 为什么有用：
  • 上下文隔离 - 子代理的工作不会干扰主代理的上下文
  • 并行执行 - 多个子代理可以同时运行
  • 专业化 - 子代理可以具有不同的工具/配置
  • 令牌效率 - 大型子任务上下文被压缩为单个结果
工作原理：
  • 主代理有一个 task 工具
  • 调用时，它会创建一个具有自己上下文的新代理实例
  • 子代理自主执行直到完成
  • 向主代理返回单个最终报告
  • 子代理是无状态的（无法发送多条消息返回）
默认子代理：
  • “通用”子代理自动可用
  • 默认具有文件系统工具
  • 可以使用额外的工具/中间件进行自定义
自定义子代理：
  • 定义具有特定工具的专用子代理
  • 示例：代码审查器、网络研究员、测试运行器
  • 通过 subagents 参数配置

​
上下文管理

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

​
代码执行

当您使用 sandbox 后端 时，Harness 会暴露一个 execute 工具，允许代理在隔离环境中运行 shell 命令。这使得代理能够安装依赖项、运行脚本并执行代码作为其任务的一部分。 工作原理：
  • Sandbox 后端实现 SandboxBackendProtocolV2 — 当检测到时，Harness 会将 execute 工具添加到代理的可用工具中
  • 如果没有 sandbox 后端，代理只有文件系统工具（read_file、write_file 等），无法运行命令
  • execute 工具返回组合的 stdout/stderr、退出码，并截断大输出（保存到文件供代理增量读取）
为什么有用：
  • 安全性 — 代码在隔离环境中运行，保护您的主机系统免受代理操作的影响
  • 干净的环境 — 使用特定的依赖项或操作系统配置，无需本地设置
  • 可重现性 — 跨团队一致的执行环境
有关设置、提供程序和文件传输 API，请参见 Sandbox。

​
人机回环

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

​
技能

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

​
内存

Harness 支持持久化内存文件，为您的 Deep Agent 在对话中提供额外的上下文。 这些文件通常包含通用编码风格、偏好、约定和指南，帮助代理了解如何与您的代码库协作并遵循您的偏好。 工作原理：
  • 使用 AGENTS.md 文件 提供持久化上下文
  • 内存文件始终加载（与技能不同，技能使用渐进式披露）
  • 在创建代理时，将一个或多个文件路径传递给 memory 参数
  • 文件存储在代理的后端（StateBackend、StoreBackend 或 FilesystemBackend）
  • 代理可以根据您的交互、反馈和识别的模式更新内存
为什么有用：
  • 提供持久化上下文，无需在每次对话中重新指定
  • 用于存储用户偏好、项目指南或领域知识
  • 始终对代理可用，确保行为一致
有关配置详情和示例，请参见 内存。
在 GitHub 上编辑此页面 或 提交问题。
连接这些文档 到 Claude、VSCode 等，通过 MCP 获取实时答案。