Skip to main content
Agent Harness 结合了多种不同的功能，使构建长期运行的代理变得更加容易： 除了这些功能外，Deep Agents 还使用 技能 和 记忆 来获取额外的上下文和指令。

​
规划功能

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

​
虚拟文件系统访问

Harness 提供了一个可配置的虚拟文件系统，该系统可以由不同的可插拔后端支持。 这些后端支持以下文件系统操作：
工具描述
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
虚拟文件系统被其他几个 Harness 功能使用，例如技能、记忆、代码执行和上下文管理。 你在为 Deep Agents 构建自定义工具和中间件时也可以使用文件系统。 更多信息，请参阅 后端。

​
文件系统权限

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

​
任务委托（子代理）

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

​
上下文管理

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

​
代码执行

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

​
人类介入

Harness 可以在指定的工具调用处暂停代理执行，以允许人类批准或修改。此功能通过 interrupt_on 参数 opting-in。 配置：
  • 将 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）中
  • 代理可以根据你的交互、反馈和识别出的模式更新记忆
为何有用：
  • 提供不需要在每次对话中重新指定的持久化上下文
  • 适用于存储用户偏好、项目指南或领域知识
  • 始终对代理可用，确保一致的行为
有关配置详情和示例，请参阅 记忆。
在 GitHub 上编辑此页面 或 提交问题。
连接这些文档 到 Claude、VSCode 等，通过 MCP 实现实时问答。